Vehicles & routing¶

In mesoltm every unit of node flow is one Vehicle. This is the mesoscopic model's defining feature: the LTM's efficient link/node arithmetic, but with individually tracked agents that carry their own routes and records.

The Vehicle object¶

from mesoltm import Vehicle

v = Vehicle(
    vehicle_id=1,
    origin="n0",
    destination="n3",
    scheduled_departure=5.0, # scheduled departure time in seconds
    route=[1, 2, 4],         # ordered link ids to traverse (optional)
    props={"vclass": "car"}, # free-form metadata (optional)
)

Key attributes:

Attribute	Meaning
`route`	Ordered list of `link_id`s the vehicle intends to traverse. Mutable at any time — rewriting it reroutes the vehicle at its next node.
`position`	Index of the current link within `route` (robust to routes that revisit a link).
`props`	Free-form `dict` of per-vehicle metadata. The core never reads it; plugins, `color_by`, and custom metrics do. Must be JSON-serialisable to survive the animation history round-trip.
`trajectory`	Auto-populated per-link log (`entry_step`, `exit_step`, `is_connector`) for the current trip; per-journey metrics are derived from it.
`scheduled_departure`	Requested departure time in seconds. The vehicle is released at the first step at/after it (step `ceil(scheduled_departure / dt)`).
`departure_time`	Actual departure time in seconds (`None` until then), stamped when the vehicle enters the origin queue.
`arrival_time`	Arrival time in seconds of the current trip (`None` while travelling), stamped by the destination node.
`journeys`	The completed-trip records (the single source of truth for this vehicle's finished trips). One entry per trip — a demand-profile vehicle has one; a re-injected one has several.
`active`	`True` while the vehicle is queued or moving; `False` once it has been absorbed at a destination.

Vehicles do not carry FD parameters

v_f, w, rho_jam describe the road (Link), not the vehicle. A Vehicle has no fundamental-diagram attributes.

Routes are propagated, not imposed¶

The network never computes routes on its own — it simply moves each vehicle along whatever route the vehicle currently holds. That single design choice is why rerouting needs no special machinery: rewrite vehicle.route and the vehicle is rerouted from its next node onward. A plugin or a routing policy does exactly this.

Routing policies¶

At a branching node, which outbound link a vehicle takes is resolved by a RoutingPolicy:

StaticRoutePolicy (the default) reads the vehicle's own route. With this policy the model reproduces the paper's behaviour exactly.
ShortestPathPolicy plans routes on the live network graph (via NetworkX), optionally with a congestion-aware cost callback and dynamic=True to re-plan as conditions change.
Your own — any object implementing the RoutingPolicy protocol's next_link(...).

Routing is entirely a layer around the flow arithmetic: it only chooses a vehicle's next link and never alters demand, supply, or the merge/diverge resolution. See Deviations §A1 and the Routing guide for details and examples.