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 a command-line session.
[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()
Route products to mills
The sample estate ships a road network with two mills at opposite ends, so the least-haul-cost destination differs across the estate. This notebook routes a schedule and reads the accounts the routing produces, then constrains the haul cost in a search.
The network
One access vertex per grid row, a road along them, a spur to destination.MILL1 at the west end and one to destination.MILL2 at the east end. examples/estate/route.yaml names the four tables and defines the route accounts: haul and volume per mill, and a total haul.
[2]:
from pathlib import Path
import pandas as pd
work = Path("tmp/examples/routes")
work.mkdir(parents=True, exist_ok=True)
schedule = pd.DataFrame({"block_id": [1, 2, 9, 10, 57, 58, 63, 64], "treatment": ["CC"] * 8, "offset": [0] * 8})
(work / "schedule.csv").write_text(schedule.to_csv(index=False))
[2]:
87
[3]:
run("ws4 simulate --dataset tmp/examples/estate/compiled --schedule tmp/examples/routes/schedule.csv"
" --years 60 --topology examples/estate/topology.csv"
" --route-config examples/estate/route.yaml --out tmp/examples/routes/run")
Simulation complete → tmp/examples/routes/run
[4]:
routed = pd.read_csv(work / "run" / "route_values.csv")
print(routed.groupby("destination")[["volume", "length_m", "haul_cost"]].sum().to_string())
print()
print(routed[["block_id", "destination", "volume", "length_m", "haul_cost"]].to_string(index=False))
volume length_m haul_cost
destination
destination.MILL1 3423.514286 8000.0 0.4
destination.MILL2 5370.300000 12000.0 0.6
block_id destination volume length_m haul_cost
1 destination.MILL1 1918.714286 4000.0 0.20
2 destination.MILL1 1504.800000 4000.0 0.20
9 destination.MILL2 1272.000000 4000.0 0.20
10 destination.MILL2 1932.000000 4000.0 0.20
57 destination.MILL2 243.000000 1000.0 0.05
58 destination.MILL2 294.300000 1000.0 0.05
63 destination.MILL2 684.000000 1000.0 0.05
64 destination.MILL2 945.000000 1000.0 0.05
Every load went to the cheaper mill for its block: the choice is the sum of the segment haul rates along the route, so a block near the middle can be closer to one mill in distance and still cheaper to send to the other.
[5]:
values = pd.read_csv(work / "run" / "account_values.csv")
print(values[(values.offset == 0) & values.account.str.startswith(("route.", "product.Mill"))].to_string(index=False))
offset account value
0 product.Mill1.Yield 3423.514286
0 product.Mill2.Yield 5370.300000
0 route.Mill1.haul 684.702857
0 route.Mill2.haul 749.115000
0 route.Total.haul 1433.817857
Constrain the haul cost in a search
[6]:
(work / "targets.yaml").write_text(
"targets:\n"
"- account: product.Harvested.CC\n"
" period: 1\n"
" minimum: 20000\n"
" period_width: 10\n"
"- account: route.Total.haul\n"
" period: 1\n"
" maximum: 3000\n"
" period_width: 10\n"
)
run("ws4 optimize --dataset tmp/examples/estate/compiled --targets tmp/examples/routes/targets.yaml"
" --years 100 --iterations 20000 --route-config examples/estate/route.yaml --threads 1"
" --out tmp/examples/routes/search")
Optimization Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ key ┃ value ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ incumbent_objective │ 0.0 │
│ iterations │ 20000 │
│ patience │ 0 │
│ reversion │ 0 │
│ seed │ 42 │
│ metaheuristic │ sa │
│ threshold │ 1.0 │
│ starts │ 1 │
│ initial_schedule_path │ None │
│ blocks_scheduled │ 24 │
│ operators │ ['toggle', 'shift', 'swap', 'lns', 'cluster', 'coalesce', 'merge', 'split'] │
│ constraint_strategy │ penalize │
│ constraint_stats │ {'strategy': 'penalize', 'enabled': False, 'proposed': 0, 'feasible': 0, 'rejected': 0, 'repaired': 0, 'initial_removed': 0, 'initial_repairs': 0, 'available': True} │
│ constraint_feasible │ True │
│ constraint_report │ constraint_report.json │
│ run_manifest │ run_manifest.json │
│ 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} │
│ data_quality_report │ data_quality.json │
│ ending_inventory │ {'offset': 99, 'accounts': {'feature.Seral.regen': 143.49999999999997, 'feature.Volume.managed': 29307.574999999997, 'feature.Volume.natural': 99698.14285714286}} │
│ ending_inventory_report │ ending_inventory.csv │
│ status │ ok │
│ time_limit_reached │ False │
│ dataset │ {'schema_version': '0.1', 'sources': [{'path': 'recipe.xml', 'sha256': 'ff05c1de6ac54f9509d423fae0597abc17b03ee9965e75819f2d6778e30f5288'}, {'path': 'fragments.csv', 'sha256': │
│ │ '5f371cb7421d65f5839f334f94911d315d8200606c29a53d87352b875b4589d9'}], 'manifest_sha256': 'd26ad2c906f0d4fe6768999b4418534c72eeadf1d4b3bdc93d7cf3b5ca1aa35a'} │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
[7]:
print(pd.read_csv(work / "search" / "report_targets.csv").to_string(index=False))
print()
print(pd.read_csv(work / "search" / "route_cost_report.csv").head(3).to_string(index=False))
account period year value minimum maximum raw_penalty penalty scale normalization priority kind status
product.Harvested.CC 1 10 20443.057143 20000.0 NaN 0.0 0.0 1.0 none 1 level met
route.Total.haul 1 10 136.092857 NaN 3000.0 0.0 0.0 1.0 none 1 level met
PERIOD YEAR PERIODWIDTH LENGTH BUILTLENGTH BUILD_EXPENSE HAUL_EXPENSE MAINTAIN_EXPENSE TOTAL VOLUME AVERAGEHAULDIST AVERAGEBUILDCOST AVERAGEHAULCOST AVERAGEMAINTCOST
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
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
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
Where to look next
docs/howto/route-products.rstwalks through the tables and the route configuration.docs/reference/roads.rstspecifies the network, the routing and the route outputs.