depot.api.private.consumption ============================= .. py:module:: depot.api.private.consumption Classes ------- .. autoapisummary:: depot.api.private.consumption.ConsumptionResult depot.api.private.consumption.ConsumptionInformation Functions --------- .. autoapisummary:: depot.api.private.consumption.extract_trip_information depot.api.private.consumption.initialize_vehicle depot.api.private.consumption.add_initial_standby_event depot.api.private.consumption.find_charger_occupancy depot.api.private.consumption.find_best_timeslot depot.api.private.consumption.attempt_opportunity_charging_event Module Contents --------------- .. py:class:: 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. :param 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%). :param 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``. :param 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. .. py:attribute:: delta_soc_total :type: float .. py:attribute:: timestamps :type: List[datetime.datetime] | None .. py:attribute:: delta_soc :type: List[float] | None .. py:class:: ConsumptionInformation A dataclass to hold the information needed for the consumption simulation. :param trip_id: The ID of the trip for which the consumption is calculated. :param consumption_lut: The ConsumptionLut object for the vehicle class. This is used to calculate the consumption based on the trip parameters. :param average_speed: The average speed of the trip in km/h. This is used to calculate the consumption. :param distance: The distance of the trip in km. This is used to calculate the total consumption. :param temperature: The ambient temperature in °C. This is used to calculate the consumption. :param level_of_loading: The level of loading of the vehicle as a fraction of its maximum payload. :param incline: The incline of the trip as a fraction (0.0-1.0). This is used to calculate the consumption. :param consumption: The total consumption of the trip in kWh. This is calculated based on the LUT and trip parameters. :param consumption_per_km: The consumption per km in kWh. This is calculated based on the LUT and trip parameters. .. py:attribute:: trip_id :type: int .. py:attribute:: consumption_lut :type: eflips.model.ConsumptionLut | None .. py:attribute:: average_speed :type: float .. py:attribute:: distance :type: float .. py:attribute:: temperature :type: float .. py:attribute:: level_of_loading :type: float .. py:attribute:: incline :type: float :value: 0.0 .. py:attribute:: consumption :type: float :value: None .. py:attribute:: consumption_per_km :type: float :value: None .. py:method:: calculate() Calculates the consumption for the trip. Returns a float in kWh. :return: The energy consumption in kWh. This is already the consumption for the whole trip. .. py:method:: generate_consumption_result(battery_capacity) Generates a ConsumptionResult object from the current instance. :param battery_capacity: The battery capacity in kWh. :return: A ConsumptionResult object containing the total change in SoC and optional timeseries. .. py:function:: extract_trip_information(trip_id, scenario, passenger_mass=68, passenger_count=17.6) Extracts the information needed for the consumption simulation from a trip. .. py:function:: 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. :param rotation: A :class:`Rotation` instance for which a new ``Vehicle`` should be created. The new vehicle will inherit its type and scenario from this rotation. :param session: An active SQLAlchemy :class:`Session` used to persist the new vehicle to the database. The vehicle is added to the session but not committed here. :return: ``None``. Changes are made to the session but are not committed yet. .. py:function:: 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 :class:`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). :param vehicle: A :class:`Vehicle` instance for which to add a new standby event. Must have associated rotations and trips. :param session: An active SQLAlchemy :class:`Session` used to persist the new event to the database. The event is added to the session but not committed here. :return: ``None``. A new event is added to the session for the earliest trip, but changes are not yet committed. .. py:function:: 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. :param station: The :class:`Station` whose charger occupancy is to be analyzed. :param time_start: The start time for the occupancy timeseries (inclusive). :param time_end: The end time for the occupancy timeseries (exclusive). :param session: An active SQLAlchemy :class:`Session` used to query the database. :param 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. .. py:function:: find_best_timeslot(station, time_start, time_end, charging_duration, session, resolution = timedelta(seconds=1)) .. py:function:: attempt_opportunity_charging_event(previous_trip, next_trip, vehicle, charge_start_soc, terminus_deadtime, session)