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.rst explains the size classes, search_distance and the operators.

  • docs/reference/spatial.rst specifies the topology, the metrics and the opening rules.