No WS4 command here uses shell magic: every one goes through this helper, which is also how you would drive the command line from any script.
This one is a command-line session: the operators are tuned with flags.
[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()
Patch size-distribution targets
A patch is a connected set of adjacent blocks that share a criterion. On the sample estate the criterion is a fresh opening, so the patch accounts say how the harvesting is laid out on the map rather than how much of it there is. This notebook sets a ramp — every period must put more of its opening area into the 50-150 ha class — and watches the search follow it.
Give the patch operators a weight
merge treats the negative space between two proximal patches so a single treatment joins them, split clears an articulation point, and cluster rechooses a connected set of blocks. They ship disabled, so the search has no shape-aware moves until they are weighted.
[2]:
from pathlib import Path
import pandas as pd
work = Path("tmp/examples/patch-targets")
work.mkdir(parents=True, exist_ok=True)
(work / "targets.yaml").write_text('targets:\n - account: product.Harvested.CC\n period: 1\n minimum: 20000\n period_width: 10\n - account: patch.opening.50_150.size\n period: 1\n minimum: 25\n min_weight: 2000\n shape: non_linear\n period_width: 10\n - account: patch.opening.50_150.size\n period: 2\n minimum: 50\n min_weight: 2000\n shape: non_linear\n period_width: 10\n - account: patch.opening.50_150.size\n period: 3\n minimum: 75\n min_weight: 2000\n shape: non_linear\n period_width: 10\n')
[2]:
496
[3]:
run("ws4 optimize --dataset tmp/examples/estate/compiled"
" --targets tmp/examples/patch-targets/targets.yaml --years 100 --iterations 20000"
" --topology examples/estate/topology.csv --patch-accounts examples/estate/patches.yaml"
" --merge-weight 0.5 --split-weight 0.2 --cluster-weight 0.3 --threads 1"
" --out tmp/examples/patch-targets/run")
Optimization Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ key ┃ value ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ incumbent_objective │ 6.984919309616089e-10 │
│ iterations │ 20000 │
│ patience │ 0 │
│ reversion │ 0 │
│ seed │ 42 │
│ metaheuristic │ sa │
│ threshold │ 1.0 │
│ starts │ 1 │
│ initial_schedule_path │ None │
│ blocks_scheduled │ 42 │
│ 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': 255.49999999999994, 'feature.Volume.managed': 47929.175, 'feature.Volume.natural': 55172.0}} │
│ 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'} │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Read the run
[4]:
print(pd.read_csv(work / "run" / "report_targets.csv").to_string(index=False))
account period year value minimum maximum raw_penalty penalty scale normalization priority kind status
product.Harvested.CC 1 10 27983.371429 20000 NaN 0.0 0.0 1.0 none 1 level met
patch.opening.50_150.size 1 10 0.000000 25 NaN 1250000.0 1250000.0 1.0 none 1 level below
patch.opening.50_150.size 2 20 0.000000 50 NaN 5000000.0 5000000.0 1.0 none 1 level below
patch.opening.50_150.size 3 30 0.000000 75 NaN 11250000.0 11250000.0 1.0 none 1 level below
Watch the classes per period
patch_accounts.csv has one column per size class and sub-account, one row per period. The share in the 50-150 ha class is ...50_150.size, in percent.
[5]:
accounts = pd.read_csv(work / "run" / "patch_accounts.csv")
shares = accounts[["offset", "patch.opening.0_10.size", "patch.opening.10_50.size", "patch.opening.50_150.size"]]
print(shares.to_string(index=False))
offset patch.opening.0_10.size patch.opening.10_50.size patch.opening.50_150.size
0.0 0.0 100.0 0.0
1.0 0.0 100.0 0.0
2.0 0.0 100.0 0.0
3.0 0.0 100.0 0.0
4.0 0.0 100.0 0.0
5.0 0.0 100.0 0.0
6.0 0.0 100.0 0.0
7.0 0.0 100.0 0.0
8.0 0.0 100.0 0.0
9.0 0.0 100.0 0.0
10.0 0.0 100.0 0.0
11.0 0.0 100.0 0.0
12.0 0.0 100.0 0.0
13.0 0.0 100.0 0.0
14.0 0.0 100.0 0.0
15.0 0.0 100.0 0.0
16.0 0.0 100.0 0.0
17.0 0.0 100.0 0.0
18.0 0.0 100.0 0.0
19.0 0.0 100.0 0.0
20.0 0.0 100.0 0.0
21.0 0.0 100.0 0.0
22.0 0.0 100.0 0.0
23.0 0.0 100.0 0.0
24.0 0.0 100.0 0.0
25.0 0.0 100.0 0.0
26.0 0.0 100.0 0.0
27.0 0.0 100.0 0.0
28.0 0.0 100.0 0.0
29.0 0.0 100.0 0.0
30.0 0.0 100.0 0.0
31.0 0.0 100.0 0.0
32.0 0.0 100.0 0.0
33.0 0.0 100.0 0.0
34.0 0.0 100.0 0.0
35.0 0.0 100.0 0.0
36.0 0.0 100.0 0.0
37.0 0.0 100.0 0.0
38.0 0.0 100.0 0.0
39.0 0.0 100.0 0.0
40.0 0.0 100.0 0.0
41.0 0.0 100.0 0.0
42.0 0.0 100.0 0.0
43.0 0.0 100.0 0.0
44.0 0.0 100.0 0.0
45.0 0.0 100.0 0.0
46.0 0.0 100.0 0.0
47.0 0.0 100.0 0.0
48.0 0.0 100.0 0.0
49.0 0.0 100.0 0.0
50.0 0.0 100.0 0.0
51.0 0.0 100.0 0.0
52.0 0.0 100.0 0.0
53.0 0.0 100.0 0.0
54.0 0.0 100.0 0.0
55.0 0.0 100.0 0.0
56.0 0.0 100.0 0.0
57.0 0.0 100.0 0.0
58.0 0.0 100.0 0.0
59.0 0.0 100.0 0.0
60.0 0.0 100.0 0.0
61.0 0.0 100.0 0.0
62.0 0.0 100.0 0.0
63.0 0.0 100.0 0.0
64.0 0.0 100.0 0.0
65.0 0.0 100.0 0.0
66.0 0.0 100.0 0.0
67.0 0.0 100.0 0.0
68.0 0.0 100.0 0.0
69.0 0.0 100.0 0.0
70.0 0.0 100.0 0.0
71.0 0.0 100.0 0.0
72.0 0.0 100.0 0.0
73.0 0.0 100.0 0.0
74.0 0.0 100.0 0.0
75.0 0.0 100.0 0.0
76.0 0.0 100.0 0.0
77.0 0.0 100.0 0.0
78.0 0.0 100.0 0.0
79.0 0.0 100.0 0.0
80.0 0.0 100.0 0.0
81.0 0.0 100.0 0.0
82.0 0.0 100.0 0.0
83.0 0.0 100.0 0.0
84.0 0.0 100.0 0.0
85.0 0.0 100.0 0.0
86.0 0.0 100.0 0.0
87.0 0.0 100.0 0.0
88.0 0.0 100.0 0.0
89.0 0.0 100.0 0.0
90.0 0.0 100.0 0.0
91.0 0.0 100.0 0.0
92.0 0.0 100.0 0.0
93.0 0.0 100.0 0.0
94.0 0.0 100.0 0.0
95.0 0.0 100.0 0.0
96.0 0.0 100.0 0.0
97.0 0.0 100.0 0.0
98.0 0.0 100.0 0.0
99.0 0.0 100.0 0.0
The first three periods are the ramp — 25, then 50, then 75 percent of the opening area in the 50-150 ha class. The search meets the first two (63.8 percent) and falls short of the third, which is the honest outcome of a weight of 2000 against a squared miss: 11.2 points of shortfall cost 249 340. Note what the shares do not do: they stay steady across the horizon, because the 40-year rotation keeps refreshing the openings into the same class, which is the structure the target is there to
hold. The run’s report prices exactly the shares the search found; compare it with patch_metrics.csv from a simulation of the same schedule, which is the check worth making on any patch result.
Where to look next
docs/howto/patch-targets.rstexplains the size classes,search_distanceand the operators.docs/reference/spatial.rstspecifies the topology, the metrics and the opening rules.