Package {fz}

Type:	Package
Title:	R Wrapper for the 'funz-fz' Parametric Simulation Framework
Version:	1.1
Description:	Provides R bindings to the 'funz-fz' Python package using 'reticulate'. The 'fz' framework wraps arbitrary simulation codes to run parameter sweeps, design-of-experiments studies, and iterative algorithm-driven analyses by substituting variable placeholders in text input files and collecting outputs into data frames. Calculators can run locally (shell), over SSH, or on 'SLURM' clusters. See https://github.com/Funz/fz for the underlying framework.
License:	BSD_3_clause + file LICENSE
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.3
SystemRequirements:	Python (>= 3.8), funz-fz Python package
Imports:	reticulate (≥ 1.28)
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown
Config/reticulate:	list( packages = list( list(package = "funz-fz") ) )
VignetteBuilder:	knitr
URL:	https://github.com/Funz/fz.R
BugReports:	https://github.com/Funz/fz.R/issues
NeedsCompilation:	no
Packaged:	2026-06-22 20:39:38 UTC; richet
Author:	Yann Richet [aut, cre]
Maintainer:	Yann Richet <yann.richet@asnr.fr>
Repository:	CRAN
Date/Publication:	2026-06-29 13:30:02 UTC

fz: R Wrapper for the 'funz-fz' Parametric Simulation Framework

Description

Provides R bindings to the 'funz-fz' Python package using 'reticulate'. The 'fz' framework wraps arbitrary simulation codes to run parameter sweeps, design-of-experiments studies, and iterative algorithm-driven analyses by substituting variable placeholders in text input files and collecting outputs into data frames. Calculators can run locally (shell), over SSH, or on 'SLURM' clusters. See https://github.com/Funz/fz for the underlying framework.

Author(s)

Maintainer: Yann Richet yann.richet@asnr.fr (ORCID)

See Also

Useful links:

• https://github.com/Funz/fz.R

• Report bugs at https://github.com/Funz/fz.R/issues

Check if fz Python Package is Available

Description

Checks whether the fz Python package is available in the current Python environment.

Usage

fz_available()

Value

Logical; TRUE if fz is available, FALSE otherwise.

Examples

if (fz_available()) {
  message("fz is available!")
} else {
  message("Please install fz with fz_install()")
}

Install the fz Python Package

Description

This function installs the fz Python package into a virtual environment or conda environment managed by reticulate.

Usage

fz_install(method = "auto", conda = "auto", pip = TRUE, ...)

Arguments

Value

NULL (invisibly). Called for side effects.

Examples

## Not run: 
# Install fz in a virtual environment
fz_install()

# Install in a conda environment
fz_install(method = "conda")

## End(Not run)

fzc Function

Description

Compiles input file(s) by replacing variable placeholders with values. Each unique combination of values is written to its own subdirectory inside output_dir, named var1=val1,var2=val2,....

Usage

fzc(input_path, input_variables, model, output_dir = "output")

Arguments

Value

NULL (invisibly). Called for side effects.

Examples

if (fz_available()) {
  tf <- tempfile(fileext = ".txt")
  writeLines(c("P = ${P~1.013}", "V = ${V~22.4}"), tf)

  model <- list(varprefix = "$", delim = "{}", formulaprefix = "@",
                commentline = "#")
  out <- tempfile()

  fzc(tf, list(P = 2.0, V = 11.2), model, out)
  fzc(tf, list(P = c(1.0, 2.0), V = c(11.2, 22.4)), model, out)
}

fzd Function

Description

Runs an iterative design of experiments driven by an algorithm. Unlike fzr (which evaluates a fixed grid), fzd lets an algorithm adaptively choose which parameter combinations to evaluate, which is useful for sensitivity analysis, surrogate-model fitting, or optimization.

Usage

fzd(
  input_path,
  input_variables,
  model,
  output_expression,
  algorithm,
  calculators = NULL,
  algorithm_options = NULL,
  analysis_dir = "analysis"
)

Arguments

Value

Named list with the analysis results produced by the algorithm.

Examples

