ChargingSimulator

Electric vehicle charging simulation engine driven by fleet operations.

The ChargingSimulator takes fleet operation outputs and reconstructs vehicle-level energy consumption and charging behavior. It supports multiple charging strategies.

The simulator computes:

• Vehicle-level charging schedules
• Stop-level aggregated charging demand
• Battery capacity requirements
• Charging load curves by location
• Map of charging activity

Charging strategies can be predefined identifiers or user-defined callables. Multiple charging strategies can be provided and are then applied in sequence until energy needs are satisfied.

The following predifined charging strategy identifiers are supported:

• "terminal_random": Attempts charging at terminal stops with a given probability.

• "terminal_specific_random": Attempts charging only at a user-defined subset of terminal stop IDs with a given probability.

• "stop_random": Attempts charging at intermediate stops (at_stop events) with a given probability.

• "depot_day": Attempts charging during daytime non-operating periods.

• "depot_night" Attempts charging at the beginning and/or end of the service day.

Charging power availability is defined through the charging_powers_kW dictionary, which specifies discrete charging power options and their selection probabilities for each location type.

Notes

• Fleet operation must be computed before initializing this simulator.
• Charging is simulated over a single service day.
• Overlapping charging events are automatically prevented.

Attributes:

Name	Type	Description
fleet_sim	FleetSimulator	Fleet simulator containing vehicle operations.
energy_consumption_kWh_per_km	float	Vehicle energy consumption rate.
security_driving_distance_km	float	Safety distance added to energy needs.
charging_powers_kW	dict	Charging power distributions by location type.
charging_schedule_pervehicle	DataFrame	Vehicle-level charging results (computed after simulation).
charging_schedule_perstop	DataFrame	Stop-level aggregated charging results (computed after simulation).

Examples:

>>> charging_sim = ChargingSimulator(fleet_sim, 1.2, 10.0, charging_powers_kW)
>>> charging_sim.compute_charging_schedule(["depot_night", "terminal_random"])
>>> df_vehicle = charging_sim.charging_schedule_pervehicle

Example configuration for charging powers:

charging_powers_kW = {
    "depot": [
        [22, 0.6],    # 22 kW charger, 60% probability
        [150, 0.4]    # 150 kW charger, 40% probability
    ],
    "terminal": [
        [50, 1.0]     # 50 kW charger, always selected
    ],
    "stop": [
        [50, 0.7],    # 50 kW charger, 70% probability
        [120, 0.3]     # 120 kW charger, 30% probability
    ]
}

Attributes

charging_powers_kW property writable

Charging power distributions by location type.

Returns:

Name	Type	Description
dict	dict	Mapping of location type to charging power distributions.

charging_schedule_perstop property

Stop-level aggregated charging schedules.

Returns:

Type	Description
DataFrame	pd.DataFrame: Aggregated charging demand per stop.

charging_schedule_pervehicle property

Vehicle-level charging schedules.

Returns:

Type	Description
DataFrame	pd.DataFrame: Charging schedules and battery metrics per vehicle.

energy_consumption_kWh_per_km property writable

Energy consumption rate of vehicles.

Returns:

Name	Type	Description
float	float	Energy consumption in kWh per kilometer.

fleet_sim property writable

Fleet simulator used as input for charging simulations.

Returns:

Name	Type	Description
FleetSimulator	FleetSimulator	Fleet simulator with computed operations.

security_driving_distance_km property writable

Safety driving distance added to daily energy needs.

Returns:

Name	Type	Description
float	float	Safety distance in kilometers.

Functions

__init__(fleet_sim, energy_consumption_kWh_per_km, security_driving_distance_km, charging_powers_kW=None)

Initialize a ChargingSimulator based on an existing fleet simulation.

The constructor validates that fleet operations have already been computed and initializes all parameters required for energy and charging simulations.

Parameters:

Name	Type	Description	Default
fleet_sim	FleetSimulator	Fleet simulator containing vehicle operations.	required
energy_consumption_kWh_per_km	float	Energy consumption per kilometer.	required
security_driving_distance_km	float	Additional safety distance in kilometers.	required
charging_powers_kW	dict	Charging power distributions by location type.	None

Raises:

Type	Description
ValueError	If fleet operation data is missing or parameters are invalid.

compute_charging_load_curve(time_step_s)

Compute aggregated charging load curves by location type.

Parameters:

Name	Type	Description	Default
time_step_s	int	Time resolution in seconds.	required

Returns:

Type	Description
DataFrame	pd.DataFrame: Time series of aggregated charging power by location.

compute_charging_schedule(charging_strategies, **kwargs)

Compute vehicle-level and stop-level charging schedules.

This method reconstructs vehicle travel timelines, estimates energy needs, and applies a sequence of charging strategies until the required energy is satisfied or no further charging is possible.

Charging strategies are applied in priority order and may be predefined identifiers or user-provided callables. Charging strategies are provided as a list of string identifiers, each corresponding to a known strategy supported by the _generate_charging_events_for_strategy method.

For each vehicle, the method:

1. Reconstructs the detailed travel sequence based on operational data and predefined trip structure.
2. Estimates the total energy need based on distance traveled and energy consumption rate.
3. Applies each charging strategy (in priority order) to generate charging events.
4. Accepts new charging events until the energy need is met.
5. Records the charging events, energy requirement, remaining unmet energy, and minimum required battery capacity.

The method also computes stop-level charging statistics by aggregating all vehicle charging events.

Populates self.charging_schedule_pervehicle and self.charging_schedule_perstop

Parameters:

Name	Type	Description	Default
charging_strategies	list[str or callable]	Ordered list of charging strategies. Each element can be either: - A predefined strategy identifier (e.g. "terminal_random", "terminal_specific_random", "stop_random", "depot_day", "depot_night") - A user-defined callable with signature strategy(travel_sequence, **kwargs)	required
**kwargs		Additional keyword arguments forwarded to charging strategy handlers. Currently supported keyword arguments: - specific_terminal_ids (list[str]): List of terminal stop IDs eligible for charging when using the "terminal_specific_random" strategy.	{}

Returns:

Type	Description
None	None

generate_charging_map(stop_charging_schedule, filepath)

Generate an interactive map visualizing charging activity at stops.

Parameters:

Name	Type	Description	Default
stop_charging_schedule	DataFrame	Stop-level charging results.	required
filepath	str	Output path for the generated HTML map.	required

Returns:

Type	Description
None	None