TripSimulator¶
Internal GTFS-based simulation engine for a single trip.
Internal API
This class is not intended for direct use by end users.
It is an internal building block used by the FleetSimulator class.
This class simulates the temporal and spatial operation of vehicles assigned to a single GTFS trip. Using stop times, shapes, and frequency definitions, it reconstructs:
- The event-level sequence of a single vehicle along the trip (stops, terminals, and travelling segments)
- The fleet operation schedule, accounting for headways, looping behavior, and potential transient regimes
- The time-resolved spatial trajectory of each vehicle
- An interactive map visualization of fleet movements
The simulator relies on a pre-loaded GTFSManager instance.
Notes
- Only GTFS trips with valid
frequencies.txtentries are supported. - All times are assumed to refer to a single service day (00:00–23:59).
- Shapes are assumed to be spatially consistent with stop locations.
Attributes:
| Name | Type | Description |
|---|---|---|
gtfs_manager |
GTFSManager
|
GTFS data manager providing access to GTFS tables. |
trip_id |
str
|
Identifier of the GTFS trip being simulated. |
single_trip_sequence |
DataFrame or list
|
Event-level description of a single vehicle run (result - computed after simulation). |
fleet_operation |
DataFrame or list
|
Fleet-wide operational schedule (result - computed after simulation). |
Examples:
>>> simulator = TripSimulator(manager, "trip_42")
>>> simulator.compute_single_trip_sequence()
>>> simulator.compute_fleet_operation()
>>> traj = simulator.get_fleet_trajectory(time_step=120)
Attributes¶
fleet_operation
property
¶
Fleet-wide operation schedule for the simulated trip.
Each entry corresponds to a vehicle and includes: - Time intervals of operation and non-operation - Number of trip repetitions (possibly fractional) - Aggregated travel, stop, and terminal times - Total distance and operation duration
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame or list[dict]: Fleet operation description. |
gtfs_manager
property
writable
¶
GTFS data manager associated with the simulator.
Returns:
| Name | Type | Description |
|---|---|---|
GTFSManager |
GTFSManager
|
The GTFS manager instance. |
single_trip_sequence
property
¶
Event-level sequence of a single vehicle performing the trip.
The sequence is ordered in time and contains alternating events such as:
- at_terminal
- at_stop
- travelling
Each event includes duration, distance, cumulative metrics, and geometry.
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame or list[dict]: Structured representation of the trip events. |
trip_id
property
writable
¶
Identifier of the simulated GTFS trip.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
Trip identifier. |
Functions¶
__init__(gtfs_manager, trip_id)
¶
Initialize a TripSimulator for a given GTFS trip.
This constructor binds the simulator to a GTFS dataset and validates that the requested trip exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gtfs_manager
|
GTFSManager
|
Instance managing the GTFS dataset. |
required |
trip_id
|
str
|
Identifier of the trip to simulate. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the trip ID is not found in the GTFS dataset. |
compute_fleet_operation(transient_regime=False)
¶
Compute the fleet operation required to serve the trip frequencies.
This method expands the single-trip sequence into a fleet-level operational plan based on GTFS frequency definitions. It supports:
- Looping operation (vehicles already in circulation)
- Transient regimes (vehicles progressively entering service)
- Partial trip repetitions at service boundaries
- Aggregation of distance and time metrics per vehicle
The result is stored internally in self.fleet_operation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
transient_regime
|
bool
|
If True, vehicles start operation progressively after the service start time. If False, routes are assumed to be already populated with vehicles at the beginning of service. Defaults to False. |
False
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If no frequency data is available or if trip duration is zero. |
Returns:
| Type | Description |
|---|---|
None
|
None |
compute_single_trip_sequence()
¶
Compute the detailed event sequence for a single vehicle trip.
This method reconstructs the full temporal and spatial evolution of one vehicle running the trip by:
- Ordering stops using GTFS stop times
- Projecting stops onto the trip shape
- Computing inter-stop travel distances and durations
- Generating a sequence of discrete events (stops, terminals, travel)
The result is stored internally in self.single_trip_sequence.
Returns:
| Type | Description |
|---|---|
None
|
None |
get_fleet_trajectory(time_step)
¶
Compute time-resolved spatial trajectories for the entire fleet.
Using the precomputed fleet operation and single-trip sequence, this method reconstructs vehicle locations at a fixed temporal resolution throughout the day.
Each vehicle is represented by a row, and each column corresponds
to a time step. Cells contain Shapely Point geometries or None
when the vehicle is not operating.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
time_step
|
int
|
Temporal resolution in seconds. |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: Fleet trajectory matrix indexed by vehicle ID |
DataFrame
|
and time (HH:MM:SS). |
get_fleet_trajectory_map(fleet_trajectory)
¶
Generate an interactive time-slider map of fleet trajectories.
This method visualizes the simulated fleet operation using a Folium map with a temporal slider. Vehicle positions are animated over time, and the trip shape is displayed as a reference.
Notes
- This visualization currently only supports a 2-minute time step.
- Vehicles at identical locations are slightly jittered for clarity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fleet_trajectory
|
DataFrame
|
Output of |
required |
Returns:
| Type | Description |
|---|---|
Map
|
folium.Map: Interactive map with animated vehicle movements. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no valid trajectory data is available or if the time step is incompatible. |
max_vehicles_in_operation()
¶
Estimate the maximum number of vehicles required to operate the trip.
The estimate is based on: - Trip duration - Minimum headway across all frequency definitions
Returns:
| Name | Type | Description |
|---|---|---|
int |
int
|
Estimated maximum number of vehicles. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no frequency data is available for the trip. |
trip_duration_sec()
¶
Compute the total duration of the trip.
The duration is defined as the time difference between the first arrival and the last departure in the GTFS stop times.
Returns:
| Name | Type | Description |
|---|---|---|
int |
int
|
Trip duration in seconds. |