if (fz_available()) {
  tf <- tempfile(fileext = ".txt")
  writeLines(c("x = ${x~0}", "y = ${y~0}"), tf)

  model <- list(
    varprefix = "$", delim = "{}", formulaprefix = "@", commentline = "#",
    output = list(z = "grep z output.txt | cut -d= -f2")
  )

  result <- fzd(
    tf,
    list(x = "[0;1]", y = "[-5;5]"),
    model,
    output_expression = "z",
    algorithm        = "algorithms/montecarlo_uniform.py",
    algorithm_options = "batch_sample_size=10;max_iterations=3"
  )
}

fzi Function

Description

Parses input file(s) to find variables, formulas, and static objects.

Usage

fzi(input_path, model)

Arguments

Value

Named list with variable names and their default values (or NULL).

Examples

if (fz_available()) {
  tf <- tempfile(fileext = ".txt")
  writeLines(c("pressure = ${P~1.013}", "volume = ${V~22.4}"), tf)

  model <- list(varprefix = "$", delim = "{}", formulaprefix = "@",
                commentline = "#")

  vars <- fzi(tf, model)
}

fzl Function

Description

Lists installed models and available calculators.

Usage

fzl(models = "*", calculators = "*", check = FALSE)

Arguments

Value

Named list with two entries:

models

Named list of installed model definitions.

calculators

Named list of available calculators.

Examples

if (fz_available()) {
  info <- fzl()
  names(info$models)
  names(info$calculators)

  info <- fzl(models = "Perfect*")
  info <- fzl(check = TRUE)
}

fzo Function

Description

Reads and parses output file(s) according to the model's output commands. Each matched directory is processed independently; the results are combined into a single list or data frame.

Usage

fzo(output_path, model)

Arguments

Value

Named list or data frame of parsed output values.

Examples

if (fz_available()) {
  out_dir <- file.path(tempdir(), "P=2,V=11.2")
  dir.create(out_dir, recursive = TRUE)
  writeLines("result = 42", file.path(out_dir, "output.txt"))

  model <- list(
    varprefix = "$", delim = "{}", formulaprefix = "@", commentline = "#",
    output = list(result = "grep 'result' output.txt | cut -d= -f2")
  )

  values <- fzo(out_dir, model)
}

fzr Function

Description

Runs full parametric calculations over an input template. fzr combines fzc, calculator execution, and fzo into a single call: it compiles the template for every parameter combination, runs the model via the calculator(s), and collects all outputs into a data frame.

Usage

fzr(
  input_path,
  input_variables,
  model,
  results_dir = "results",
  calculators = NULL,
  callbacks = NULL,
  timeout = NULL
)

Arguments

Value

Data frame (or named list) with one row per case and columns for each input variable and output quantity.

Examples

if (fz_available()) {
  tf <- tempfile(fileext = ".sh")
  writeLines(c(
    "#!/bin/sh",
    "echo result = $(( ${x~0} + ${y~0} )) > output.txt"
  ), tf)

  model <- list(
    varprefix = "$", delim = "{}", formulaprefix = "@", commentline = "#",
    output = list(result = "grep result output.txt | cut -d= -f2")
  )

  results <- fzr(tf, list(x = c(1L, 2L), y = 3L), model,
                 calculators = "sh://bash input.sh")
}

Get the Global Configuration

Description

Returns the fz configuration object. Values are controlled by environment variables such as FZ_LOG_LEVEL, FZ_MAX_WORKERS, FZ_MAX_RETRIES, and FZ_SHELL_PATH.

Usage

get_config()

Value

A Python Config object. Access fields with $, e.g. get_config()$max_workers.

Examples

if (fz_available()) {
  cfg <- get_config()
  cfg$max_workers
  cfg$max_retries
}

Get the Current Interpreter

Description

Returns the global formula interpreter used when evaluating formula expressions inside template files (e.g. "python" or "R").

Usage

get_interpreter()

Value

Character string naming the current interpreter.

Examples

if (fz_available()) {
  get_interpreter()
}

Get the Current Log Level

Description

Returns the current logging verbosity level.

Usage

get_log_level()

Value

A log-level value (use as.character() to convert to a string such as "DEBUG", "INFO", "WARNING", "ERROR").

