Metrics¶

Post-run analysis of per-vehicle travel times, derived from each vehicle's trajectory. collect_trips builds one record per vehicle, summarize_trips reduces them to network aggregates, and write_trips_csv flattens them to disk. See Metrics & trip analysis.

collect_trips ¶

collect_trips(sim: Simulation, include_connectors: bool = False) -> list[dict]

Collect travel-time records for every completed trip in a finished run.

Completed trips are gathered from the destination nodes' recorded journeys — one record per completed journey. A vehicle from a static demand profile contributes one journey; a hand-injected vehicle that was re-injected contributes one per trip. Vehicles still en route or waiting in an origin queue at the end of the horizon have no completed journey and are not included.

Parameters:

Name	Type	Description	Default
`sim`	`Simulation`	A run :class:`~mesoltm.core.simulation.Simulation`.	required
`include_connectors`	`bool`	Passed through to :func:`trip_record`.	`False`

Returns:

Type	Description
`list[dict]`	A list of per-journey records (see :func:`trip_record`), sorted by
`list[dict]`	`(vehicle_id, journey_index)`.

trip_record ¶

trip_record(journey: dict, dt: float, include_connectors: bool = False) -> dict

Build the travel-time record for a single completed journey.

The reported travel_time is the time from the vehicle's actual departure to its arrival, minus the artificial one-step free-flow lag that each auto-inserted O/D connector imposes (a one-cell connector always costs one free-flow step to cross, even when empty and unrestricted). The actual departure (departure_time) is the instant the vehicle entered the origin queue — stamped by :meth:~mesoltm.core.nodes.origin_node.OriginNode.prepare_step at the first step at or after its scheduled_departure — and the arrival (arrival_time) is stamped at absorption; both are read straight off the journey record (already in seconds). Measuring from the actual departure (rather than the sub-step scheduled_departure) keeps travel_time a clean multiple of dt and, for a vehicle injected with a past departure time, avoids charging travel for time before the vehicle could exist.

Time a vehicle spends on a connector beyond its one free-flow step is kept: it is a genuine supply-limited wait to enter or leave the network (downstream space was the binding constraint). travel_time splits into access_time (origin-queue wait plus any supply-limited connector wait) and network_time (time on real links only), so travel_time == access_time + network_time; network_time reflects only real links and is unaffected by connectors.

Parameters:

Name	Type	Description	Default
`journey`	`dict`	A completed journey record as produced by :meth:`~mesoltm.core.vehicle.Vehicle.snapshot_journey` and stored on `vehicle.journeys` / a destination's `completed_journeys`.	required
`dt`	`float`	Simulation step `dt` in seconds, used to convert steps to seconds.	required
`include_connectors`	`bool`	If `True` keep auto-inserted O/D connector links in `link_travel_times` and `route`; by default only real links are reported (connectors are internal access stubs).	`False`

Returns:

Type	Description
`dict`	A dict with keys:
`dict`	`vehicle_id`, `journey_index`, `origin`, `destination`;
`dict`	`route` — the ordered real link ids the vehicle actually drove;
`dict`	`scheduled_departure_time` — the journey's requested departure (`scheduled_departure`), which may fall between steps;
`dict`	`departure_time` — the actual departure: when the vehicle entered the origin queue (normally `ceil(scheduled_departure / dt) * dt`, later if it was injected with a past departure time);
`dict`	`network_entry_time` — when it entered the first real link;
`dict`	`arrival_time` — when it was absorbed at the destination;
`dict`	`travel_time` — time in system from the actual `departure_time` to arrival, with each connector's one-step free-flow lag removed (supply-limited connector waiting is kept);
`dict`	`access_time` — the part of `travel_time` not spent on real links: origin-queue wait plus any supply-limited O/D connector wait, `travel_time − network_time`;
`dict`	`network_time` — time on real links only (connector-free);
`dict`	`n_links` and `link_travel_times` (`{link_id: seconds}`).
`dict`	Time fields are seconds; `None` where a value cannot be determined (e.g.
`dict`	the vehicle never entered the network).

summarize_trips ¶

summarize_trips(trips: list[dict]) -> dict

Aggregate a list of trip records into a compact network-level summary.

Parameters:

Name	Type	Description	Default
`trips`	`list[dict]`	Records as returned by :func:`collect_trips`.	required

Returns:

Type	Description
`dict`	A dict of headline metrics: trip counts, mean/median/min/max total travel
`dict`	time (which includes the initial access wait), mean access time, total
`dict`	vehicle-hours, and the mean travel time per link. Duration fields are
`dict`	`None` when there are no completed trips.

write_trips_csv ¶

write_trips_csv(trips: list[dict], path: str) -> str

Write trip records to a CSV file (one row per completed journey).

The route and per-link travel times are flattened into single columns ("l1;l2;..." and "link_id:seconds;...") so the file stays flat.

Parameters:

Name	Type	Description	Default
`trips`	`list[dict]`	Records as returned by :func:`collect_trips`.	required
`path`	`str`	Destination file path.	required

Returns:

Type	Description
`str`	The path written to.