{ "cells": [ { "cell_type": "markdown", "id": "e6adbacd", "metadata": {}, "source": [ "# Quickstart: compile, simulate, target, search\n", "\n", "The command-line walkthrough, run here on the two-block example in `examples/synthetic`.\n", "Its numbers are checkable by hand: with no schedule the natural-track volume at offset 0 is\n", "`3.0 * 120 + 2.0 * 170 = 700`, and clearing block 1 leaves `2.0 * 170 = 340`.\n", "\n", "This one is a **command-line** session: every step is a `ws4` command.\n" ] }, { "cell_type": "markdown", "id": "db8150fb", "metadata": {}, "source": [ "## Compile a dataset" ] }, { "cell_type": "code", "execution_count": 1, "id": "8ab498ed", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:48.717877Z", "iopub.status.busy": "2026-10-17T20:20:48.717441Z", "iopub.status.idle": "2026-10-17T20:20:48.728730Z", "shell.execute_reply": "2026-10-17T20:20:48.725293Z" } }, "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": "code", "execution_count": 2, "id": "f4599044", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:48.732434Z", "iopub.status.busy": "2026-10-17T20:20:48.732009Z", "iopub.status.idle": "2026-10-17T20:20:49.654452Z", "shell.execute_reply": "2026-10-17T20:20:49.652644Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1;32mBuilt dataset\u001b[0m → tmp/examples/quickstart/compiled\n" ] } ], "source": [ "run(\"ws4 build --xml examples/synthetic/recipe.xml --fragments examples/synthetic/fragments.csv --out tmp/examples/quickstart/compiled\")" ] }, { "cell_type": "code", "execution_count": 3, "id": "07561330", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:49.658219Z", "iopub.status.busy": "2026-10-17T20:20:49.657774Z", "iopub.status.idle": "2026-10-17T20:20:50.592671Z", "shell.execute_reply": "2026-10-17T20:20:50.591150Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1;32mDataset is valid\u001b[0m → tmp/examples/quickstart/compiled\n" ] } ], "source": [ "run(\"ws4 validate --dataset tmp/examples/quickstart/compiled\")" ] }, { "cell_type": "markdown", "id": "bc726fed", "metadata": {}, "source": [ "## Simulate a schedule\n", "\n", "A schedule is a CSV of `block_id`, `treatment`, and `offset`, where the offset is the number of years after the start of the simulation." ] }, { "cell_type": "code", "execution_count": 4, "id": "f68f8a16", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:50.595902Z", "iopub.status.busy": "2026-10-17T20:20:50.595698Z", "iopub.status.idle": "2026-10-17T20:20:51.504419Z", "shell.execute_reply": "2026-10-17T20:20:51.502821Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1;32mSimulation complete\u001b[0m → tmp/examples/quickstart/sim\n" ] } ], "source": [ "from pathlib import Path\n", "\n", "work = Path(\"tmp/examples/quickstart\")\n", "work.mkdir(parents=True, exist_ok=True)\n", "(work / \"schedule.csv\").write_text(\"block_id,treatment,offset\\n1,CC,0\\n\")\n", "\n", "run(\"ws4 simulate --dataset tmp/examples/quickstart/compiled --schedule tmp/examples/quickstart/schedule.csv --years 5 --out tmp/examples/quickstart/sim\")" ] }, { "cell_type": "code", "execution_count": 5, "id": "56eefc34", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:51.508124Z", "iopub.status.busy": "2026-10-17T20:20:51.507680Z", "iopub.status.idle": "2026-10-17T20:20:51.813987Z", "shell.execute_reply": "2026-10-17T20:20:51.812635Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " offset account value\n", " -1 feature.Volume 700.0\n", " 0 feature.Volume 340.0\n", " 0 product.Volume 360.0\n", " 1 feature.Volume 360.0\n" ] } ], "source": [ "import pandas as pd\n", "\n", "values = pd.read_csv(work / \"sim\" / \"account_values.csv\")\n", "print(values.head(4).to_string(index=False))" ] }, { "cell_type": "markdown", "id": "8d94440b", "metadata": {}, "source": [ "`340.0` is the figure from the example: block 1's 3.0 ha of natural track is gone, and block\n", "2's 2.0 ha of natural volume remains." ] }, { "cell_type": "markdown", "id": "8e76dbb7", "metadata": {}, "source": [ "## State a target and check the run against it" ] }, { "cell_type": "code", "execution_count": 6, "id": "e960e6e8", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:51.817534Z", "iopub.status.busy": "2026-10-17T20:20:51.817360Z", "iopub.status.idle": "2026-10-17T20:20:52.679327Z", "shell.execute_reply": "2026-10-17T20:20:52.677764Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1;32mReport written\u001b[0m → tmp/examples/quickstart/sim\n" ] } ], "source": [ "(work / \"targets.yaml\").write_text(\n", " \"targets:\\n\"\n", " \"- account: feature.Volume\\n\"\n", " \" period: 1\\n\"\n", " \" minimum: 700\\n\"\n", " \" maximum: 700\\n\"\n", " \" period_width: 1\\n\"\n", ")\n", "\n", "run(\"ws4 report --run tmp/examples/quickstart/sim --targets tmp/examples/quickstart/targets.yaml\")" ] }, { "cell_type": "code", "execution_count": 7, "id": "17ecb523", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:52.682992Z", "iopub.status.busy": "2026-10-17T20:20:52.682508Z", "iopub.status.idle": "2026-10-17T20:20:52.695480Z", "shell.execute_reply": "2026-10-17T20:20:52.694069Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " account period year value minimum maximum raw_penalty penalty scale normalization priority kind status\n", "feature.Volume 1 1 340.0 700 700 360.0 360.0 1.0 none 1 level below\n" ] } ], "source": [ "print(pd.read_csv(work / \"sim\" / \"report_targets.csv\").to_string(index=False))" ] }, { "cell_type": "markdown", "id": "421f63e2", "metadata": {}, "source": [ "The status is `below`: clearing block 1 drops the natural volume to 340 against a floor of\n", "700, and the penalty is the shortfall." ] }, { "cell_type": "markdown", "id": "118b2f12", "metadata": {}, "source": [ "## Search for a schedule that meets it" ] }, { "cell_type": "code", "execution_count": 8, "id": "c2356576", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:52.699063Z", "iopub.status.busy": "2026-10-17T20:20:52.698650Z", "iopub.status.idle": "2026-10-17T20:20:53.672326Z", "shell.execute_reply": "2026-10-17T20:20:53.670455Z" }, "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 │ 500 │\n", "│ patience │ 0 │\n", "│ reversion │ 0 │\n", "│ seed │ 1 │\n", "│ metaheuristic │ sa │\n", "│ threshold │ 1.0 │\n", "│ starts │ 1 │\n", "│ initial_schedule_path │ None │\n", "│ blocks_scheduled │ 0 │\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': 4, 'accounts': {'feature.Volume': 750.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': 'fae361c3f333850d45b1509d95be0a183e4d809fb133a2b102721196aeb78f2a'}, {'path': 'fragments.csv', 'sha256': │\n", "│ │ '9fe1655c619cd8b40eabdba84af8ed986c1cedab343855ba67ba46cb84da018a'}], 'manifest_sha256': '84ed52a984442dfbf148a67582869c872915e69c5adfb09f057d3107b10f2600'} │\n", "└─────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘\n" ] } ], "source": [ "run(\"ws4 optimize --dataset tmp/examples/quickstart/compiled --targets tmp/examples/quickstart/targets.yaml --years 5 --time-limit 00:00:05 --seed 1 --threads 1 --out tmp/examples/quickstart/opt\")" ] }, { "cell_type": "code", "execution_count": 9, "id": "fd0dbf83", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:53.676305Z", "iopub.status.busy": "2026-10-17T20:20:53.675853Z", "iopub.status.idle": "2026-10-17T20:20:53.684481Z", "shell.execute_reply": "2026-10-17T20:20:53.682839Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{'incumbent_objective': 0.0, 'blocks_scheduled': 0, 'iterations': 500, 'seed': 1, 'status': 'ok'}\n", "block_id,treatment,offset\n", "\n" ] } ], "source": [ "import json\n", "\n", "summary = json.loads((work / \"opt\" / \"summary.json\").read_text())\n", "print({key: summary[key] for key in (\"incumbent_objective\", \"blocks_scheduled\", \"iterations\", \"seed\", \"status\")})\n", "print((work / \"opt\" / \"schedule.csv\").read_text())" ] }, { "cell_type": "markdown", "id": "880dcdc5", "metadata": {}, "source": [ "The incumbent is an **empty schedule**: leaving the stand alone holds `feature.Volume` at 700,\n", "which meets the floor, so nothing can beat a penalty of zero. On a two-block landscape that is\n", "the whole answer." ] }, { "cell_type": "markdown", "id": "143156e1", "metadata": {}, "source": [ "## Watch a search\n", "\n", "`ws4 watch` paints the realized-versus-target window; `--plain` prints one frame instead of the\n", "live view, which is what a notebook wants." ] }, { "cell_type": "code", "execution_count": 10, "id": "a5a95835", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:53.688245Z", "iopub.status.busy": "2026-10-17T20:20:53.687781Z", "iopub.status.idle": "2026-10-17T20:20:54.619229Z", "shell.execute_reply": "2026-10-17T20:20:54.617391Z" }, "tags": [ "no-drift-check" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[36m╭─\u001b[0m\u001b[36m───────────────────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\u001b[36m ws4 watch \u001b[0m\u001b[36m───────────────────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n", "\u001b[36m│\u001b[0m \u001b[1mfeature.Volume\u001b[0m objective (sum of penalties): 0 \u001b[36m│\u001b[0m\n", "\u001b[36m│\u001b[0m iteration 200/200 6642.31 eval/s elapsed 0.0s seed 1 sa \u001b[36m│\u001b[0m\n", "\u001b[36m╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n", "\n", "\u001b[1mfeature.Volume Z +0 \u001b[0m\n", "\u001b[37m 748.1 \u001b[0m\u001b[37m│\u001b[0m \u001b[37m::\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[37m::\u001b[0m\u001b[37m::\u001b[0m\u001b[32m##\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m \n", " \u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m \n", "\u001b[37m 0 \u001b[0m\u001b[37m│\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m\u001b[32m##\u001b[0m \n", "\u001b[37m └\u001b[0m\u001b[37m──────────\u001b[0m\u001b[37m \u001b[0m\n", " \u001b[37m1 \u001b[0m\u001b[37m2 \u001b[0m\u001b[37m3 \u001b[0m\u001b[37m4 \u001b[0m\u001b[37m5 \u001b[0m \n", " \n", "\u001b[3m feature.Volume — per 1-year period \u001b[0m \n", "\u001b[1m \u001b[0m\u001b[1mperiod\u001b[0m\u001b[1m \u001b[0m\u001b[1m \u001b[0m\u001b[1mmin\u001b[0m\u001b[1m \u001b[0m\u001b[1m \u001b[0m\u001b[1mrealized\u001b[0m\u001b[1m \u001b[0m\u001b[1m \u001b[0m\u001b[1mmax\u001b[0m\u001b[1m \u001b[0m\u001b[1m \u001b[0m\u001b[1mshortfall\u001b[0m\u001b[1m \u001b[0m\u001b[1m \u001b[0m\u001b[1mexcess\u001b[0m\u001b[1m \u001b[0m\u001b[1m \u001b[0m\u001b[1mstatus\u001b[0m\u001b[1m \u001b[0m \n", " 1 700 700 700 0 0 \u001b[32mok\u001b[0m \n", " 2 — 712.5 — 0 0 \u001b[32mok\u001b[0m \n", " 3 — 350 — 0 0 \u001b[32mok\u001b[0m \n", " 4 — 370 — 0 0 \u001b[32mok\u001b[0m \n", " 5 — 390 — 0 0 \u001b[32mok\u001b[0m \n", "\u001b[3m Watch 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", "│ objective │ 0 │\n", "│ penalty │ 0 │\n", "│ evaluations │ 200 │\n", "│ blocks │ 0 │\n", "│ elapsed │ 0.03011 │\n", "└─────────────┴─────────┘\n" ] } ], "source": [ "run(\"ws4 watch --dataset tmp/examples/quickstart/compiled --targets tmp/examples/quickstart/targets.yaml --account feature.Volume --years 5 --period-width 1 --iterations 200 --plain\")" ] }, { "cell_type": "markdown", "id": "8a9f2c2f", "metadata": {}, "source": [ "## Where to go next\n", "\n", "* The how-to guides, for targets with teeth, even flow, and patch size distributions.\n", "* `020_even_flow.ipynb`, which uses the Python API on a larger estate." ] } ], "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 }