{ "cells": [ { "cell_type": "code", "execution_count": 1, "id": "e90e221a", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:03:16.342041Z", "iopub.status.busy": "2026-10-17T23:03:16.341560Z", "iopub.status.idle": "2026-10-17T23:03:16.350839Z", "shell.execute_reply": "2026-10-17T23:03:16.349301Z" } }, "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()\n" ] }, { "cell_type": "markdown", "id": "04da7073", "metadata": {}, "source": [ "# The sample estate\n", "\n", "`examples/estate` is a small self-contained estate: 64 blocks on an 8 x 8 grid, one clearcut\n", "treatment that can be applied more than once, a seral feature that marks fresh openings, and a\n", "road network with two mills. Everything below runs against it.\n", "\n", "This one is mostly a **command-line** session, with one compile through the library.\n" ] }, { "cell_type": "markdown", "id": "c0bf0c35", "metadata": {}, "source": [ "## The files\n", "\n", "| File | What it holds |\n", "| --- | --- |\n", "| `recipe.xml` | two lanes, one clearcut operable from age 40, the volume curves, and a seral curve that is 1 while an opening is fresh |\n", "| `fragments.csv` | 64 blocks, 8-12 ha, ages 0-100, all natural |\n", "| `topology.csv` | the grid adjacency that makes adjacent openings a patch |\n", "| `vertices.csv`, `segments.csv`, `destinations.csv`, `linkages.csv` | the road network and the two mills |\n", "| `route.yaml`, `patches.yaml`, `eligibility.csv` | the route configuration and the patch account |\n" ] }, { "cell_type": "markdown", "id": "b98f8bad", "metadata": {}, "source": [ "## Compile it" ] }, { "cell_type": "code", "execution_count": 2, "id": "92c24621", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:03:16.354207Z", "iopub.status.busy": "2026-10-17T23:03:16.353813Z", "iopub.status.idle": "2026-10-17T23:03:16.792102Z", "shell.execute_reply": "2026-10-17T23:03:16.790654Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "tmp/examples/estate/compiled\n" ] } ], "source": [ "from pathlib import Path\n", "\n", "from ws4.build.compiler import build_canonical_dataset\n", "\n", "work = Path(\"tmp/examples/estate\")\n", "work.mkdir(parents=True, exist_ok=True)\n", "dataset = build_canonical_dataset(\n", " \"examples/estate/recipe.xml\", \"examples/estate/fragments.csv\", work / \"compiled\"\n", ")\n", "print(dataset)" ] }, { "cell_type": "markdown", "id": "cf00d7ff", "metadata": {}, "source": [ "## Simulate a schedule: openings, and two mills\n", "\n", "Cutting eight blocks at offset 0 opens patches on the grid and ships the volume to whichever mill\n", "is cheaper to reach." ] }, { "cell_type": "code", "execution_count": 3, "id": "a1d35fef", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:03:16.794876Z", "iopub.status.busy": "2026-10-17T23:03:16.794696Z", "iopub.status.idle": "2026-10-17T23:03:17.754751Z", "shell.execute_reply": "2026-10-17T23:03:17.753434Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1;32mSimulation complete\u001b[0m → tmp/examples/estate/run\n" ] } ], "source": [ "import pandas as pd\n", "\n", "schedule = pd.DataFrame({\"block_id\": [1, 2, 9, 10, 57, 58, 63, 64], \"treatment\": [\"CC\"] * 8, \"offset\": [0] * 8})\n", "(work / \"schedule.csv\").write_text(schedule.to_csv(index=False))\n", "\n", "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\")" ] }, { "cell_type": "code", "execution_count": 4, "id": "1f3b64ae", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:03:17.758128Z", "iopub.status.busy": "2026-10-17T23:03:17.757633Z", "iopub.status.idle": "2026-10-17T23:03:17.769017Z", "shell.execute_reply": "2026-10-17T23:03:17.767709Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " offset account value\n", " -1 feature.Seral.regen 0.000000\n", " -1 feature.Volume.managed 0.000000\n", " -1 feature.Volume.natural 80026.785714\n" ] } ], "source": [ "values = pd.read_csv(work / \"run\" / \"account_values.csv\")\n", "print(values[values.offset == -1].to_string(index=False))" ] }, { "cell_type": "markdown", "id": "dc30032e", "metadata": {}, "source": [ "`feature.Seral.regen` is the area in fresh openings — the criterion the patch account reads. The\n", "two `product.Mill*` accounts and the two haul accounts say how the volume split, and\n", "`route.Total.haul` is the duplicate account that adds them." ] }, { "cell_type": "code", "execution_count": 5, "id": "07920d76", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:03:17.771834Z", "iopub.status.busy": "2026-10-17T23:03:17.771589Z", "iopub.status.idle": "2026-10-17T23:03:17.785466Z", "shell.execute_reply": "2026-10-17T23:03:17.784310Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " volume haul_cost\n", "destination \n", "destination.MILL1 3423.514286 0.4\n", "destination.MILL2 5370.300000 0.6\n", "\n", " block_id destination volume length_m haul_cost\n", " 1 destination.MILL1 1918.714286 4000.0 0.2\n", " 2 destination.MILL1 1504.800000 4000.0 0.2\n", " 9 destination.MILL2 1272.000000 4000.0 0.2\n", " 10 destination.MILL2 1932.000000 4000.0 0.2\n" ] } ], "source": [ "routed = pd.read_csv(work / \"run\" / \"route_values.csv\")\n", "print(routed.groupby(\"destination\")[[\"volume\", \"haul_cost\"]].sum().to_string())\n", "print()\n", "print(routed[[\"block_id\", \"destination\", \"volume\", \"length_m\", \"haul_cost\"]].head(4).to_string(index=False))" ] }, { "cell_type": "markdown", "id": "18a9c0b2", "metadata": {}, "source": [ "Blocks near the west end go to `destination.MILL1`, blocks further east to `destination.MILL2`:\n", "the choice is the least haul cost along the segments, not the distance to a mill." ] }, { "cell_type": "markdown", "id": "425ec0fd", "metadata": {}, "source": [ "## The openings themselves" ] }, { "cell_type": "code", "execution_count": 6, "id": "e522156a", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:03:17.788301Z", "iopub.status.busy": "2026-10-17T23:03:17.788101Z", "iopub.status.idle": "2026-10-17T23:03:17.796025Z", "shell.execute_reply": "2026-10-17T23:03:17.794782Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " offset patch_count mean_patch_area max_patch_area le5 le10 le50 over\n", " 0 3.0 27.3 42.9 0 0 3 0\n" ] } ], "source": [ "metrics = pd.read_csv(work / \"run\" / \"patch_metrics.csv\")\n", "print(metrics[metrics.offset <= 2].to_string(index=False))" ] }, { "cell_type": "markdown", "id": "8e8f8021", "metadata": {}, "source": [ "## Search, and read the run\n", "\n", "A volume floor plus a haul-cost ceiling behaves predictably, and shows the route accounts folding\n", "into the objective." ] }, { "cell_type": "code", "execution_count": 7, "id": "f3a013b5", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:03:17.798759Z", "iopub.status.busy": "2026-10-17T23:03:17.798532Z", "iopub.status.idle": "2026-10-17T23:06:55.688201Z", "shell.execute_reply": "2026-10-17T23:06:55.686637Z" }, "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 │ 0.0 │\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 │ 24 │\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': 143.49999999999997, 'feature.Volume.managed': 29307.574999999997, 'feature.Volume.natural': 99698.14285714286}} │\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": [ "(work / \"targets.yaml\").write_text(\n", " \"targets:\\n\"\n", " \"- account: product.Harvested.CC\\n\"\n", " \" period: 1\\n\"\n", " \" minimum: 20000\\n\"\n", " \" period_width: 10\\n\"\n", " \"- account: route.Total.haul\\n\"\n", " \" period: 1\\n\"\n", " \" maximum: 3000\\n\"\n", " \" period_width: 10\\n\"\n", ")\n", "\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\")" ] }, { "cell_type": "code", "execution_count": 8, "id": "c0101520", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:06:55.691913Z", "iopub.status.busy": "2026-10-17T23:06:55.691473Z", "iopub.status.idle": "2026-10-17T23:06:55.706105Z", "shell.execute_reply": "2026-10-17T23:06:55.704855Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{'incumbent_objective': 0.0, 'blocks_scheduled': 24, 'iterations': 20000, 'status': 'ok'}\n", "\n", " account period year value minimum maximum raw_penalty penalty scale normalization priority kind status\n", "product.Harvested.CC 1 10 20443.057143 20000.0 NaN 0.0 0.0 1.0 none 1 level met\n", " route.Total.haul 1 10 136.092857 NaN 3000.0 0.0 0.0 1.0 none 1 level met\n" ] } ], "source": [ "import json\n", "\n", "summary = json.loads((work / \"search\" / \"summary.json\").read_text())\n", "print({key: summary[key] for key in (\"incumbent_objective\", \"blocks_scheduled\", \"iterations\", \"status\")})\n", "print()\n", "print(pd.read_csv(work / \"search\" / \"report_targets.csv\").to_string(index=False))" ] }, { "cell_type": "markdown", "id": "0d6b1717", "metadata": {}, "source": [ "## What to look at next\n", "\n", "* `docs/howto/route-products.rst` walks through the road tables and the route configuration.\n", "* `docs/howto/patch-targets.rst` covers the patch accounts, the size classes and the shape-aware\n", " operators; a run's report and a simulation of the same schedule agree on the classes.\n", "* `docs/getting-started/architecture.rst` explains why the search prices a move instead of\n", " re-simulating." ] } ], "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 }