fz (version 1.2.0)

fzr: 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,
  case_naming = NULL,
  input_static = NULL
)

Value

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

Arguments

input_path

Path to input file or directory.

input_variables

Named list of variable values (or vectors of values for a full-factorial grid), or a data frame where each row is one case.

model

Model definition dict or alias string.

results_dir

Results directory. Default "results".

calculators

Calculator specification(s). Strings of the form "sh://<command>" run a local shell command; "ssh://user\@host" runs over SSH; NULL auto-detects installed calculators.

callbacks

Optional named list of callback functions.

timeout

Timeout in seconds per case. Default NULL, which resolves to the model's own "timeout" entry if set, otherwise the FZ_RUN_TIMEOUT configuration value (1 hour by default in funz-fz >= 1.2). An explicit value here takes precedence over both.

case_naming

How each case's result/temp subdirectory is named: "path" (default, "var1=val1,var2=val2,..."), "hash" (short content hash of the variable combination), or "index" ("case_<i>"). "hash"/"index" avoid filesystem name length limits with many variables and write a cases.csv manifest at the results root. Default NULL (uses FZ_CASE_NAMING or "path").

input_static

Optional character vector of files identical across every case (e.g. a shared reference dataset): never templated, never re-hashed per case, and - for relative paths - symlinked into each case directory instead of duplicated (and transferred to remote calculators). Absolute paths are assumed already present calculator-side. Default NULL.

Examples

# \donttest{
if (fz_available()) {
  # run inside a throwaway directory: fz writes results/ and .fz/ under cwd
  ex_dir <- file.path(tempdir(), "fz-fzr-example")
  dir.create(ex_dir, showWarnings = FALSE)
  owd <- setwd(ex_dir)

  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")

  setwd(owd)
  unlink(ex_dir, recursive = TRUE)
}
# }