[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()
The sample estate
examples/estate is a small self-contained estate: 64 blocks on an 8 x 8 grid, one clearcut treatment that can be applied more than once, a seral feature that marks fresh openings, and a road network with two mills. Everything below runs against it.
This one is mostly a command-line session, with one compile through the library.
The files
File |
What it holds |
|---|---|
|
two lanes, one clearcut operable from age 40, the volume curves, and a seral curve that is 1 while an opening is fresh |
|
64 blocks, 8-12 ha, ages 0-100, all natural |
|
the grid adjacency that makes adjacent openings a patch |
|
the road network and the two mills |
|
the route configuration and the patch account |
Compile it
[2]:
from pathlib import Path
from ws4.build.compiler import build_canonical_dataset
work = Path("tmp/examples/estate")
work.mkdir(parents=True, exist_ok=True)
dataset = build_canonical_dataset(
"examples/estate/recipe.xml", "examples/estate/fragments.csv", work / "compiled"
)
print(dataset)
tmp/examples/estate/compiled
Simulate a schedule: openings, and two mills
Cutting eight blocks at offset 0 opens patches on the grid and ships the volume to whichever mill is cheaper to reach.
[3]:
import pandas as pd
schedule = pd.DataFrame({"block_id": [1, 2, 9, 10, 57, 58, 63, 64], "treatment": ["CC"] * 8, "offset": [0] * 8})
(work / "schedule.csv").write_text(schedule.to_csv(index=False))
run("ws4 simulate --dataset tmp/examples/estate/compiled --schedule tmp/examples/estate/schedule.csv --years 10 --topology examples/estate/topology.csv --route-config examples/estate/route.yaml --out tmp/examples/estate/run")
Simulation complete → tmp/examples/estate/run
[4]:
values = pd.read_csv(work / "run" / "account_values.csv")
print(values[values.offset == -1].to_string(index=False))
offset account value
-1 feature.Seral.regen 0.000000
-1 feature.Volume.managed 0.000000
-1 feature.Volume.natural 80026.785714
feature.Seral.regen is the area in fresh openings — the criterion the patch account reads. The two product.Mill* accounts and the two haul accounts say how the volume split, and route.Total.haul is the duplicate account that adds them.
[5]:
routed = pd.read_csv(work / "run" / "route_values.csv")
print(routed.groupby("destination")[["volume", "haul_cost"]].sum().to_string())
print()
print(routed[["block_id", "destination", "volume", "length_m", "haul_cost"]].head(4).to_string(index=False))
volume haul_cost
destination
destination.MILL1 3423.514286 0.4
destination.MILL2 5370.300000 0.6
block_id destination volume length_m haul_cost
1 destination.MILL1 1918.714286 4000.0 0.2
2 destination.MILL1 1504.800000 4000.0 0.2
9 destination.MILL2 1272.000000 4000.0 0.2
10 destination.MILL2 1932.000000 4000.0 0.2
Blocks near the west end go to destination.MILL1, blocks further east to destination.MILL2: the choice is the least haul cost along the segments, not the distance to a mill.
The openings themselves
[6]:
metrics = pd.read_csv(work / "run" / "patch_metrics.csv")
print(metrics[metrics.offset <= 2].to_string(index=False))
offset patch_count mean_patch_area max_patch_area le5 le10 le50 over
0 3.0 27.3 42.9 0 0 3 0
Search, and read the run
A volume floor plus a haul-cost ceiling behaves predictably, and shows the route accounts folding into the objective.
[7]:
(work / "targets.yaml").write_text(
"targets:\n"
"- account: product.Harvested.CC\n"
" period: 1\n"
" minimum: 20000\n"
" period_width: 10\n"
"- account: route.Total.haul\n"
" period: 1\n"
" maximum: 3000\n"
" period_width: 10\n"
)
run("ws4 optimize --dataset tmp/examples/estate/compiled --targets tmp/examples/estate/targets.yaml --years 100 --iterations 20000 --route-config examples/estate/route.yaml --threads 1 --out tmp/examples/estate/search")
Optimization Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ key ┃ value ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ incumbent_objective │ 0.0 │
│ iterations │ 20000 │
│ patience │ 0 │
│ reversion │ 0 │
│ seed │ 42 │
│ metaheuristic │ sa │
│ threshold │ 1.0 │
│ starts │ 1 │
│ initial_schedule_path │ None │
│ blocks_scheduled │ 24 │
│ 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': 99, 'accounts': {'feature.Seral.regen': 143.49999999999997, 'feature.Volume.managed': 29307.574999999997, 'feature.Volume.natural': 99698.14285714286}} │
│ ending_inventory_report │ ending_inventory.csv │
│ status │ ok │
│ time_limit_reached │ False │
│ dataset │ {'schema_version': '0.1', 'sources': [{'path': 'recipe.xml', 'sha256': 'ff05c1de6ac54f9509d423fae0597abc17b03ee9965e75819f2d6778e30f5288'}, {'path': 'fragments.csv', 'sha256': │
│ │ '5f371cb7421d65f5839f334f94911d315d8200606c29a53d87352b875b4589d9'}], 'manifest_sha256': 'd26ad2c906f0d4fe6768999b4418534c72eeadf1d4b3bdc93d7cf3b5ca1aa35a'} │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
[8]:
import json
summary = json.loads((work / "search" / "summary.json").read_text())
print({key: summary[key] for key in ("incumbent_objective", "blocks_scheduled", "iterations", "status")})
print()
print(pd.read_csv(work / "search" / "report_targets.csv").to_string(index=False))
{'incumbent_objective': 0.0, 'blocks_scheduled': 24, 'iterations': 20000, 'status': 'ok'}
account period year value minimum maximum raw_penalty penalty scale normalization priority kind status
product.Harvested.CC 1 10 20443.057143 20000.0 NaN 0.0 0.0 1.0 none 1 level met
route.Total.haul 1 10 136.092857 NaN 3000.0 0.0 0.0 1.0 none 1 level met
What to look at next
docs/howto/route-products.rstwalks through the road tables and the route configuration.docs/howto/patch-targets.rstcovers the patch accounts, the size classes and the shape-aware operators; a run’s report and a simulation of the same schedule agree on the classes.docs/getting-started/architecture.rstexplains why the search prices a move instead of re-simulating.