Quickstart: compile, simulate, target, search
The command-line walkthrough, run here on the two-block example in examples/synthetic. Its numbers are checkable by hand: with no schedule the natural-track volume at offset 0 is 3.0 * 120 + 2.0 * 170 = 700, and clearing block 1 leaves 2.0 * 170 = 340.
This one is a command-line session: every step is a ws4 command.
Compile a dataset
[1]:
import subprocess
def run(command: str) -> None:
"""Run a WS4 command, printing what it printed."""
result = subprocess.run(command, shell=True, text=True, capture_output=True)
print((result.stdout or result.stderr).strip())
result.check_returncode()
[2]:
run("ws4 build --xml examples/synthetic/recipe.xml --fragments examples/synthetic/fragments.csv --out tmp/examples/quickstart/compiled")
Built dataset → tmp/examples/quickstart/compiled
[3]:
run("ws4 validate --dataset tmp/examples/quickstart/compiled")
Dataset is valid → tmp/examples/quickstart/compiled
Simulate a schedule
A schedule is a CSV of block_id, treatment, and offset, where the offset is the number of years after the start of the simulation.
[4]:
from pathlib import Path
work = Path("tmp/examples/quickstart")
work.mkdir(parents=True, exist_ok=True)
(work / "schedule.csv").write_text("block_id,treatment,offset\n1,CC,0\n")
run("ws4 simulate --dataset tmp/examples/quickstart/compiled --schedule tmp/examples/quickstart/schedule.csv --years 5 --out tmp/examples/quickstart/sim")
Simulation complete → tmp/examples/quickstart/sim
[5]:
import pandas as pd
values = pd.read_csv(work / "sim" / "account_values.csv")
print(values.head(4).to_string(index=False))
offset account value
-1 feature.Volume 700.0
0 feature.Volume 340.0
0 product.Volume 360.0
1 feature.Volume 360.0
340.0 is the figure from the example: block 1’s 3.0 ha of natural track is gone, and block 2’s 2.0 ha of natural volume remains.
State a target and check the run against it
[6]:
(work / "targets.yaml").write_text(
"targets:\n"
"- account: feature.Volume\n"
" period: 1\n"
" minimum: 700\n"
" maximum: 700\n"
" period_width: 1\n"
)
run("ws4 report --run tmp/examples/quickstart/sim --targets tmp/examples/quickstart/targets.yaml")
Report written → tmp/examples/quickstart/sim
[7]:
print(pd.read_csv(work / "sim" / "report_targets.csv").to_string(index=False))
account period year value minimum maximum raw_penalty penalty scale normalization priority kind status
feature.Volume 1 1 340.0 700 700 360.0 360.0 1.0 none 1 level below
The status is below: clearing block 1 drops the natural volume to 340 against a floor of 700, and the penalty is the shortfall.
Search for a schedule that meets it
[8]:
run("ws4 optimize --dataset tmp/examples/quickstart/compiled --targets tmp/examples/quickstart/targets.yaml --years 5 --time-limit 00:00:05 --seed 1 --threads 1 --out tmp/examples/quickstart/opt")
Optimization Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ key ┃ value ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ incumbent_objective │ 0.0 │
│ iterations │ 500 │
│ patience │ 0 │
│ reversion │ 0 │
│ seed │ 1 │
│ metaheuristic │ sa │
│ threshold │ 1.0 │
│ starts │ 1 │
│ initial_schedule_path │ None │
│ blocks_scheduled │ 0 │
│ operators │ ['toggle', 'shift', 'swap', 'lns', 'cluster', 'coalesce', 'merge', 'split'] │
│ constraint_strategy │ penalize │
│ constraint_stats │ {'strategy': 'penalize', 'enabled': False, 'proposed': 0, 'feasible': 0, 'rejected': 0, 'repaired': 0, 'initial_removed': 0, 'initial_repairs': 0, 'available': True} │
│ constraint_feasible │ True │
│ constraint_report │ constraint_report.json │
│ run_manifest │ run_manifest.json │
│ data_quality │ {'status': 'unknown', 'metadata_supplied': False, 'provenance_supplied': False, 'warnings': ['data-quality metadata is not supplied', 'dataset provenance is not supplied'], 'table_count': 12} │
│ data_quality_report │ data_quality.json │
│ ending_inventory │ {'offset': 4, 'accounts': {'feature.Volume': 750.0}} │
│ ending_inventory_report │ ending_inventory.csv │
│ status │ ok │
│ time_limit_reached │ False │
│ dataset │ {'schema_version': '0.1', 'sources': [{'path': 'recipe.xml', 'sha256': 'fae361c3f333850d45b1509d95be0a183e4d809fb133a2b102721196aeb78f2a'}, {'path': 'fragments.csv', 'sha256': │
│ │ '9fe1655c619cd8b40eabdba84af8ed986c1cedab343855ba67ba46cb84da018a'}], 'manifest_sha256': '84ed52a984442dfbf148a67582869c872915e69c5adfb09f057d3107b10f2600'} │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
[9]:
import json
summary = json.loads((work / "opt" / "summary.json").read_text())
print({key: summary[key] for key in ("incumbent_objective", "blocks_scheduled", "iterations", "seed", "status")})
print((work / "opt" / "schedule.csv").read_text())
{'incumbent_objective': 0.0, 'blocks_scheduled': 0, 'iterations': 500, 'seed': 1, 'status': 'ok'}
block_id,treatment,offset
The incumbent is an empty schedule: leaving the stand alone holds feature.Volume at 700, which meets the floor, so nothing can beat a penalty of zero. On a two-block landscape that is the whole answer.
Watch a search
ws4 watch paints the realized-versus-target window; --plain prints one frame instead of the live view, which is what a notebook wants.
[10]:
run("ws4 watch --dataset tmp/examples/quickstart/compiled --targets tmp/examples/quickstart/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 6642.31 eval/s elapsed 0.0s seed 1 sa │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
feature.Volume Z +0
748.1 │ ::::::::
│####::::::
│####::::::
│####::::::
│####::::::
│####::::::
│####::::##
│##########
│##########
│##########
│##########
0 │##########
└──────────
1 2 3 4 5
feature.Volume — per 1-year period
period min realized max shortfall excess status
1 700 700 700 0 0 ok
2 — 712.5 — 0 0 ok
3 — 350 — 0 0 ok
4 — 370 — 0 0 ok
5 — 390 — 0 0 ok
Watch summary
┏━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ key ┃ value ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━┩
│ objective │ 0 │
│ penalty │ 0 │
│ evaluations │ 200 │
│ blocks │ 0 │
│ elapsed │ 0.03011 │
└─────────────┴─────────┘
Where to go next
The how-to guides, for targets with teeth, even flow, and patch size distributions.
020_even_flow.ipynb, which uses the Python API on a larger estate.