Route products to mills
The road model routes each produced product from its block to a destination — usually a mill — over a network of segments, chooses the destination, and accounts for the haul, build, and maintenance costs. Those become accounts you can target like any other, so “keep haul cost under X” or “at least Y volume to Mill 1” are ordinary targets.
Prerequisites
A compiled dataset whose
blockstable has the same block ids as the network’s linkages.Four network tables, or the established equivalents (see Roads, routes, and mills):
vertices.csv,segments.csv,destinations.csv,linkages.csv. The sample estate ships all of them, with two mills, so the guide’s commands run as they are.Optionally an eligibility table (
product,destination) saying which mill may receive which product.
Procedure
1. Write the route configuration.
# examples/estate/route.yaml — the shipped configuration, with two mills
route:
segments: segments.csv
destinations: destinations.csv
linkages: linkages.csv
eligibility: eligibility.csv # optional
unutilized: product.Unutilized # optional: where unreachable volume is recorded
route_accounts:
- {destination: destination.MILL1, kind: haul, account: route.Mill1.haul}
- {destination: destination.MILL2, kind: haul, account: route.Mill2.haul}
- {destination: destination.MILL1, kind: volume, account: product.Mill1.Yield}
- {destination: destination.MILL2, kind: volume, account: product.Mill2.Yield}
duplicate_accounts:
- {master: route.Mill1.haul, target: route.Total.haul}
- {master: route.Mill2.haul, target: route.Total.haul}
A route account sums one route value (haul, build, maintain, or volume) for one
destination into a named account. A duplicate account copies an account into another, scaled by a
factor, which is how a per-mill cost becomes a total.
2. Simulate with routing. That writes the route outputs beside the account values:
ws4 simulate --dataset tmp/estate/compiled --schedule tmp/estate/schedule.csv \
--years 60 --topology examples/estate/topology.csv \
--route-config examples/estate/route.yaml --out tmp/estate/run
Cutting eight blocks at offset 0 on the sample estate splits between the mills by least haul cost, and the route accounts resolve into the account values:
year account value
0 product.Harvested.CC 8793.814286
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
route_values.csv says where each load went: a block at the west end goes to destination.MILL1,
and one further east to destination.MILL2, because that is the cheaper chain of segments even
though its own spur is longer.
The run directory gains route_values.csv (one row per routed product), network_table.csv (one
row per segment per period), route_table.<destination>.csv, and route_cost_report.csv.
3. Target a route account. Because the route accounts are resolved into the account values, they are ordinary targets:
targets:
- account: route.Total.haul
period: 1
maximum: 500000
max_weight: 1.0
period_width: 10
4. Search with routing. Pass the same configuration to the search:
ws4 optimize --dataset tmp/howto/compiled --targets tmp/howto/route-targets.yaml \
--years 100 \
--route-config tmp/howto/route.yaml \
--time-limit 00:05:00 --seed 1 --out tmp/howto/route-run
5. The same in Python.
from ws4.roads.accounts import load_route_config
from ws4.sim.engine import Simulator
config = load_route_config("tmp/howto/route.yaml")
Simulator.from_dataset(dataset).run(
schedule_csv,
years=100,
out_dir=Path("tmp/howto/routed"),
route_model=config.model,
route_accounts=config.route_accounts,
duplicate_accounts=config.duplicate_accounts,
)
Troubleshooting
Everything is surplus — no destination is eligible for the product. Check the eligibility table, and check that the destinations are reachable from the block’s linkage vertex.
Haul cost is zero — the product was not routed at all, usually the same cause as above. Look at
route_values.csv: a missing row is a routing problem, a zero cost is a rate problem.The search became very slow — usually a build route account, a duplicate account, or an edge-contrast element. Haul, maintenance, and volume route accounts are additive, so the search prices a move with a route delta; those three are not, and force a whole-schedule evaluation per step. Keep them out while you tune, then add them (notes/design/ws4-performance.md in the repository records the measurements).
Build cost appears once and never again — that is the model: a segment is charged its build cost in the first period it is used and its maintenance cost in every period it is used.
Two mills share a vertex and the choice looks arbitrary — destinations are identified by account name, not by vertex, and the choice is exclusive: the least-haul-cost reachable eligible destination wins.