Examples

if (fz_available()) {
  as.character(get_log_level())
}

Install a Model or Algorithm (generic)

Description

Generic alias: installs a model from a GitHub name, URL, or local zip file. Equivalent to install_model.

Usage

install(source, global = FALSE)

Arguments

Value

Named list with installation details.

Examples

if (fz_available()) {
  install("Funz/Model-PerfectGas")
}

Install an Algorithm

Description

Installs an algorithm from a GitHub repository name, URL, or local zip file into the user-level ~/.fz/algorithms/ directory (or system-level when global = TRUE).

Usage

install_algorithm(source, global = FALSE)

Arguments

Value

Named list with installation details (path, name, …).

Examples

if (fz_available()) {
  install_algorithm("Funz/Algorithm-MonteCarlo")
}

Install a Model

Description

Installs a model from a GitHub repository name, URL, or local zip file into the user-level ~/.fz/models/ directory (or system-level when global = TRUE).

Usage

install_model(source, global = FALSE)

Arguments

Value

Named list with installation details (path, id, …).

Examples

if (fz_available()) {
  install_model("Funz/Model-PerfectGas")
}

List Installed Algorithms

Description

Returns details of all algorithms installed in ~/.fz/algorithms/.

Usage

list_installed_algorithms(global = FALSE)

Arguments

Value

Named list of installed algorithm definitions.

Examples

if (fz_available()) {
  algos <- list_installed_algorithms()
  names(algos)
}

List Installed Models

Description

Returns details of all models installed in ~/.fz/models/.

Usage

list_installed_models(global = FALSE)

Arguments

Value

Named list of installed model definitions.

Examples

if (fz_available()) {
  models <- list_installed_models()
  names(models)
}

List Installed Models (alias)

Description

Alias for list_installed_models.

Usage

list_models(global = FALSE)

Arguments

Value

Named list of installed model definitions.

Examples

if (fz_available()) {
  names(list_models())
}

Print the Current Configuration

Description

Prints all fz configuration values in a human-readable format, including which settings come from environment variables.

Usage

print_config()

Value

NULL (invisibly). Called for side effects.

Examples

if (fz_available()) {
  print_config()
}

Reload Configuration from Environment Variables

Description

Re-reads all FZ_* environment variables and updates the live configuration. Useful after changing environment variables within the session.

Usage

reload_config()

Value

NULL (invisibly). Called for side effects.

Examples

if (fz_available()) {
  Sys.setenv(FZ_MAX_WORKERS = "8")
  reload_config()
  get_config()$max_workers
}

Set the Interpreter

Description

Sets the global formula interpreter for evaluating expressions inside template files.

Usage

set_interpreter(interpreter)

Arguments

Value

NULL (invisibly). Called for side effects.

Examples

if (fz_available()) {
  set_interpreter("R")
  set_interpreter("python")
}

Set the Log Level

Description

Controls how much output fz emits during execution.

Usage

set_log_level(level)

Arguments

Value

NULL (invisibly). Called for side effects.

Examples

if (fz_available()) {
  set_log_level("DEBUG")
  set_log_level("WARNING")
  set_log_level("ERROR")
}

Uninstall a Model (generic)

Description

Generic alias: removes a model by name. Equivalent to uninstall_model.

Usage

uninstall(model_name, global = FALSE)

Arguments

Value

TRUE if removed, FALSE otherwise.

Examples

if (fz_available()) {
  uninstall("PerfectGas")
}

Uninstall an Algorithm

Description

Removes a previously installed algorithm from ~/.fz/algorithms/.

Usage

uninstall_algorithm(algorithm_name, global = FALSE)

Arguments

Value

TRUE if the algorithm was removed, FALSE otherwise.

Examples

if (fz_available()) {
  uninstall_algorithm("MonteCarlo")
}

Uninstall a Model

Description

Removes a previously installed model from ~/.fz/models/.

Usage

uninstall_model(model_name, global = FALSE)

Arguments

Value

TRUE if the model was removed, FALSE otherwise.

Examples

if (fz_available()) {
  uninstall_model("PerfectGas")
}