FleetSimulator

GTFS-based fleet simulation engine for the entire vehicle fleet operating on multiple trips.

The FleetSimulator orchestrates multiple TripSimulator objects, acting as a higher level engine for fleet-wide simulations. Results are aggregated into unified fleet-level outputs, including:

• Operational schedules across multiple vehicles operating on different trips
• Aggregated travel event sequences for all simulated vehicles
• Time-resolved spatial trajectories and map visualizations of fleet movements

Each trip is simulated independently using TripSimulator instances, and the results are merged into pandas DataFrames.

Notes

• All trips are assumed to belong to the same GTFS feed and service day (GTFS data pre-processing is needed for a different behaviour).
• Trip simulations are independent; no vehicle interlining is assumed.
• Multiprocessing can be enabled to speed up large fleet simulations.
• Time-resolved fleet trajectoriy calculation may be computationally expensive.

Attributes:

Name	Type	Description
gtfs_manager	GTFSManager	GTFS data manager providing access to GTFS tables.
trip_ids	list[str]	List of GTFS trip identifiers included in the simulation.
fleet_operation	DataFrame	Aggregated fleet operation schedule (result - computed after simulation).
trip_travel_sequences	DataFrame	Aggregated event-level travel sequences (result - computed after simulation).

Examples:

>>> simulator = FleetSimulator(manager, trip_ids=["trip_1", "trip_2"])
>>> simulator.compute_fleet_operation()
>>> fleet_df = simulator.fleet_operation
>>> traj = simulator.get_fleet_trajectory(time_step=120)

Attributes

fleet_operation property

Aggregated fleet-wide operation schedule.

Each row corresponds to a simulated vehicle-trip combination and includes operational metrics such as:

• Operation start and end times
• Number of trip repetitions
• Travel, stop, and terminal durations
• Total distance and active time

Returns:

Type	Description
DataFrame	pd.DataFrame: Fleet operation description.

gtfs_manager property writable

GTFS data manager associated with the fleet simulator.

Returns:

Name	Type	Description
GTFSManager	GTFSManager	The GTFS manager instance.

trip_ids property writable

List of GTFS trip identifiers included in the fleet simulation.

Returns:

Type	Description
list	list[str]: Trip IDs simulated by the fleet simulator.

trip_travel_sequences property

Aggregated event-level travel sequences for all simulated trips.

This DataFrame merges the single_trip_sequence outputs of all underlying TripSimulator` instances and includes:

• Event type (travelling, at_stop, at_terminal)
• Duration and distance
• Geometry (Point or LineString)
• Associated trip identifier

Returns:

Type	Description
DataFrame	pd.DataFrame: Fleet-wide travel event sequences.

Functions

__init__(gtfs_manager, trip_ids=None)

Initialize a FleetSimulator for a set of GTFS trips.

This constructor binds the simulator to a GTFSManager and validates the list of trips to be simulated. If no trip IDs are provided, all available trips in the GTFS feed are selected.

Parameters:

Name	Type	Description	Default
gtfs_manager	GTFSManager	Instance managing the GTFS dataset.	required
trip_ids	list[str]	List of trip IDs to simulate. If None, all trips in the GTFS feed are included.	None

Raises:

Type	Description
ValueError	If one or more trip IDs are not found in the GTFS dataset.

compute_fleet_operation(use_multiprocessing=False, transient_regime=False)

Compute the fleet-wide operation schedule for all selected trips.

This method iterates over the configured trip IDs, runs a TripSimulator for each trip, and aggregates their fleet operation outputs into a single DataFrame.

Optionally, multiprocessing can be enabled to parallelize per-trip simulations and reduce computation time for large fleets.

The result is stored internally in self.fleet_operation and self.trip_travel_sequences.

Parameters:

Name	Type	Description	Default
use_multiprocessing	bool	If True, run trip simulations in parallel using Python multiprocessing. Default is False.	False
transient_regime	bool	Whether to include transient (non-steady-state) fleet behavior in the simulation.	False

Returns:

Type	Description
None	None

generate_fleet_trajectory_map(fleet_trajectory, filepath)

Generate an interactive HTML map visualizing fleet trajectories.

This method merges per-trip folium maps generated by TripSimulator into a single interactive map with a time slider showing vehicle movements.

Warning

This visualization currently assumes a fixed time step of 2 minutes.

Parameters:

Name	Type	Description	Default
fleet_trajectory	DataFrame	Fleet trajectory DataFrame as returned by :meth:get_fleet_trajectory.	required
filepath	str	Path where the generated HTML map is saved.	required

Returns:

Type	Description
None	None

get_fleet_trajectory(time_step, transient_regime=False)

Compute time-resolved spatial trajectories for the entire fleet.

For each simulated trip, this method recomputes the fleet operation and generates vehicle trajectories sampled at a fixed time step.

Warning

This method needs to be further optimized. For the moment, it recomputes trip simulations internally and may be computationally heavy.

Parameters:

Name	Type	Description	Default
time_step	int	Temporal resolution in seconds at which vehicle positions are sampled.	required
transient_regime	bool	Whether to include transient fleet behavior.	False

Returns:

Type	Description
DataFrame	pd.DataFrame: Multi-index DataFrame indexed by
DataFrame	(trip_id, vehicle_id) with columns representing time steps
DataFrame	(HH:MM:SS). Each cell contains a shapely.geometry.Point
DataFrame	representing the vehicle location or None.