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

vertices.csv

vertex_id (NODE) — a road junction.

segments.csv

segment_id (SEGMENT), from_vertex (FNODE), to_vertex (TNODE), length_m (LENGTH), haul_cost (HAUL), build_cost (BUILD), maintain_cost (MAINTAIN) — an undirected edge.

destinations.csv

name (ACCOUNT), vertex_id (NODE) — a destination account attached to a vertex. Several destinations may share a vertex.

linkages.csv

block_id (BLOCK), vertex_id (NODE) — each block is assigned to exactly one vertex.

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’s vertices table carries X and Y; 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 product column and a destination column; 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,destination columns.

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 the vertices table carries X and Y. 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. None means every segment is open, which is the whole-planned-network behaviour; a set means only those segments are routable, and open_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/ MAINTAIN and WS4 names are both accepted.

  • destinations (pandas.DataFrame) – The destination table. The destination name comes from ACCOUNT / destination / name / dest_id; the vertex from NODE / 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_id and X/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:

RouteNetwork

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 (addRouteHaulAccount and 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 volume account 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:

RouteModel

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 optional eligibility table, an optional unutilized account — one name, or a name per product — and lists of route_accounts and duplicate_accounts. A vertices table (named in the config, or vertices.csv beside the config or the segments table) supplies the coordinates for the used-road geometry. initial_roads is all (the default, the whole planned network) or existing (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 is maintenance — model: reference (the default, and what parity uses) or model: traffic with per_volume for 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, and value columns, 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, product and volume columns.

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 vertices table; 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_length and first_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>.volume and <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 RouteAccount sums 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, and value columns.

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. LENGTH is 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. BUILTLENGTH is 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. AVERAGEHAULDIST is 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, and used_roads.csv when the vertices table has coordinates.