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.csvandprocess_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:
autouses a compiled feature label containingbiomasswhen one exists, otherwise converts the track volume curve with--wood-densityand--biomass-expansion.featurerequires a compiled biomass curve;--biomass-labelselects it exactly.volumealways uses the track volume conversion.fixeduses--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