{ "cells": [ { "cell_type": "markdown", "id": "86eeb24f", "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.\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "ccccd207", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:27:02.879130Z", "iopub.status.busy": "2026-10-17T23:27:02.878710Z", "iopub.status.idle": "2026-10-17T23:27:02.888137Z", "shell.execute_reply": "2026-10-17T23:27:02.886638Z" } }, "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": "d5d31c1e", "metadata": {}, "source": [ "# Route products to mills\n", "\n", "The sample estate ships a road network with two mills at opposite ends, so the least-haul-cost\n", "destination differs across the estate. This notebook routes a schedule and reads the accounts\n", "the routing produces, then constrains the haul cost in a search." ] }, { "cell_type": "markdown", "id": "58825d80", "metadata": {}, "source": [ "## The network\n", "\n", "One access vertex per grid row, a road along them, a spur to `destination.MILL1` at the west end\n", "and one to `destination.MILL2` at the east end. `examples/estate/route.yaml` names the four\n", "tables and defines the route accounts: haul and volume per mill, and a total haul." ] }, { "cell_type": "code", "execution_count": 2, "id": "624a7d3c", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:27:02.892140Z", "iopub.status.busy": "2026-10-17T23:27:02.891755Z", "iopub.status.idle": "2026-10-17T23:27:03.201017Z", "shell.execute_reply": "2026-10-17T23:27:03.199697Z" } }, "outputs": [ { "data": { "text/plain": [ "87" ] }, "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/routes\")\n", "work.mkdir(parents=True, exist_ok=True)\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))" ] }, { "cell_type": "code", "execution_count": 3, "id": "290b1017", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:27:03.204278Z", "iopub.status.busy": "2026-10-17T23:27:03.204100Z", "iopub.status.idle": "2026-10-17T23:27:04.377640Z", "shell.execute_reply": "2026-10-17T23:27:04.375635Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1;32mSimulation complete\u001b[0m → tmp/examples/routes/run\n" ] } ], "source": [ "run(\"ws4 simulate --dataset tmp/examples/estate/compiled --schedule tmp/examples/routes/schedule.csv\"\n", " \" --years 60 --topology examples/estate/topology.csv\"\n", " \" --route-config examples/estate/route.yaml --out tmp/examples/routes/run\")" ] }, { "cell_type": "code", "execution_count": 4, "id": "fbfd63ec", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:27:04.385380Z", "iopub.status.busy": "2026-10-17T23:27:04.384914Z", "iopub.status.idle": "2026-10-17T23:27:04.412565Z", "shell.execute_reply": "2026-10-17T23:27:04.410982Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " volume length_m haul_cost\n", "destination \n", "destination.MILL1 3423.514286 8000.0 0.4\n", "destination.MILL2 5370.300000 12000.0 0.6\n", "\n", " block_id destination volume length_m haul_cost\n", " 1 destination.MILL1 1918.714286 4000.0 0.20\n", " 2 destination.MILL1 1504.800000 4000.0 0.20\n", " 9 destination.MILL2 1272.000000 4000.0 0.20\n", " 10 destination.MILL2 1932.000000 4000.0 0.20\n", " 57 destination.MILL2 243.000000 1000.0 0.05\n", " 58 destination.MILL2 294.300000 1000.0 0.05\n", " 63 destination.MILL2 684.000000 1000.0 0.05\n", " 64 destination.MILL2 945.000000 1000.0 0.05\n" ] } ], "source": [ "routed = pd.read_csv(work / \"run\" / \"route_values.csv\")\n", "print(routed.groupby(\"destination\")[[\"volume\", \"length_m\", \"haul_cost\"]].sum().to_string())\n", "print()\n", "print(routed[[\"block_id\", \"destination\", \"volume\", \"length_m\", \"haul_cost\"]].to_string(index=False))" ] }, { "cell_type": "markdown", "id": "cadfbcc9", "metadata": {}, "source": [ "Every load went to the cheaper mill for its block: the choice is the sum of the segment haul\n", "rates along the route, so a block near the middle can be closer to one mill in distance and still\n", "cheaper to send to the other." ] }, { "cell_type": "code", "execution_count": 5, "id": "65ede9e8", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:27:04.415986Z", "iopub.status.busy": "2026-10-17T23:27:04.415774Z", "iopub.status.idle": "2026-10-17T23:27:04.425233Z", "shell.execute_reply": "2026-10-17T23:27:04.423867Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " offset account value\n", " 0 product.Mill1.Yield 3423.514286\n", " 0 product.Mill2.Yield 5370.300000\n", " 0 route.Mill1.haul 684.702857\n", " 0 route.Mill2.haul 749.115000\n", " 0 route.Total.haul 1433.817857\n" ] } ], "source": [ "values = pd.read_csv(work / \"run\" / \"account_values.csv\")\n", "print(values[(values.offset == 0) & values.account.str.startswith((\"route.\", \"product.Mill\"))].to_string(index=False))" ] }, { "cell_type": "markdown", "id": "f23915b3", "metadata": {}, "source": [ "## Constrain the haul cost in a search" ] }, { "cell_type": "code", "execution_count": 6, "id": "2c558cf0", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:27:04.428323Z", "iopub.status.busy": "2026-10-17T23:27:04.428076Z", "iopub.status.idle": "2026-10-17T23:30:46.080835Z", "shell.execute_reply": "2026-10-17T23:30:46.078916Z" }, "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/routes/targets.yaml\"\n", " \" --years 100 --iterations 20000 --route-config examples/estate/route.yaml --threads 1\"\n", " \" --out tmp/examples/routes/search\")" ] }, { "cell_type": "code", "execution_count": 7, "id": "fd7efd8e", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:30:46.084287Z", "iopub.status.busy": "2026-10-17T23:30:46.083836Z", "iopub.status.idle": "2026-10-17T23:30:46.105367Z", "shell.execute_reply": "2026-10-17T23:30:46.103890Z" } }, "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 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", "\n", " PERIOD YEAR PERIODWIDTH LENGTH BUILTLENGTH BUILD_EXPENSE HAUL_EXPENSE MAINTAIN_EXPENSE TOTAL VOLUME AVERAGEHAULDIST AVERAGEBUILDCOST AVERAGEHAULCOST AVERAGEMAINTCOST\n", " 0 0 1 3500.0 3500.0 105000.0 213.675 10500.0 115713.675 1221.000000 3.500000 85.995086 0.175000 8.599509\n", " 2 2 1 3000.0 0.0 0.0 324.540 9000.0 9324.540 2797.200000 2.320463 0.000000 0.116023 3.217503\n", " 6 6 1 3500.0 0.0 0.0 380.175 10500.0 10880.175 2172.428571 3.500000 0.000000 0.175000 4.833300\n" ] } ], "source": [ "print(pd.read_csv(work / \"search\" / \"report_targets.csv\").to_string(index=False))\n", "print()\n", "print(pd.read_csv(work / \"search\" / \"route_cost_report.csv\").head(3).to_string(index=False))" ] }, { "cell_type": "markdown", "id": "4bec26ea", "metadata": {}, "source": [ "## Where to look next\n", "\n", "* `docs/howto/route-products.rst` walks through the tables and the route configuration.\n", "* `docs/reference/roads.rst` specifies the network, the routing and the route outputs." ] } ], "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 }