Skip to contents

Run one DEoptim trial for a candidate parameter vector (blocking)

sim_landis.Rd

One calibration trial: copy paths$scenario_template into a scratch dir under paths$scratch_root, patch dynamic-fire.txt with par_vec, run LANDIS-II via the warm Docker pool (or a one-off Docker/local invocation if no pool is supplied), parse the resulting Dynamic Fire logs.

Usage

sim_landis(
  par_vec,
  par_names = NULL,
  paths,
  sim_years,
  base_seed,
  pool = NULL,
  pool_idx = NULL,
  method = NULL,
  pixel_area_ha = NULL,
  keep_scratch = FALSE,
  retries = 0L,
  trial_timeout_sec = NULL
)

Arguments

par_vec

Numeric. Named candidate parameter vector.

par_names

Character or NULL. Names in canonical order (calibration_par_names()). Used to re-attach names if DEoptim strips them when calling the objective function with positional args.

paths

Named list of strings. Required entries:

scenario_template

Directory built by build_calibration_scenario_template().

scratch_root

Where per-trial dirs are created. Must equal the pool's scratch_root when pool is supplied. NULL = tempdir().

sim_years

Integer. Calibration sim duration in years (informational; the actual Duration comes from the template's scenario.txt).

base_seed

Integer. Random seed for this trial.

pool

A landis_pool from landis_pool_start(), or NULL for one-off.

pool_idx

Integer. 1-based container index in pool. Required when pool is non-NULL.

method

Character. "docker" or "local". Used only when pool is NULL. Default from getOption("landisutils.run.method").

pixel_area_ha

Numeric or NULL. Hectares per cell. Default NULL derives it from the template's scenario.txt CellLength, so fire sizes are in hectares on any grid. A value that disagrees with CellLength is an error: the calibration drivers never passed one, so every trial on a non-100 m grid was scored in cells against observed hectares.

keep_scratch

Logical. Leave the per-trial scratch dir in place for debugging. Default FALSE.

retries

Integer >= 0. Extra attempts if the simulator exits non-zero, passed to landis_pool_exec(). Default 0 preserves fail-fast. Set it (via cfg$retries) for long searches: one failed exec aborts the entire calibration, and a production run makes tens of thousands of container executions, so a rare transient becomes near-certain. Only the pooled path honours this; a genuine input fault fails on every attempt regardless.

trial_timeout_sec

Numeric or NULL. Wall-clock ceiling for one simulator execution, passed to landis_pool_exec(). NULL (the default) waits indefinitely. retries only helps when the simulator exits; a process that wedges instead never returns, and the coordinator – parked in a blocking read on that worker's socket – waits with it, so the whole generation stalls behind one container with nothing logged. Set this to a generous multiple of a healthy trial's runtime (it is a deadlock breaker, not a scheduler) so a wedged trial is killed, retried and, if it keeps wedging, surfaced as an error the search can act on. Only the pooled path honours it.

Value

The output of parse_dynamic_fire_logs() for the trial's rep01/.

Details

paths carries only file PATHS so the function is FORK-safe (no terra/sf objects in the worker's environment).

Isolation between trials in the same pool container: each trial uses a unique scratch directory; landis_pool_exec() sets per-call env vars to redirect dotnet caches; the trial directory is deleted after parsing unless keep_scratch = TRUE.

See also

Other Dynamic Fire calibration helpers: apply_calibrated_damage_age(), apply_calibrated_hi_prop(), apply_calibrated_ignprob(), apply_calibrated_num_fires(), bc_fuel_code_to_base(), build_calibration_scenario_template(), build_calibration_spinup_scenario(), calibrate_dynamic_fire(), calibration_par_names(), dedup_community_snapshot(), default_severity_prior_sturtevant2009(), landis_overstory_mortality_share(), loss_from_stats(), observed_fire_sizes(), parse_dynamic_fire_logs(), patch_fire_config(), run_calibration_spinup(), run_calibration_validation(), save_observed_fire_targets(), sim_mock(), sim_r_reimpl()