{ "cells": [ { "cell_type": "markdown", "id": "a62ecd68", "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 the **library** path for the loop, with one compile through the library.\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "158b4eed", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:30:46.844324Z", "iopub.status.busy": "2026-10-17T23:30:46.843889Z", "iopub.status.idle": "2026-10-17T23:30:46.852823Z", "shell.execute_reply": "2026-10-17T23:30:46.851340Z" } }, "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": "86bab0a2", "metadata": {}, "source": [ "# Sweep a parameter\n", "\n", "The command line is the fastest way to run one study; the Python API is the way to run many.\n", "This notebook sweeps one number — the floor on harvested volume — and collects the results into\n", "a frame, which is the shape of most sensitivity work." ] }, { "cell_type": "markdown", "id": "4a432f1c", "metadata": {}, "source": [ "## The loop\n", "\n", "Every run writes the same files, so a sweep is a loop that reads `summary.json` and the target\n", "report back." ] }, { "cell_type": "code", "execution_count": 2, "id": "5c0064b2", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:30:46.856591Z", "iopub.status.busy": "2026-10-17T23:30:46.856192Z", "iopub.status.idle": "2026-10-17T23:30:47.493254Z", "shell.execute_reply": "2026-10-17T23:30:47.492179Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "tmp/examples/sweep/compiled\n" ] } ], "source": [ "import json\n", "from pathlib import Path\n", "\n", "import pandas as pd\n", "from ws4.build.compiler import build_canonical_dataset\n", "from ws4.opt.engine import OptimizeConfig, Optimizer\n", "\n", "work = Path(\"tmp/examples/sweep\")\n", "work.mkdir(parents=True, exist_ok=True)\n", "dataset = build_canonical_dataset(\"examples/estate/recipe.xml\", \"examples/estate/fragments.csv\", work / \"compiled\")\n", "print(dataset)" ] }, { "cell_type": "code", "execution_count": 3, "id": "9cd575c3", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T23:30:47.497100Z", "iopub.status.busy": "2026-10-17T23:30:47.496910Z", "iopub.status.idle": "2026-10-17T23:30:50.477287Z", "shell.execute_reply": "2026-10-17T23:30:50.476128Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " floor objective treatments volume_share patch_met\n", " 10000 0.0 12 12156.000000 below\n", " 20000 -0.0 18 20848.200000 below\n", " 30000 -0.0 29 30218.142857 below\n" ] } ], "source": [ "rows = []\n", "for floor in (10_000, 20_000, 30_000):\n", " targets = work / f\"targets-{floor}.yaml\"\n", " targets.write_text(\n", " \"targets:\\n\"\n", " \"- account: product.Harvested.CC\\n\"\n", " \" period: 1\\n\"\n", " f\" minimum: {floor}\\n\"\n", " \" period_width: 10\\n\"\n", " \"- account: patch.opening.50_150.size\\n\"\n", " \" period: 1\\n\"\n", " \" minimum: 30\\n\"\n", " \" min_weight: 2000\\n\"\n", " \" shape: non_linear\\n\"\n", " \" period_width: 10\\n\"\n", " )\n", " out = work / f\"run-{floor}\"\n", " optimizer = Optimizer.from_dataset(\n", " dataset,\n", " OptimizeConfig(years=100, iterations=2000, seed=1, targets_path=str(targets),\n", " topology_path=\"examples/estate/topology.csv\",\n", " patch_accounts_path=\"examples/estate/patches.yaml\",\n", " merge_weight=0.5, split_weight=0.2, cluster_weight=0.3, threads=1),\n", " )\n", " summary = optimizer.run(out)\n", " report = pd.read_csv(out / \"report_targets.csv\")\n", " rows.append({\n", " \"floor\": floor,\n", " \"objective\": round(summary[\"incumbent_objective\"], 1),\n", " \"treatments\": summary[\"blocks_scheduled\"],\n", " \"volume_share\": float(report.loc[report.account == \"product.Harvested.CC\", \"value\"].iloc[0]),\n", " \"patch_met\": report.loc[report.account.str.startswith(\"patch\"), \"status\"].iloc[0],\n", " })\n", "\n", "print(pd.DataFrame(rows).to_string(index=False))" ] }, { "cell_type": "markdown", "id": "b6bbde25", "metadata": {}, "source": [ "The frame is the point: one row per configuration, with the objective and the target statuses\n", "beside the parameter. A spread in the objective across seeds, or a target that flips between\n", "`met` and `below` between neighbouring settings, is what tells you whether a result is worth\n", "reporting." ] }, { "cell_type": "markdown", "id": "4af952c8", "metadata": {}, "source": [ "## Where to look next\n", "\n", "* `docs/howto/automate-a-study.md` collects the patterns: in-memory targets, hand-driven solvers,\n", " and the island model.\n", "* `docs/reference/optimizer.rst` specifies the objective and the search stack." ] } ], "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 }