Routing¶

A routing policy decides a vehicle's next link at a branching node. RoutingPolicy is the protocol; StaticRoutePolicy (the default) follows each vehicle's own route; ShortestPathPolicy plans routes on the live network graph, optionally with a congestion-aware cost. See Routing.

RoutingPolicy ¶

Bases: Protocol

Interface for deciding the next link of a vehicle leaving a node.

next_link ¶

next_link(vehicle: Vehicle, current_link_id: int, node: BaseNode, state: NetworkState | None) -> int | None

Return the link_id the vehicle should enter next.

Parameters:

Name	Type	Description	Default
`vehicle`	`Vehicle`	The vehicle being routed.	required
`current_link_id`	`int`	The inbound link the vehicle is currently on.	required
`node`	`BaseNode`	The node resolving the movement (gives access to candidate outbound links).	required
`state`	`NetworkState \| None`	A read-only network state view, or `None`.	required

Returns:

Type	Description
`int \| None`	The next `link_id`, or `None` if no next link applies.

StaticRoutePolicy ¶

Default policy: follow each vehicle's own route (abmmeso-faithful).

Resolution is delegated to :meth:Vehicle.next_link, which uses the vehicle's position pointer (robust to routes that revisit a link) and falls back to the first occurrence of the current link — matching the reference implementation.

next_link ¶

next_link(vehicle: Vehicle, current_link_id: int, node: BaseNode, state: NetworkState | None) -> int | None

Return the vehicle's own-route next link (see :class:RoutingPolicy).

ShortestPathPolicy ¶

ShortestPathPolicy(cost: Callable[[int, NetworkState], float] | None = None, dynamic: bool = False)

Routes each vehicle along the current shortest path to its destination.

At every branching node the policy computes the least-cost path from the node the vehicle is entering to vehicle.destination over the real links, and returns the first link on that path. Because it is consulted live at each node, rerouting happens automatically as costs change; supply a cost function reading the :class:NetworkState to make routing congestion-aware.

Parallel links between two nodes are collapsed to their cheapest option, so a slow lane or an inflated-length detour is used only when it is actually the faster choice.

Attributes:

Name	Type	Description
`dynamic`		If `True` the routing graph is rebuilt on every decision so live costs take effect; if `False` the free-flow graph is built once.

Create a shortest-path policy.

Parameters:

Name	Type	Description	Default
`cost`	`Callable[[int, NetworkState], float] \| None`	Optional `cost(link_id, state) -> float` giving each link's routing cost, where `state` is the live :class:`~mesoltm.network.state.NetworkState` (exported as `mesoltm.NetworkState`) — so a congestion-aware cost can read `state.occupancy(link_id)`, `state.density(link_id)` etc. with full typing. Defaults to the link's continuous free-flow travel time (`state.continuous_free_flow_time(link_id)`, i.e. `length / v_f`).	`None`
`dynamic`	`bool`	Whether to recompute the graph on each decision (needed when `cost` depends on live state).	`False`

refresh ¶

refresh(state: NetworkState) -> None

Rebuild the cached routing graph from the live state, once.

Lets a caller that needs many route lookups against the same live state (e.g. a rerouting plugin re-planning every vehicle in one step) build the dynamic graph a single time, then temporarily set dynamic = False so the lookups reuse it instead of rebuilding it per call.

route ¶

route(state: NetworkState, from_node: NodeId, to_node: NodeId) -> list[int]

Return the full shortest real-link route from from_node to to_node.

Convenience planner (used e.g. to seed a vehicle's route before injection or inside a rerouting plugin). Returns the ordered real link ids, or an empty list if the nodes coincide or no path exists. Respects the same cost function and dynamic setting as :meth:next_link.

next_link ¶

next_link(vehicle: Vehicle, current_link_id: int, node: BaseNode, state: NetworkState | None) -> int | None

Return the first link on the shortest path toward the destination.

See :class:~mesoltm.routing.policy.RoutingPolicy for the argument contract (the engine always passes a :class:NetworkState; None yields no decision). When the vehicle has arrived at its destination node, the destination's sink connector (if any) is returned so it leaves the network.