No WS4 command here uses shell magic: every one goes through this helper, which is also how you would drive the command line from any script.
This one is the library path for the loop, with one compile through the library.
[1]:
import subprocess
def run(command: str) -> None:
"""Run a WS4 command, printing what it printed."""
result = subprocess.run(command, shell=True, text=True, capture_output=True)
print((result.stdout or result.stderr).strip())
result.check_returncode()
Sweep a parameter
The command line is the fastest way to run one study; the Python API is the way to run many. This notebook sweeps one number — the floor on harvested volume — and collects the results into a frame, which is the shape of most sensitivity work.
The loop
Every run writes the same files, so a sweep is a loop that reads summary.json and the target report back.
[2]:
import json
from pathlib import Path
import pandas as pd
from ws4.build.compiler import build_canonical_dataset
from ws4.opt.engine import OptimizeConfig, Optimizer
work = Path("tmp/examples/sweep")
work.mkdir(parents=True, exist_ok=True)
dataset = build_canonical_dataset("examples/estate/recipe.xml", "examples/estate/fragments.csv", work / "compiled")
print(dataset)
tmp/examples/sweep/compiled
[3]:
rows = []
for floor in (10_000, 20_000, 30_000):
targets = work / f"targets-{floor}.yaml"
targets.write_text(
"targets:\n"
"- account: product.Harvested.CC\n"
" period: 1\n"
f" minimum: {floor}\n"
" period_width: 10\n"
"- account: patch.opening.50_150.size\n"
" period: 1\n"
" minimum: 30\n"
" min_weight: 2000\n"
" shape: non_linear\n"
" period_width: 10\n"
)
out = work / f"run-{floor}"
optimizer = Optimizer.from_dataset(
dataset,
OptimizeConfig(years=100, iterations=2000, seed=1, targets_path=str(targets),
topology_path="examples/estate/topology.csv",
patch_accounts_path="examples/estate/patches.yaml",
merge_weight=0.5, split_weight=0.2, cluster_weight=0.3, threads=1),
)
summary = optimizer.run(out)
report = pd.read_csv(out / "report_targets.csv")
rows.append({
"floor": floor,
"objective": round(summary["incumbent_objective"], 1),
"treatments": summary["blocks_scheduled"],
"volume_share": float(report.loc[report.account == "product.Harvested.CC", "value"].iloc[0]),
"patch_met": report.loc[report.account.str.startswith("patch"), "status"].iloc[0],
})
print(pd.DataFrame(rows).to_string(index=False))
floor objective treatments volume_share patch_met
10000 0.0 12 12156.000000 below
20000 -0.0 18 20848.200000 below
30000 -0.0 29 30218.142857 below
The frame is the point: one row per configuration, with the objective and the target statuses beside the parameter. A spread in the objective across seeds, or a target that flips between met and below between neighbouring settings, is what tells you whether a result is worth reporting.
Where to look next
docs/howto/automate-a-study.mdcollects the patterns: in-memory targets, hand-driven solvers, and the island model.docs/reference/optimizer.rstspecifies the objective and the search stack.