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

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,
  parse_timeout_sec = 600,
  parse_retries = 2L,
  parse_options = list()
)

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.

parse_timeout_sec

Numeric or NULL. Wall-clock ceiling on parsing the finished replicate, which runs in a child R process so that it can be killed: a parse that spins in native code never reaches an interrupt check, and one that crashes would otherwise take the calibration worker with it. Either stalls the whole search, because the coordinator waits on every worker. A healthy parse takes seconds. Default 600. NULL parses in this process with no limit, as before 0.0.162. Each failed attempt is appended to parse_failures.log under the scratch root.

parse_retries

Integer >= 0. Extra attempts after a parse times out or its process dies. An error the parser raises is not retried. Default 2.

parse_options

List of options for parse_dynamic_fire_logs(), by name: any of by_class, engine_rule and event_fields, each TRUE or FALSE. A replicate's directory is deleted once it is parsed, so the parse must keep whatever is wanted from it. Applies to the in-process parse and the isolated one alike. Default list() parses as before.

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(), bc_fuel_label_to_base(), build_calibration_scenario_template(), build_calibration_spinup_scenario(), calibrate_dynamic_fire(), calibration_par_names(), dedup_community_snapshot(), default_severity_prior_sturtevant2009(), fire_cohort_killed(), fire_cohort_mortality(), ground_fire_kill_par_names(), landis_dominant_cohorts(), 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()