Run a process scenario from a compiled dataset

ws4 ecosystem run-dataset connects the compiled management dataset to the annual process engine. It reads fragments, tracks, features, curves, and treatments, builds one initial cohort per fragment, attaches the compiled track curves, and runs a schedule through fire, LANDIS succession, management, salvage, and regeneration.

ws4 ecosystem run-dataset \
  --dataset build/tsa24 \
  --schedule schedule.csv \
  --output runs/process \
  --topology topology.csv \
  --years 5 \
  --max-blocks 200 \
  --ignition-rate 0.01 \
  --establishment-probability 0.25 \
  --seed 1

The output directory contains:

  • process_evaluation.json: final accounts and event counts.

  • process_evaluation_accounts.csv and process_evaluation_values.csv.

  • process_events.json: the replayable event log.

  • process_dataset.json: the loaded fragment, block, curve, species, and seed metadata.

Assumptions

Initial live biomass comes from --biomass-source:

  • auto uses a compiled feature label containing biomass when one exists, otherwise converts the track volume curve with --wood-density and --biomass-expansion.

  • feature requires a compiled biomass curve; --biomass-label selects it exactly.

  • volume always uses the track volume conversion.

  • fixed uses --initial-biomass (default 100 t/ha).

The default conversion is 0.5 t/m3 wood density and a 1.5 biomass expansion factor. These are explicit provisional coefficients, not a hidden calibration. Initial fuel remains zero by default; succession adds fuel.

Species are read from the compiled feature.SpeciesProp.* curves: each fragment is split into species cohorts whose area fractions come from the curves at its current age. --species is the fallback when a track has no proportion curve, and --no-species-composition uses that fallback everywhere. The default aliases map common BC codes to the published LANDIS reference traits; pass an explicit species_traits mapping to ProcessDataset.from_directory to override them.

The default curve selection uses feature.Volume when present, then the managed or unmanaged feature.Yield.*.Total label that matches the track name. Use --volume-label to force one feature label.

Pass --topology with a block edge list (src_block,dst_block,distance_m) to map block adjacency onto fragment fire edges. Without it, fire ignites independently per fragment and does not spread.

Succession runs in a vectorized landscape batch by default: one event per year applies the published LANDIS kernels over every fragment at once. Use --no-batch-succession to emit one succession event per fragment for debugging or event-log comparison. --max-blocks bounds a pilot run; the batch path handles a full estate-scale dataset.

Optimize a schedule

ws4 ecosystem optimize runs the process hill-climb against a targets file and writes the best schedule in the estate input format:

ws4 ecosystem optimize \
  --dataset build/tsa24 \
  --targets targets.yaml \
  --output runs/process-opt \
  --topology topology.csv \
  --years 5 \
  --max-iterations 2 \
  --max-blocks 200

The output contains process_optimization.json, the search trace, schedule.csv, block_fragments.csv, the best evaluation, and the best event log. The grammar uses every compiled treatment and every block in the selected dataset, with an empty schedule as the default starting point; pass --initial-schedule to start elsewhere.

The Python API carries the same state into the process search and optimization modules:

prepared = ProcessDataset.from_directory(dataset, topology=topology)
result = prepared.search(
    candidates,
    horizon_years=5,
    targets=targets,
    fire=FireConfig(ignition_rate_per_fragment_year=0.01),
    seed=1,
)
best = result.best.evaluation