Roads, routes, and mills
The road model routes each produced product from its block to a destination (usually a mill)
over a segment graph, chooses the destination, and accounts for the haul, build, and maintenance
costs. A destination is identified by its account name (for example destination.MILL1),
not by its vertex: the sample route model attaches more than one mill to the same vertex.
Network tables
A network is four CSV tables loaded by ws4.roads.network.load_route_tables:
Table |
Columns |
|---|---|
|
|
|
|
|
|
|
|
Both the WS4 names and the established route-table names are accepted.
RouteNetwork.route returns the least-haul-cost route (its segments, length, and the haul,
build, and maintenance costs); route_length and route_cost return the shortest path by
length or by cost, and nearest_destination returns the least-haul-cost eligible destination.
The route model
ws4.roads.accounts.RouteModel holds the network, the eligibility (which destinations a
product may reach), and an optional unutilized account for surplus. The destination choice is
exclusive: one destination per product per block, the least-haul-cost reachable eligible one.
A product with no reachable eligible destination is surplus (unutilized). Eligibility loads from a
product,destination table with load_route_eligibility.
The route cost ledger
ws4.roads.accounts.RouteCostLedger accumulates the route accounts over a run, following the
established route-account model:
the haul cost is the volume times the sum of the segment haul rates on the route;
the build cost is charged once, in the first period a segment is used;
the maintenance cost is charged in each period a segment is used.
It writes, into the run directory:
route_values.csv— one row per routed product (year, block_id, destination, product, volume, length_m, haul_cost);network_table.csv— one row per segment per period, with the total and per-destination volume and haul expense;route_table.<destination>.csv— the per-segment route table for one destination;route_cost_report.csv— one row per period, with the established columns (PERIOD, YEAR, PERIODWIDTH, LENGTH, BUILTLENGTH, BUILD_EXPENSE, HAUL_EXPENSE, MAINTAIN_EXPENSE, TOTAL, VOLUME, AVERAGEHAULDIST, AVERAGEBUILDCOST, AVERAGEHAULCOST, AVERAGEMAINTCOST);used_roads.csv— one row per used segment per year, with the segment’s vertex coordinates (period,segment_id,from_vertex,to_vertex,x1,y1,x2,y2,volume,built_length,first_use). It is written when the route configuration’sverticestable carriesXandY; the service serves it as the Used roads (run) overlay. This is the run’s road use, distinct from the source access network.
Route accounts and duplicate accounts
A route account (RouteAccount, matching addRouteHaulAccount and friends) sums a route
value — haul, build, maintenance, or volume — for a destination into a named account. A
duplicate account (DuplicateAccount, matching duplicateAccount) copies an account’s
value into another, scaled by a factor. resolve_account_values combines the simulated account
values with the route account values and applies the duplicates, so the resulting accounts (for
example route.Total.haul) can be targeted by the optimizer.
A route configuration file (YAML) names the route tables, an optional eligibility table,
an optional unutilized account, the route accounts, and the duplicate accounts. The vertices
table is optional as a configuration key: when it is omitted, vertices.csv beside the
configuration is used if it exists, and it supplies the used-road geometry when it has X and
Y:
route:
segments: segments.csv
destinations: destinations.csv
linkages: linkages.csv
eligibility: eligibility.csv
unutilized: product.Unutilized
route_accounts:
- {destination: destination.MILL1, kind: haul, account: route.Mill1.haul}
- {destination: destination.MILL1, kind: volume, account: product.Mill1.Yield}
duplicate_accounts:
- {master: route.Mill1.haul, target: route.Total.haul}
Load it with load_route_config and pass the model, route accounts, and duplicate accounts to
the simulator or the optimizer (OptimizeConfig.route_config_path or --route-config on the
command line):
from ws4.roads.accounts import load_route_config
from ws4.sim.engine import Simulator
config = load_route_config("route.yaml")
Simulator.from_dataset(dataset).run(
schedule, years, out_dir,
route_model=config.model,
route_accounts=config.route_accounts,
duplicate_accounts=config.duplicate_accounts,
)
The routing is verified against the reference implementation’s own outputs: its sample ships cost_destination.<mill>.csv (the summed haul rate per network node), and python scripts/acceptance.py –roads-sample <sample>/roads compares WS4’s least-haul-cost routes to it node by node — 37 701 comparisons on the C5-class sample, with no differences. notes/design/ws4-parity-harness.md records what the comparison covers and what it does not.
The route model runs in the optimizer’s inner loop. Haul, maintenance, and volume route accounts are additive over blocks, so a move is priced by a route delta and needs no re-routing; a build route account, a duplicate account, and edge contrast are not additive, so any of them makes an evaluation a whole-schedule pass. See notes/design/ws4-performance.md for the measurements.
API
- ws4.roads.network.load_route_tables(root: Path) tuple[DataFrame, DataFrame, DataFrame, DataFrame][source]
Load
vertices.csv,segments.csv,destinations.csv,linkages.csv.- Parameters:
root (Path) – Directory holding the four CSV files.
- Returns:
tuple of pandas.DataFrame –
(vertices, segments, destinations, linkages).
- ws4.roads.network.load_route_eligibility(path: Path) dict[str, tuple[str, ...]][source]
Load a product-to-destination eligibility table.
The table has a
productcolumn and adestinationcolumn; a product may name more than one destination. The result maps each product label to the destinations that may receive it.- Parameters:
path (Path) – The eligibility CSV, with
product,destinationcolumns.- Returns:
dict of str to tuple of str – The eligible destinations per product label.
- class ws4.roads.network.RouteNetwork(segments: tuple[~ws4.roads.network.Segment, ...], destinations: tuple[~ws4.roads.network.Destination, ...], block_vertex: ~collections.abc.Mapping[int, int], vertex_coordinates: ~collections.abc.Mapping[int, tuple[float, float]] = <factory>, _distance_cache: dict[tuple[int, str, int], dict[int, float]] = <factory>, _previous_cache: dict[tuple[int, str, int], dict[int, tuple[int, int]]] = <factory>, _segments_cache: dict[int, ~ws4.roads.network.Segment] | None = None, _adjacency_cache: dict[int, list[int]] | None = None, opened: set[int] | None = None, _open_version: int = 0)[source]
A road network with least-cost routing between blocks and destinations.
- segments
The road segments.
- Type:
tuple of Segment
- destinations
The destinations, identified by account name.
- Type:
tuple of Destination
- block_vertex
The single vertex each block is assigned to.
- Type:
mapping of int to int
- vertex_coordinates
The
(x, y)coordinate of each vertex, when theverticestable carriesXandY. Used to write a run’s used-road geometry.- Type:
mapping of int to tuple of float
- opened
The segments open in the current period.
Nonemeans every segment is open, which is the whole-planned-network behaviour; a set means only those segments are routable, andopen_segments()grows it.- Type:
set of int or None
- classmethod from_tables(segments: DataFrame, destinations: DataFrame, linkages: DataFrame, *, initial_open: set[int] | None = None, vertices: DataFrame | None = None) RouteNetwork[source]
Build a network from the segments, destinations, and linkages tables.
- Parameters:
segments (pandas.DataFrame) – The segment table. Legacy
FNODE/TNODE/LENGTH/HAUL/BUILD/MAINTAINand WS4 names are both accepted.destinations (pandas.DataFrame) – The destination table. The destination name comes from
ACCOUNT/destination/name/dest_id; the vertex fromNODE/vertex_id.linkages (pandas.DataFrame) – The block-to-vertex table (
BLOCK/block_id,NODE/vertex_id).initial_open (set of int or None, optional) – The segments open before the run.
None(the default) opens every segment, which is the whole-network behaviour WS4 had before roads were dated. An empty set starts with no road.existing_segments()returns the usual set: the segments whose build cost is 0, which the reference makes available at period 1 at null cost.vertices (pandas.DataFrame or None, optional) – The vertex table, with
NODE/vertex_idandX/Y. When given, the coordinates are kept for the run’s used-road geometry.
- Returns:
RouteNetwork – The assembled network.
- destination_names() tuple[str, ...][source]
Return the destination account names, in table order.
- Returns:
tuple of str – The destination names.
- open_segments(segment_ids: Sequence[int]) tuple[int, ...][source]
Open planned segments, and forget the routes computed before they were open.
A segment is opened once; opening an already-open segment is a no-op. The open set is a per-run piece of state, so a network with
opened = None(every segment open) is left unchanged.- Parameters:
segment_ids (sequence of int) – The segments to open.
- Returns:
tuple of int – The segments that were not already open, in input order.
- route(block_id: int, destination: str, *, open_only: bool = True) Route | None[source]
Return the least-haul-cost route from a block to a destination.
- Parameters:
block_id (int) – The block.
destination (str) – The destination account name.
open_only (bool, optional) – When true (the default) route over opened segments only; when false, over the whole planned network, which is how a block is reached before its road is built.
- Returns:
Route or None – The route, or None when the block or destination is not linked, or no path exists.
- route_length(block_id: int, destination: str, *, open_only: bool = True) float | None[source]
Return the shortest route length (metres) from a block to a destination.
- Parameters:
block_id (int) – The block.
destination (str) – The destination account name.
open_only (bool, optional) – When true (the default) route over opened segments only; when false, over the whole planned network.
- Returns:
float or None – The route length, or None when the block or destination is not linked.
- route_cost(block_id: int, destination: str, *, open_only: bool = True) float | None[source]
Return the shortest haul cost from a block to a destination.
- Parameters:
block_id (int) – The block.
destination (str) – The destination account name.
open_only (bool, optional) – When true (the default) route over opened segments only; when false, over the whole planned network.
- Returns:
float or None – The haul cost, or None when the block or destination is not linked.
- nearest_destination(block_id: int, eligible: Iterable[str] | None = None, *, open_only: bool = True) tuple[str, float] | None[source]
Return the least-haul-cost destination for a block, or None.
- Parameters:
block_id (int) – The block.
eligible (iterable of str, optional) – The destination names the block’s product may be sent to. When omitted, every destination is eligible.
open_only (bool, optional) – When true (the default) consider opened segments only; when false, the whole planned network.
- Returns:
tuple of (str, float) or None – The destination account name and route length, or None when no eligible destination is reachable.
- class ws4.roads.network.Route(destination: str, segment_ids: tuple[int, ...], length_m: float, haul_cost: float, build_cost: float, maintain_cost: float)[source]
A route from a block to a destination.
- destination
The destination account name.
- Type:
str
- segment_ids
The segment ids along the route, from the block to the destination.
- Type:
tuple of int
- length_m
The total route length, in metres.
- Type:
float
- haul_cost
The total haul cost per unit of volume over the route.
- Type:
float
- build_cost
The total build cost of the segments along the route.
- Type:
float
- maintain_cost
The total maintenance cost of the segments along the route.
- Type:
float
- class ws4.roads.accounts.RouteModel(network: ~ws4.roads.network.RouteNetwork, eligibility: ~collections.abc.Mapping[str, ~collections.abc.Sequence[str]] = <factory>, unutilized: str | ~collections.abc.Mapping[str, str] = '', delivery: ~collections.abc.Sequence[~ws4.roads.accounts.DeliveryTarget] = (), _overrides: dict[tuple[int, str], str] = <factory>, _assign_cache: dict[tuple[int, str], tuple[str, ~ws4.roads.network.Route | None]] = <factory>)[source]
The route model: which destinations a product may reach, and the costs.
- network
The road network.
- Type:
- eligibility
The destination names each product may be sent to. A product absent from the map may go to any destination. When present and empty, the product is unutilized.
- Type:
mapping of str to sequence of str, optional
- unutilized
The account name that records surplus product, either for every product or per product label. The reference declares its surplus per master product — the conifer split has no such account at all, the deciduous split has its own — so a single shared account would file one product’s surplus under another’s. An empty string, or a product with no entry, disables surplus for that product.
- Type:
str or mapping of str to str, optional
- delivery
The volumes destinations must receive each year. A run fills them before it routes, from the blocks nearest each destination, and leaves every other block to the cost rule, which is how the reference’s mill products are split.
- Type:
sequence of DeliveryTarget, optional
- surplus_account(product: str) str[source]
Return the account that records a product’s surplus.
- Parameters:
product (str) – The product label.
- Returns:
str – The surplus account for the product, or an empty string when it has none.
- eligible(product: str) tuple[str, ...][source]
Return the destinations a product may be sent to.
A map that names products is also the list of what the model delivers: a product it does not name is routed nowhere, because a configuration that says where wood goes is saying what the wood is. Leaving a product out otherwise puts areas, sera classes and volume classes on the road beside the yield — which is what WS4 did until the route report made its volume 2.3 times the reference’s for exactly that reason. A model with no map at all delivers every product to every destination, which is what it did before there was a map.
- Parameters:
product (str) – The product label.
- Returns:
tuple of str – The destinations the product may be sent to: what the map names for it; nothing when the map names other products but not this one, or when the product is explicitly unutilized; and every destination when there is no map.
- delivers(product: str) bool[source]
Return whether a product is routed at all.
- Parameters:
product (str) – The product label.
- Returns:
bool – True when the product has at least one destination it may be sent to.
- set_overrides(overrides: Mapping[tuple[int, str], str]) None[source]
Replace the destinations a run has decided, dropping the choices cached before them.
- Parameters:
overrides (mapping of (int, str) to str) – The destination per
(block, product)this year, or an empty mapping for none.
- assign(block_id: int, product: str) tuple[str, Route | None][source]
Choose a destination for a block’s product.
The choice is exclusive: one destination per product per block, the least haul-cost reachable eligible destination. When none is reachable and an unutilized account is configured, the product is surplus. The choice is fixed for a given block and product, so it is computed once and cached.
- Parameters:
block_id (int) – The block.
product (str) – The product label.
- Returns:
tuple of (str, Route or None) – The chosen destination name, and its route (None for surplus).
- class ws4.roads.accounts.RouteAccount(destination: str, kind: str, account: str, factor: float = 1.0, product: str | None = None)[source]
A route account definition (
addRouteHaulAccountand friends).- destination
The destination the account tracks.
- Type:
str
- kind
The route value to sum: a cost, or the product volume.
- Type:
{“haul”, “build”, “maintain”, “volume”}
- account
The name to add the value into.
- Type:
str
- factor
A scaling factor, applied to the value (default 1; use -1 to subtract).
- Type:
float
- product
The product a
volumeaccount tracks, or None for every product routed there. A cost account cannot name a product: the ledger prices a route, not a tonne of it.- Type:
str or None
- class ws4.roads.accounts.DuplicateAccount(master: str, target: str, factor: float = 1.0)[source]
A duplicate account (
duplicateAccount(master, target, factor)).- master
The account whose value is copied.
- Type:
str
- target
The account the value is added into.
- Type:
str
- factor
A scaling factor (default 1; use -1 to subtract).
- Type:
float
- class ws4.roads.accounts.RouteConfig(model: RouteModel, route_accounts: tuple[~ws4.roads.accounts.RouteAccount, ...]=(), duplicate_accounts: tuple[~ws4.roads.accounts.DuplicateAccount, ...]=(), product_allocations: tuple[~ws4.roads.accounts.ProductAllocation, ...]=(), period_width: int = 1, delivery: tuple[~ws4.roads.accounts.DeliveryTarget, ...]=(), maintenance: MaintenanceCharge = <factory>)[source]
A loaded route configuration.
- model
The route model (network, eligibility, surplus).
- Type:
- route_accounts
The route accounts to resolve.
- Type:
tuple of RouteAccount
- duplicate_accounts
The duplicate accounts to resolve.
- Type:
tuple of DuplicateAccount
- product_allocations
The master products to partition across their destinations.
- Type:
tuple of ProductAllocation
- period_width
The planning-period width, in years.
- Type:
int
- delivery
The volumes destinations must receive each year, which is how the reference’s mill products are split.
- Type:
tuple of DeliveryTarget
- maintenance
How a used road’s maintenance is charged. The default is the reference’s own reading; a divergence from it has to be asked for by name under
divergences.- Type:
MaintenanceCharge
- ws4.roads.accounts.load_route_config(path: Path) RouteConfig[source]
Load a route configuration from YAML.
The file names the four route tables (
segments,destinations,linkages), an optionaleligibilitytable, an optionalunutilizedaccount — one name, or a name per product — and lists ofroute_accountsandduplicate_accounts. Averticestable (named in the config, orvertices.csvbeside the config or the segments table) supplies the coordinates for the used-road geometry.initial_roadsisall(the default, the whole planned network) orexisting(the zero-build-cost roads open at period 1, the rest opened on demand). Relative paths resolve against the configuration file’s directory.Parity is the default and a divergence has to be named. Everything WS4 computes the way the reference does needs no configuration; what WS4 computes differently is asked for under
divergences, one named entry per quantity, so that what a run does is explicit rather than implicit. The one entry there ismaintenance—model: reference(the default, and what parity uses) ormodel: trafficwithper_volumefor the affine charge — and an entry WS4 does not know is refused rather than ignored.- Parameters:
path (Path) – The YAML configuration file.
- Returns:
RouteConfig – The loaded configuration.
- ws4.roads.accounts.resolve_account_values(values: DataFrame, extra: DataFrame | None = None, duplicates: Sequence[DuplicateAccount] = ()) DataFrame[source]
Combine account values, apply duplicate accounts, and sum by year and account.
- Parameters:
values (pandas.DataFrame) – The simulated account values (
year,account,value).extra (pandas.DataFrame or None, optional) – Additional account values (for example route cost accounts).
duplicates (sequence of DuplicateAccount, optional) – Duplicate accounts. Each copies the value of its master account (summed over the year) into its target, scaled by its factor. Duplicates are applied once, in order, against the combined values (they do not chain).
- Returns:
pandas.DataFrame – The resolved values, with
year,account, andvaluecolumns, summed by year and account.
- class ws4.roads.accounts.RouteCostLedger(network: RouteNetwork, period_width: int = 1, collect: bool = True, maintenance: MaintenanceCharge | None = None)[source]
Accumulate route costs over a run and render the route accounts.
The ledger records each routed product, then writes:
the network table (one row per segment per period, with the total and per-destination volume and haul expense);
a route table per destination;
the route cost report (one row per period).
- Parameters:
network (RouteNetwork) – The road network.
period_width (int, optional) – The planning-period width, in years, recorded in the report.
collect (bool, optional) – When True (the default), also keep the per-segment detail that the network table, the route tables, and the route cost report need. When False, only the per-destination totals that
account_values()needs are kept, so a search can evaluate route accounts without the reporting overhead.maintenance (MaintenanceCharge or None, optional) – How a used road’s maintenance is charged. The default is the reference’s own reading; a divergence from it has to be asked for by name.
- record(year: int, block_id: int, product: str, volume: float, destination: str, route: Route | None) None[source]
Record a routed product.
- Parameters:
year (int) – The year of the routing.
block_id (int) – The producing block.
product (str) – The product label.
volume (float) – The produced volume.
destination (str) – The destination account name.
route (Route or None) – The route, or None for a surplus (unutilized) product.
- route_rows() DataFrame[source]
Return the per-product routing rows.
- Returns:
pandas.DataFrame –
year,block_id,destination,product,volume,length_m,haul_cost.
- product_volumes() DataFrame[source]
Return the routed volume per year, destination and product.
- Returns:
pandas.DataFrame –
year,destination,productandvolumecolumns.
- used_roads() DataFrame[source]
Return the used road segments with their vertex geometry.
One row per used segment per year. The geometry comes from the network’s
verticestable; when the table has no coordinates, the frame is empty rather than inventing a line.- Returns:
pandas.DataFrame –
period,segment_id,from_vertex,to_vertex,x1,y1,x2,y2,volume,built_lengthandfirst_use.
- network_table() DataFrame[source]
Return the network table: one row per segment per period.
- Returns:
pandas.DataFrame –
period,segment_id,length,built_length,build_expense,maintain_expense,initial_use,volume, and, for each destination,<destination>.volumeand<destination>.haul_expense.
- route_table(destination: str) DataFrame[source]
Return the route table for one destination: one row per segment per period.
- Parameters:
destination (str) – The destination account name.
- Returns:
pandas.DataFrame –
period,segment_id,from_vertex,to_vertex,volume,haul_expense,length,haul_cost,distance.
- account_values(route_accounts: Sequence[RouteAccount]) DataFrame[source]
Return the route account values, one row per period and account.
Each
RouteAccountsums a route value (haul, build, maintenance, or volume) for its destination into its named account, scaled by its factor.- Parameters:
route_accounts (sequence of RouteAccount) – The route accounts to resolve.
- Returns:
pandas.DataFrame –
year,account, andvaluecolumns.
- route_cost_report(destination: str | None = None) DataFrame[source]
Return the route cost report: one row per period of the model.
The report is folded into the model’s own periods, so its rows are the reference’s: a period is labelled by the year it ends at and carries the model’s period width. The expenses and the volume are summed over the period’s years.
LENGTHis the length of the distinct road used at any time in the period, counted once — a road used in five of the period’s ten years is one road, not five — which is the reference’s reading of the column.BUILTLENGTHis the length first built in the period, also counted once. The averages are recomputed from those figures rather than averaged, which is what makes them mean the same thing in a ten-year period as in a one-year one.AVERAGEHAULDISTis in kilometres, the reference’s unit, while the model routes in metres.With the default period width of one this is one row per year, unchanged.
- Parameters:
destination (str or None, optional) – A destination account to report on alone, which is how the reference ships this report — one table per mill. None reports the whole network, where a shared segment is counted once rather than once per destination it carries wood for.
- Returns:
pandas.DataFrame – The report, in the established column order. Column labels use the established command-line tokens when written by
write().
- write(out_dir: Path) None[source]
Write the route accounts into a run directory.
- Parameters:
out_dir (Path) – The run directory. The method writes
route_values.csv,network_table.csv, the route cost report, a route table and a route cost report per destination, andused_roads.csvwhen the vertices table has coordinates.