depot.api.private.consumption

Classes

ConsumptionResult

A dataclass that stores the results of a charging simulation for a single trip.

ConsumptionInformation

A dataclass to hold the information needed for the consumption simulation.

Functions

extract_trip_information(trip_id, scenario[, ...])

Extracts the information needed for the consumption simulation from a trip.

initialize_vehicle(rotation, session)

Create and add a new Vehicle object in the database for the given rotation.

add_initial_standby_event(vehicle, session)

Create and add a standby event immediately before the earliest trip of the given vehicle.

find_charger_occupancy(station, time_start, time_end, ...)

Build a timeseries of charger occupancy at a station between two points in time.

find_best_timeslot(station, time_start, time_end, ...)

attempt_opportunity_charging_event(previous_trip, ...)

Module Contents

class depot.api.private.consumption.ConsumptionResult

A dataclass that stores the results of a charging simulation for a single trip.

This class holds both the total change in battery State of Charge (SoC) over the trip as well as an optional timeseries of timestamps and incremental SoC changes. When an entry exists for a given trip in consumption_result, the simulation will use these precomputed values instead of recalculating the SoC changes from the vehicle distance and consumption.

Parameters:

  • delta_soc_total – The total change in the vehicle’s State of Charge over the trip, typically negative if the vehicle is consuming energy (e.g., -0.15 means the SoC dropped by 15%).

  • timestamps – A list of timestamps (e.g., arrival times at stops) that mark the times associated with the SoC changes. The number of timestamps must match the number of entries in delta_soc.

  • delta_soc – A list of cumulative SoC changes corresponding to the timestamps. For example, if delta_soc[i] = -0.02, it means the SoC decreased by 2% between from the start of the trip to timestamps[i]. This list should typically be a monotonic decreasing sequence.

delta_soc_total: float
timestamps: List[datetime.datetime] | None
delta_soc: List[float] | None
class depot.api.private.consumption.ConsumptionInformation

A dataclass to hold the information needed for the consumption simulation.

Parameters:

  • trip_id – The ID of the trip for which the consumption is calculated.

  • consumption_lut – The ConsumptionLut object for the vehicle class. This is used to calculate the consumption based on the trip parameters.

  • average_speed – The average speed of the trip in km/h. This is used to calculate the consumption.

  • distance – The distance of the trip in km. This is used to calculate the total consumption.

  • temperature – The ambient temperature in °C. This is used to calculate the consumption.

  • level_of_loading – The level of loading of the vehicle as a fraction of its maximum payload.

  • incline – The incline of the trip as a fraction (0.0-1.0). This is used to calculate the consumption.

  • consumption – The total consumption of the trip in kWh. This is calculated based on the LUT and trip parameters.

  • consumption_per_km – The consumption per km in kWh. This is calculated based on the LUT and trip parameters.

trip_id: int
consumption_lut: eflips.model.ConsumptionLut | None
average_speed: float
distance: float
temperature: float
level_of_loading: float
incline: float = 0.0
consumption: float = None
consumption_per_km: float = None
calculate()

Calculates the consumption for the trip. Returns a float in kWh.

Returns:

The energy consumption in kWh. This is already the consumption for the whole trip.

generate_consumption_result(battery_capacity)

Generates a ConsumptionResult object from the current instance.

Parameters:

battery_capacity – The battery capacity in kWh.

Returns:

A ConsumptionResult object containing the total change in SoC and optional timeseries.

Return type:

ConsumptionResult

depot.api.private.consumption.extract_trip_information(trip_id, scenario, passenger_mass=68, passenger_count=17.6)

Extracts the information needed for the consumption simulation from a trip.

Parameters:

  • trip_id (int)

  • scenario (eflips.model.Scenario)

Return type:

ConsumptionInformation

depot.api.private.consumption.initialize_vehicle(rotation, session)

Create and add a new Vehicle object in the database for the given rotation.

This function:

  1. Creates a new Vehicle instance using the provided rotation’s vehicle type and scenario ID.

  2. Names it based on the rotation’s ID.

  3. Adds the vehicle to the specified SQLAlchemy session.

  4. Assigns the new vehicle to the rotation’s vehicle attribute.

Parameters:

  • rotation (eflips.model.Rotation) – A Rotation instance for which a new Vehicle should be created. The new vehicle will inherit its type and scenario from this rotation.

  • session (sqlalchemy.orm.session.Session) – An active SQLAlchemy Session used to persist the new vehicle to the database. The vehicle is added to the session but not committed here.

Returns:

None. Changes are made to the session but are not committed yet.

depot.api.private.consumption.add_initial_standby_event(vehicle, session)

Create and add a standby event immediately before the earliest trip of the given vehicle.

This function:

  1. Gathers all rotations assigned to the vehicle, sorted by their first trip’s departure time.

  2. Identifies the earliest trip across those rotations.

  3. Fetches an appropriate Area record from the database based on the vehicle’s scenario and vehicle type (for depot and subloc capacity).

  4. Constructs a dummy standby event starting one second before the earliest trip’s departure time, ending at the trip’s departure time, with 100% SoC.

  5. Adds the event to the session without committing (the caller is responsible for commits).

Parameters:

  • vehicle (eflips.model.Vehicle) – A Vehicle instance for which to add a new standby event. Must have associated rotations and trips.

  • session (sqlalchemy.orm.session.Session) – An active SQLAlchemy Session used to persist the new event to the database. The event is added to the session but not committed here.

Returns:

None. A new event is added to the session for the earliest trip, but changes are not yet committed.

Return type:

None

depot.api.private.consumption.find_charger_occupancy(station, time_start, time_end, session, resolution=timedelta(seconds=1))

Build a timeseries of charger occupancy at a station between two points in time.

For each discrete timestep between time_start and time_end (at the given resolution), this function calculates how many charging events (from the database) overlap with that time, thus producing a count of the active chargers at each timestep.

Parameters:

  • station (eflips.model.Station) – The Station whose charger occupancy is to be analyzed.

  • time_start (datetime.datetime) – The start time for the occupancy timeseries (inclusive).

  • time_end (datetime.datetime) – The end time for the occupancy timeseries (exclusive).

  • session (sqlalchemy.orm.session.Session) – An active SQLAlchemy Session used to query the database.

  • resolution – The timestep interval used to build the timeseries (default is 1 second). Note that using a very fine resolution over a large time range can produce large arrays.

Returns:

A tuple of two numpy arrays:

  1. times: The array of discrete timesteps (shape: (n,)).

  2. occupancy: The array of integer occupancy values for each timestep (shape: (n,)), indicating how many charging events are active.

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

depot.api.private.consumption.find_best_timeslot(station, time_start, time_end, charging_duration, session, resolution=timedelta(seconds=1))
Parameters:

  • station (eflips.model.Station)

  • time_start (datetime.datetime)

  • time_end (datetime.datetime)

  • charging_duration (datetime.timedelta)

  • session (sqlalchemy.orm.session.Session)

  • resolution (datetime.timedelta)

Return type:

datetime.datetime

depot.api.private.consumption.attempt_opportunity_charging_event(previous_trip, next_trip, vehicle, charge_start_soc, terminus_deadtime, session)
Parameters:

  • previous_trip (eflips.model.Trip)

  • next_trip (eflips.model.Trip)

  • vehicle (eflips.model.Vehicle)

  • charge_start_soc (float)

  • terminus_deadtime (datetime.timedelta)

  • session (sqlalchemy.orm.session.Session)

Return type:

float