{ "cells": [ { "cell_type": "markdown", "id": "67acae5a", "metadata": {}, "source": [ "No WS4 command here uses shell magic: every one goes through this helper, which is also\n", "how you would drive the command line from any script.\n", "\n", "This one is a **command-line** session: the operators are tuned with flags.\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "017759ec", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:26:56.608998Z", "iopub.status.busy": "2026-10-17T23:26:56.608575Z", "iopub.status.idle": "2026-10-17T23:26:56.617415Z", "shell.execute_reply": "2026-10-17T23:26:56.615715Z" } }, "outputs": [], "source": [ "import subprocess\n", "\n", "\n", "def run(command: str) -> None:\n", " \"\"\"Run a WS4 command, printing what it printed.\"\"\"\n", " result = subprocess.run(command, shell=True, text=True, capture_output=True)\n", " print((result.stdout or result.stderr).strip())\n", " result.check_returncode()" ] }, { "cell_type": "markdown", "id": "0a44a2ce", "metadata": {}, "source": [ "# Patch size-distribution targets\n", "\n", "A patch is a connected set of adjacent blocks that share a criterion. On the sample estate the\n", "criterion is a fresh opening, so the patch accounts say how the harvesting is laid out on the\n", "map rather than how much of it there is. This notebook sets a **ramp** — every period must put\n", "more of its opening area into the 50-150 ha class — and watches the search follow it." ] }, { "cell_type": "markdown", "id": "ce11de9f", "metadata": {}, "source": [ "## Give the patch operators a weight\n", "\n", "`merge` treats the negative space between two proximal patches so a single treatment joins them,\n", "`split` clears an articulation point, and `cluster` rechooses a connected set of blocks. They ship\n", "disabled, so the search has no shape-aware moves until they are weighted." ] }, { "cell_type": "code", "execution_count": 2, "id": "56b62fb4", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:26:56.621283Z", "iopub.status.busy": "2026-10-17T23:26:56.620882Z", "iopub.status.idle": "2026-10-17T23:26:56.909269Z", "shell.execute_reply": "2026-10-17T23:26:56.907822Z" } }, "outputs": [ { "data": { "text/plain": [ "496" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from pathlib import Path\n", "\n", "import pandas as pd\n", "\n", "work = Path(\"tmp/examples/patch-targets\")\n", "work.mkdir(parents=True, exist_ok=True)\n", "(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')" ] }, { "cell_type": "code", "execution_count": 3, "id": "d78801e8", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:26:56.912425Z", "iopub.status.busy": "2026-10-17T23:26:56.912222Z", "iopub.status.idle": "2026-10-17T23:27:01.923232Z", "shell.execute_reply": "2026-10-17T23:27:01.921651Z" }, "tags": [ "no-drift-check" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[3m Optimization Summary \u001b[0m\n", "┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n", "┃\u001b[1m \u001b[0m\u001b[1mkey \u001b[0m\u001b[1m \u001b[0m┃\u001b[1m \u001b[0m\u001b[1mvalue \u001b[0m\u001b[1m \u001b[0m┃\n", "┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩\n", "│ incumbent_objective │ 6.984919309616089e-10 │\n", "│ iterations │ 20000 │\n", "│ patience │ 0 │\n", "│ reversion │ 0 │\n", "│ seed │ 42 │\n", "│ metaheuristic │ sa │\n", "│ threshold │ 1.0 │\n", "│ starts │ 1 │\n", "│ initial_schedule_path │ None │\n", "│ blocks_scheduled │ 42 │\n", "│ operators │ ['toggle', 'shift', 'swap', 'lns', 'cluster', 'coalesce', 'merge', 'split'] │\n", "│ constraint_strategy │ penalize │\n", "│ constraint_stats │ {'strategy': 'penalize', 'enabled': False, 'proposed': 0, 'feasible': 0, 'rejected': 0, 'repaired': 0, 'initial_removed': 0, 'initial_repairs': 0, 'available': True} │\n", "│ constraint_feasible │ True │\n", "│ constraint_report │ constraint_report.json │\n", "│ run_manifest │ run_manifest.json │\n", "│ 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} │\n", "│ data_quality_report │ data_quality.json │\n", "│ ending_inventory │ {'offset': 99, 'accounts': {'feature.Seral.regen': 255.49999999999994, 'feature.Volume.managed': 47929.175, 'feature.Volume.natural': 55172.0}} │\n", "│ ending_inventory_report │ ending_inventory.csv │\n", "│ status │ ok │\n", "│ time_limit_reached │ False │\n", "│ dataset │ {'schema_version': '0.1', 'sources': [{'path': 'recipe.xml', 'sha256': 'ff05c1de6ac54f9509d423fae0597abc17b03ee9965e75819f2d6778e30f5288'}, {'path': 'fragments.csv', 'sha256': │\n", "│ │ '5f371cb7421d65f5839f334f94911d315d8200606c29a53d87352b875b4589d9'}], 'manifest_sha256': 'd26ad2c906f0d4fe6768999b4418534c72eeadf1d4b3bdc93d7cf3b5ca1aa35a'} │\n", "└─────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘\n" ] } ], "source": [ "run(\"ws4 optimize --dataset tmp/examples/estate/compiled\"\n", " \" --targets tmp/examples/patch-targets/targets.yaml --years 100 --iterations 20000\"\n", " \" --topology examples/estate/topology.csv --patch-accounts examples/estate/patches.yaml\"\n", " \" --merge-weight 0.5 --split-weight 0.2 --cluster-weight 0.3 --threads 1\"\n", " \" --out tmp/examples/patch-targets/run\")" ] }, { "cell_type": "markdown", "id": "af90689e", "metadata": {}, "source": [ "## Read the run" ] }, { "cell_type": "code", "execution_count": 4, "id": "f3c9ec79", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:27:01.926912Z", "iopub.status.busy": "2026-10-17T23:27:01.926471Z", "iopub.status.idle": "2026-10-17T23:27:01.947904Z", "shell.execute_reply": "2026-10-17T23:27:01.946582Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " account period year value minimum maximum raw_penalty penalty scale normalization priority kind status\n", " product.Harvested.CC 1 10 27983.371429 20000 NaN 0.0 0.0 1.0 none 1 level met\n", "patch.opening.50_150.size 1 10 0.000000 25 NaN 1250000.0 1250000.0 1.0 none 1 level below\n", "patch.opening.50_150.size 2 20 0.000000 50 NaN 5000000.0 5000000.0 1.0 none 1 level below\n", "patch.opening.50_150.size 3 30 0.000000 75 NaN 11250000.0 11250000.0 1.0 none 1 level below\n" ] } ], "source": [ "print(pd.read_csv(work / \"run\" / \"report_targets.csv\").to_string(index=False))" ] }, { "cell_type": "markdown", "id": "63343651", "metadata": {}, "source": [ "## Watch the classes per period\n", "\n", "`patch_accounts.csv` has one column per size class and sub-account, one row per period. The\n", "share in the 50-150 ha class is `...50_150.size`, in percent." ] }, { "cell_type": "code", "execution_count": 5, "id": "902b99f3", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:27:01.951320Z", "iopub.status.busy": "2026-10-17T23:27:01.951006Z", "iopub.status.idle": "2026-10-17T23:27:01.968335Z", "shell.execute_reply": "2026-10-17T23:27:01.967184Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " offset patch.opening.0_10.size patch.opening.10_50.size patch.opening.50_150.size\n", " 0.0 0.0 100.0 0.0\n", " 1.0 0.0 100.0 0.0\n", " 2.0 0.0 100.0 0.0\n", " 3.0 0.0 100.0 0.0\n", " 4.0 0.0 100.0 0.0\n", " 5.0 0.0 100.0 0.0\n", " 6.0 0.0 100.0 0.0\n", " 7.0 0.0 100.0 0.0\n", " 8.0 0.0 100.0 0.0\n", " 9.0 0.0 100.0 0.0\n", " 10.0 0.0 100.0 0.0\n", " 11.0 0.0 100.0 0.0\n", " 12.0 0.0 100.0 0.0\n", " 13.0 0.0 100.0 0.0\n", " 14.0 0.0 100.0 0.0\n", " 15.0 0.0 100.0 0.0\n", " 16.0 0.0 100.0 0.0\n", " 17.0 0.0 100.0 0.0\n", " 18.0 0.0 100.0 0.0\n", " 19.0 0.0 100.0 0.0\n", " 20.0 0.0 100.0 0.0\n", " 21.0 0.0 100.0 0.0\n", " 22.0 0.0 100.0 0.0\n", " 23.0 0.0 100.0 0.0\n", " 24.0 0.0 100.0 0.0\n", " 25.0 0.0 100.0 0.0\n", " 26.0 0.0 100.0 0.0\n", " 27.0 0.0 100.0 0.0\n", " 28.0 0.0 100.0 0.0\n", " 29.0 0.0 100.0 0.0\n", " 30.0 0.0 100.0 0.0\n", " 31.0 0.0 100.0 0.0\n", " 32.0 0.0 100.0 0.0\n", " 33.0 0.0 100.0 0.0\n", " 34.0 0.0 100.0 0.0\n", " 35.0 0.0 100.0 0.0\n", " 36.0 0.0 100.0 0.0\n", " 37.0 0.0 100.0 0.0\n", " 38.0 0.0 100.0 0.0\n", " 39.0 0.0 100.0 0.0\n", " 40.0 0.0 100.0 0.0\n", " 41.0 0.0 100.0 0.0\n", " 42.0 0.0 100.0 0.0\n", " 43.0 0.0 100.0 0.0\n", " 44.0 0.0 100.0 0.0\n", " 45.0 0.0 100.0 0.0\n", " 46.0 0.0 100.0 0.0\n", " 47.0 0.0 100.0 0.0\n", " 48.0 0.0 100.0 0.0\n", " 49.0 0.0 100.0 0.0\n", " 50.0 0.0 100.0 0.0\n", " 51.0 0.0 100.0 0.0\n", " 52.0 0.0 100.0 0.0\n", " 53.0 0.0 100.0 0.0\n", " 54.0 0.0 100.0 0.0\n", " 55.0 0.0 100.0 0.0\n", " 56.0 0.0 100.0 0.0\n", " 57.0 0.0 100.0 0.0\n", " 58.0 0.0 100.0 0.0\n", " 59.0 0.0 100.0 0.0\n", " 60.0 0.0 100.0 0.0\n", " 61.0 0.0 100.0 0.0\n", " 62.0 0.0 100.0 0.0\n", " 63.0 0.0 100.0 0.0\n", " 64.0 0.0 100.0 0.0\n", " 65.0 0.0 100.0 0.0\n", " 66.0 0.0 100.0 0.0\n", " 67.0 0.0 100.0 0.0\n", " 68.0 0.0 100.0 0.0\n", " 69.0 0.0 100.0 0.0\n", " 70.0 0.0 100.0 0.0\n", " 71.0 0.0 100.0 0.0\n", " 72.0 0.0 100.0 0.0\n", " 73.0 0.0 100.0 0.0\n", " 74.0 0.0 100.0 0.0\n", " 75.0 0.0 100.0 0.0\n", " 76.0 0.0 100.0 0.0\n", " 77.0 0.0 100.0 0.0\n", " 78.0 0.0 100.0 0.0\n", " 79.0 0.0 100.0 0.0\n", " 80.0 0.0 100.0 0.0\n", " 81.0 0.0 100.0 0.0\n", " 82.0 0.0 100.0 0.0\n", " 83.0 0.0 100.0 0.0\n", " 84.0 0.0 100.0 0.0\n", " 85.0 0.0 100.0 0.0\n", " 86.0 0.0 100.0 0.0\n", " 87.0 0.0 100.0 0.0\n", " 88.0 0.0 100.0 0.0\n", " 89.0 0.0 100.0 0.0\n", " 90.0 0.0 100.0 0.0\n", " 91.0 0.0 100.0 0.0\n", " 92.0 0.0 100.0 0.0\n", " 93.0 0.0 100.0 0.0\n", " 94.0 0.0 100.0 0.0\n", " 95.0 0.0 100.0 0.0\n", " 96.0 0.0 100.0 0.0\n", " 97.0 0.0 100.0 0.0\n", " 98.0 0.0 100.0 0.0\n", " 99.0 0.0 100.0 0.0\n" ] } ], "source": [ "accounts = pd.read_csv(work / \"run\" / \"patch_accounts.csv\")\n", "shares = accounts[[\"offset\", \"patch.opening.0_10.size\", \"patch.opening.10_50.size\", \"patch.opening.50_150.size\"]]\n", "print(shares.to_string(index=False))" ] }, { "cell_type": "markdown", "id": "2e46cff8", "metadata": {}, "source": [ "The first three periods are the ramp — 25, then 50, then 75 percent of the opening area in\n", "the 50-150 ha class. The search meets the first two (63.8 percent) and falls short of the third,\n", "which is the honest outcome of a weight of 2000 against a squared miss: 11.2 points of shortfall\n", "cost 249 340. Note what the shares do *not* do: they stay steady across the horizon, because the\n", "40-year rotation keeps refreshing the openings into the same class, which is the structure the\n", "target is there to hold. The run's report prices exactly the shares the search found; compare it\n", "with `patch_metrics.csv` from a simulation of the same schedule, which is the check worth making\n", "on any patch result." ] }, { "cell_type": "markdown", "id": "13d8a312", "metadata": {}, "source": [ "## Where to look next\n", "\n", "* `docs/howto/patch-targets.rst` explains the size classes, `search_distance` and the operators.\n", "* `docs/reference/spatial.rst` specifies the topology, the metrics and the opening rules." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "python", "version": "3.12.3" } }, "nbformat": 4, "nbformat_minor": 5 }