Quickstart: the command line
This walkthrough goes from a recipe and a fragment inventory to a compiled dataset, a simulated run,
and a search that meets a target. It uses the two-block example in examples/synthetic, whose
expected numbers are written down in that directory’s README.md, so every figure below can be
checked by hand. The whole sequence takes seconds.
If you would rather call WS4 from Python, read Quickstart: the Python API instead; the two walkthroughs do the same work.
Install
python -m pip install -e ".[geo]"
ws4 --help
ws4 is one command per step:
Command |
What it does |
|---|---|
|
Compile a recipe and a fragment inventory into a dataset. |
|
Import an existing matrix-format dataset into the same schema. |
|
Check a dataset against its manifest and its invariants. |
|
Replay a schedule and write a run directory. |
|
Search for a schedule that satisfies targets. |
|
Watch realized against target values while the search runs. |
|
Balance target weights from a pilot search. |
|
Summarise a run’s accounts and target statuses. |
Every command prints where it wrote its output. The dataset is the boundary: build and ingest
produce one, and every other command reads only that (see Compiled dataset).
The example
examples/synthetic is two blocks on two fragments, both on the natural track: fragment 1 is 3.0 ha
at age 40, fragment 2 is 2.0 ha at age 60. The recipe defines a growth curve per track, one clearcut
treatment (CC) that moves a fragment from the natural track to the managed track, a
feature.Volume feature, and a product.Volume product.
With no schedule, the natural-track volume at offset 0 is 3.0 * 120 + 2.0 * 170 = 700. Clearing
block 1 at offset 0 moves that fragment onto the managed track, so the figure below should read
340.
Compile the dataset
ws4 build --xml examples/synthetic/recipe.xml \
--fragments examples/synthetic/fragments.csv \
--out tmp/getting-started/compiled
ws4 validate --dataset tmp/getting-started/compiled
Built dataset → tmp/getting-started/compiled
Dataset is valid → tmp/getting-started/compiled
Simulate a schedule
A schedule is a CSV with block_id, treatment, and offset columns, where the offset is the
number of years after the start of the simulation. Clear block 1 at offset 0 and replay five years:
cat > tmp/getting-started/schedule.csv <<'CSV'
block_id,treatment,offset
1,CC,0
CSV
ws4 simulate --dataset tmp/getting-started/compiled \
--schedule tmp/getting-started/schedule.csv \
--years 5 --out tmp/getting-started/sim
Simulation complete → tmp/getting-started/sim
The run directory holds the account values, the product values, the per-year spatial metrics when a
topology is given, and the route outputs when a route configuration is given. The head of
account_values.csv is:
offset,account,value
-1,feature.Volume,700.0
0,feature.Volume,340.0
0,product.Volume,360.0
1,feature.Volume,360.0
2,feature.Volume,380.0
340.0 is the figure from the example: the clearcut removed fragment 1’s 3.0 ha of natural volume
and left 2.0 * 170. product.Volume records what the treatment produced. The row at offset -1 is
the pre-simulation snapshot.
State a target and check a run against it
A target names an account, an accounting period, and a bound. Targets live in a YAML file:
# tmp/getting-started/targets.yaml
targets:
- account: feature.Volume
period: 1
minimum: 700
maximum: 700
period_width: 1
ws4 report --run tmp/getting-started/sim --targets tmp/getting-started/targets.yaml
Report written → tmp/getting-started/sim
report_targets.csv says how each target fared, and report_accounts.csv summarises the whole
profile:
account,year,value,minimum,maximum,penalty,status
feature.Volume,1,340.0,700,700,360.0,below
The status is below because clearing block 1 drops the natural volume to 340 against a floor of
700; the penalty is the shortfall. The year column is the display label, the year the period ends
on.
Search for a schedule that meets it
The optimizer searches the schedules that the dataset makes operably available and reports the best it found:
printf 'weights: {}\n' > tmp/getting-started/weights.yaml
ws4 optimize --dataset tmp/getting-started/compiled \
--targets tmp/getting-started/targets.yaml \
--years 5 --time-limit 00:00:05 --seed 1 --threads 1 \
--out tmp/getting-started/opt
It writes schedule.csv, summary.json, the account and product values for the incumbent, the
target report, and the telemetry log. The summary here is:
incumbent_objective: 0.0
blocks_scheduled: 0
iterations: 500
metaheuristic: sa
seed: 1
status: ok
Note
The incumbent is an empty schedule: leaving the stand alone holds feature.Volume at 700,
which meets the floor, and no treatment can beat a penalty of zero. On a two-block landscape that
is the whole answer — the point of the walkthrough is the plumbing, not the search.
Weights belong to each target (min_weight and max_weight), and ws4 calibrate
rescales them for you (see Write targets). ws4 optimize also accepts a
--weights file, kept for compatibility; it is not read.
Watch a search
ws4 watch runs the same search and paints the realized-versus-target window in place, one column
per period. --plain prints one frame instead of the live view:
ws4 watch --dataset tmp/getting-started/compiled \
--targets tmp/getting-started/targets.yaml \
--account feature.Volume --years 5 --period-width 1 \
--iterations 200 --plain
╭───────────────────────────────── ws4 watch ──────────────────────────────────╮
│ feature.Volume objective (sum of penalties): 0 │
│ iteration 200/200 7858.85 eval/s elapsed 0.0s seed 1 sa │
╰──────────────────────────────────────────────────────────────────────────────╯
feature.Volume Z +0
748.1 │ ::::::::
│####::::::
│####::::::
0 │##########
└──────────
1 2 3 4 5
Repeat --account to watch several accounts side by side, one window each. See
Watch a run.
Where to go next
How-to guides — task-shaped guides: targets, even flow, patches, routes, the Python API.
Optimizer — the objective, the operators, and the search stack.
Simulator — the annual engine and what a run directory contains.
Spatial structure and constraints — block topology, patch metrics, and the opening rules.