eflips-depot 4.4.3__py3-none-any.whl → 4.6.0__py3-none-any.whl

eflips/depot/__init__.py

@@ -53,3 +53,7 @@ from eflips.depot.simulation import (
 from eflips.depot.smart_charging import SmartCharging, ControlSmartCharging
 from eflips.depot.standalone import VehicleGenerator, SimpleTrip, Timetable
 from eflips.depot.validation import Validator
+
+
+class UnstableSimulationException(Exception):
+    pass

eflips/depot/api/__init__.py

@@ -25,15 +25,15 @@ The following steps are recommended for using the API:
     b. Run the :func:`simple_consumption_simulation` function again, this time with ``initialize_vehicles=False``.
 """
 import copy
-import datetime
 import logging
 import os
 import warnings
 from collections import OrderedDict
-from datetime import timedelta
+from dataclasses import dataclass
+from datetime import timedelta, datetime
 from enum import Enum
 from math import ceil
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, Optional, Union, List
 
 import sqlalchemy.orm
 from eflips.model import (
@@ -47,6 +47,7 @@ from eflips.model import (
     Vehicle,
     VehicleType,
     AreaType,
+    ChargeType,
 )
 from sqlalchemy.orm import Session
 
@@ -55,6 +56,11 @@ from eflips.depot import (
     DepotEvaluation,
     SimulationHost,
 )
+from eflips.depot.api.private.consumption import (
+    initialize_vehicle,
+    add_initial_standby_event,
+    attempt_opportunity_charging_event,
+)
 from eflips.depot.api.private.depot import (
     delete_depots,
     depot_to_template,
@@ -107,47 +113,131 @@ class SmartChargingStrategy(Enum):
     """
 
 
+@dataclass
+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.
+    """
+
+    delta_soc_total: float
+    timestamps: List[datetime] | None
+    delta_soc: List[float] | None
+
+
 def simple_consumption_simulation(
     scenario: Union[Scenario, int, Any],
     initialize_vehicles: bool,
     database_url: Optional[str] = None,
     calculate_timeseries: bool = False,
     terminus_deadtime: timedelta = timedelta(minutes=1),
+    consumption_result: Dict[int, ConsumptionResult] | None = None,
 ) -> None:
     """
-    A simple consumption simulation and vehicle initialization.
-
-    Energy consumotion is calculated by multiplying the vehicle's total distance by a constant
-    ``VehicleType.consumption``.
-
-    If run with ``initialize_vehicles=True``, the method will also initialize the vehicles in the database with the
-    correct vehicle type and assign them to rotations. If this is false, it will assume that there are already vehicle
-    entries and ``Rotation.vehicle_id`` is already set.
-
-    :param scenario: Either a :class:`eflips.model.Scenario` object containing the input data for the simulation. Or
-        an integer specifying the ID of a scenario in the database. Or any other object that has an attribute
-        ``id`` that is an integer. If no :class:`eflips.model.Scenario` object is passed, the ``database_url``
-        parameter must be set to a valid database URL ot the environment variable ``DATABASE_URL`` must be set to a
-        valid database URL.
-
-    :param initialize_vehicles: A boolean flag indicating whether the vehicles should be initialized in the database.
-        When running this function for the first time, this should be set to True. When running this function again
-        after the vehicles have been initialized, this should be set to False.
-
-    :param database_url: An optional database URL. If no database URL is passed and the `scenario` parameter is not a
-        :class:`eflips.model.Scenario` object, the environment variable `DATABASE_URL` must be set to a
-        valid database URL.
-
-    :param calculate_timeseries: A boolean flag indicating whether the timeseries should be calculated. If this is set
-        to True, the SoC at each stop is calculated and added to the "timeseries" column of the Event table. If this
-        is set to False, the "timeseries" column of the Event table will be set to ``None``. Setting this to false
-        may significantly speed up the simulation.
-
-    :param terminus_deadtime: The total deadtime taken to both attach and detach the charging cable at the terminus.
-                              If the total deadtime is greater than the time between the arrival and departure of the
-                              vehicle at the terminus, the vehicle will not be able to charge at the terminus.
-
-    :return: Nothing. The results are added to the database.
+    Run a simple consumption simulation and optionally initialize vehicles in the database.
+
+    This function calculates energy consumption by multiplying each vehicle's total traveled
+    distance by a constant ``VehicleType.consumption`` (kWh per km), then updates the database
+    with the resulting SoC (State of Charge) data. The function can also use precomputed results
+    for specific trips via the ``consumption_result`` parameter.
+
+    If ``initialize_vehicles`` is True, vehicles and an initial STANDBY event (with 100% SoC)
+    are created for each rotation that does not already have a vehicle. If it is False, existing
+    vehicles in the database are assumed, and a check is performed to ensure each rotation has a
+    vehicle.
+
+    Opportunity charging can optionally be applied at the end of each trip, if the vehicle and
+    station both allow it, and if the rotation is flagged to allow it. This charging event is
+    constrained by a configurable terminus deadtime.
+
+    **SoC Constraints**
+
+    - When no precomputed results are provided, SoC is computed by subtracting energy used
+      (`consumption * distance / battery_capacity`) from the previous event’s SoC.
+    - When precomputed ``ConsumptionResult`` objects are provided in ``consumption_result``,
+      they must have a non-positive total change in SoC (``delta_soc_total <= 0``).
+      If the function detects a positive ``delta_soc_total``, it raises a ``ValueError``.
+
+    **Timeseries Calculation**
+
+    - If ``calculate_timeseries`` is True, the function builds a more granular SoC timeseries
+      at each stop in the trip and stores it in the ``Event.timeseries`` column.
+    - If False, the event’s ``timeseries`` is set to ``None``, which may speed up the simulation
+      if you do not need intermediate SoC data.
+
+    :param scenario:
+        One of:
+          - A :class:`eflips.model.Scenario` instance containing the input data for the simulation.
+          - An integer specifying the ID of a scenario in the database.
+          - Any other object with an integer ``id`` attribute.
+
+        If not passing a :class:`eflips.model.Scenario` directly, the `database_url` parameter
+        or the environment variable ``DATABASE_URL`` must point to a valid database.
+
+    :param initialize_vehicles:
+        A boolean flag indicating whether new vehicles should be created and assigned
+        to rotations in the database. Set this to True the first time you run the simulation
+        so that vehicles are initialized. In subsequent runs, set to False if vehicles
+        are already present.
+
+    :param database_url:
+        A database connection string (e.g., ``postgresql://user:pass@host/db``).
+        If you do not provide this and ``scenario`` is not a
+        :class:`eflips.model.Scenario` instance, the environment variable
+        ``DATABASE_URL`` must be set.
+
+    :param calculate_timeseries:
+        If True, each trip’s detailed SoC timeseries is computed and stored in the
+        ``timeseries`` column of the corresponding driving and charging events.
+        If False, only the start/end SoC is recorded, and ``timeseries`` is set to None.
+
+    :param terminus_deadtime:
+        The total time overhead (attach + detach) for charging at the terminus.
+        If this deadtime exceeds the available layover time, no charging is performed.
+
+    :param consumption_result:
+        A dictionary mapping trip IDs to :class:`ConsumptionResult` instances for
+        precomputed SoC changes. If an entry exists for a trip, this function uses
+        those precomputed SoC changes instead of calculating them from distance
+        and consumption. Each ``ConsumptionResult`` must have:
+
+        - A non-positive ``delta_soc_total`` (<= 0).
+        - Optionally, matching lists of timestamps and delta SoC values that are
+          decreasing (i.e., the vehicle only loses or maintains SoC).
+
+    :returns:
+        ``None``. All simulation results are written directly to the database as
+        :class:`eflips.model.Event` entries.
+
+    :raises ValueError:
+        - If a rotation in the scenario does not have a vehicle when
+          ``initialize_vehicles=False``.
+        - If the vehicle type has no ``consumption`` value.
+        - If a provided ``ConsumptionResult`` has inconsistent list lengths,
+          or if its ``delta_soc_total`` is positive.
+        - If SoC timeseries are not decreasing when provided
+          via ``consumption_result``.
     """
     logger = logging.getLogger(__name__)
 
@@ -162,76 +252,18 @@ def simple_consumption_simulation(
         )
         if initialize_vehicles:
             for rotation in rotations:
-                vehicle = Vehicle(
-                    vehicle_type_id=rotation.vehicle_type_id,
-                    scenario_id=scenario.id,
-                    name=f"Vehicle for rotation {rotation.id}",
-                )
-                session.add(vehicle)
-                rotation.vehicle = vehicle
+                initialize_vehicle(rotation, session)
 
-                # Additionally, add a short STANDBY event with 100% SoC immediately before the first trip
-                first_trip_start = rotation.trips[0].departure_time
-                standby_start = first_trip_start - timedelta(seconds=1)
-                standby_event = Event(
-                    scenario_id=scenario.id,
-                    vehicle_type_id=rotation.vehicle_type_id,
-                    vehicle=vehicle,
-                    station_id=rotation.trips[0].route.departure_station_id,
-                    subloc_no=0,
-                    time_start=standby_start,
-                    time_end=first_trip_start,
-                    soc_start=1,
-                    soc_end=1,
-                    event_type=EventType.CHARGING_OPPORTUNITY,
-                    description=f"DUMMY Initial standby event for rotation {rotation.id}.",
-                    timeseries=None,
-                )
-                session.add(standby_event)
-        else:
-            for rotation in rotations:
-                if rotation.vehicle is None:
-                    raise ValueError(
-                        "The rotation does not have a vehicle assigned to it."
-                    )
-
-            vehicles = (
-                session.query(Vehicle).filter(Vehicle.scenario_id == scenario.id).all()
-            )
-            for vehicle in vehicles:
-                if (
-                    session.query(Event).filter(Event.vehicle_id == vehicle.id).count()
-                    == 0
-                ):
-                    # Also add a dummy standby-departure event if this vehicle has no events
-                    rotation_per_vehicle = sorted(
-                        vehicle.rotations, key=lambda r: r.trips[0].departure_time
-                    )
-                    earliest_trip = rotation_per_vehicle[0].trips[0]
-                    area = (
-                        session.query(Area)
-                        .filter(Area.scenario_id == scenario.id)
-                        .filter(Area.vehicle_type_id == Vehicle.vehicle_type_id)
-                        .first()
-                    )
+        for rotation in rotations:
+            if rotation.vehicle is None:
+                raise ValueError("The rotation does not have a vehicle assigned to it.")
 
-                    standby_start = earliest_trip.departure_time - timedelta(seconds=1)
-                    standby_event = Event(
-                        scenario_id=scenario.id,
-                        vehicle_type_id=vehicle.vehicle_type_id,
-                        vehicle=vehicle,
-                        station_id=area.depot.station_id,
-                        area_id=area.id,
-                        subloc_no=area.capacity,
-                        time_start=standby_start,
-                        time_end=earliest_trip.departure_time,
-                        soc_start=1,
-                        soc_end=1,
-                        event_type=EventType.STANDBY_DEPARTURE,
-                        description=f"DUMMY Initial standby event for rotation {earliest_trip.rotation_id}.",
-                        timeseries=None,
-                    )
-                    session.add(standby_event)
+        vehicles = (
+            session.query(Vehicle).filter(Vehicle.scenario_id == scenario.id).all()
+        )
+        for vehicle in vehicles:
+            if session.query(Event).filter(Event.vehicle_id == vehicle.id).count() == 0:
+                add_initial_standby_event(vehicle, session)
 
         # Since we are doing no_autoflush blocks later, we need to flush the session once here so that unflushed stuff
         # From preceding functions is visible in the database
@@ -253,9 +285,15 @@ def simple_consumption_simulation(
                     .one()
                 )
             if vehicle_type.consumption is None:
-                raise ValueError(
-                    "The vehicle type does not have a consumption value set."
-                )
+                # If the vehicle type has no consumption value, all trips must have a precomputed consumption result
+                all_trip_ids = [trip.id for trip in rotation.trips]
+                if not (
+                    consumption_result is not None
+                    and all(trip_id in consumption_result for trip_id in all_trip_ids)
+                ):
+                    raise ValueError(
+                        "The vehicle type does not have a consumption value set and no consumption results are provided."
+                    )
             consumption = vehicle_type.consumption
 
             # The departure SoC for this rotation is the SoC of the last event preceding the first trip
@@ -270,36 +308,79 @@ def simple_consumption_simulation(
 
             for trip in rotation.trips:
                 # Set up a timeseries
-                soc_start = current_soc
-                if calculate_timeseries and len(trip.stop_times) > 0:
-                    timeseries = {
-                        "time": [],
-                        "soc": [],
-                        "distance": [],
-                    }
-                    for i in range(len(trip.stop_times)):
-                        current_time = trip.stop_times[i].arrival_time
-                        dwell_duration = trip.stop_times[i].dwell_duration
-                        elapsed_distance = trip.route.assoc_route_stations[
-                            i
-                        ].elapsed_distance
-                        elapsed_energy = consumption * (elapsed_distance / 1000)  # kWh
-                        soc = (
-                            current_soc - elapsed_energy / vehicle_type.battery_capacity
-                        )
-                        timeseries["time"].append(current_time.isoformat())
-                        timeseries["soc"].append(soc)
-                        timeseries["distance"].append(elapsed_distance)
-                        if dwell_duration > timedelta(seconds=0):
-                            timeseries["time"].append(
-                                (current_time + dwell_duration).isoformat()
+                if consumption_result is None or trip.id not in consumption_result:
+                    logger.debug("Calculating consumption for trip %s", trip.id)
+                    soc_start = current_soc
+                    if calculate_timeseries and len(trip.stop_times) > 0:
+                        timeseries = {
+                            "time": [],
+                            "soc": [],
+                            "distance": [],
+                        }
+                        for i in range(len(trip.stop_times)):
+                            current_time = trip.stop_times[i].arrival_time
+                            dwell_duration = trip.stop_times[i].dwell_duration
+                            elapsed_distance = trip.route.assoc_route_stations[
+                                i
+                            ].elapsed_distance
+                            elapsed_energy = consumption * (
+                                elapsed_distance / 1000
+                            )  # kWh
+                            soc = (
+                                current_soc
+                                - elapsed_energy / vehicle_type.battery_capacity
                             )
+                            timeseries["time"].append(current_time.isoformat())
                             timeseries["soc"].append(soc)
                             timeseries["distance"].append(elapsed_distance)
+                            if dwell_duration > timedelta(seconds=0):
+                                timeseries["time"].append(
+                                    (current_time + dwell_duration).isoformat()
+                                )
+                                timeseries["soc"].append(soc)
+                                timeseries["distance"].append(elapsed_distance)
+                    else:
+                        timeseries = None
+                    energy_used = consumption * trip.route.distance / 1000  # kWh
+                    current_soc = (
+                        soc_start - energy_used / vehicle_type.battery_capacity
+                    )
                 else:
-                    timeseries = None
-                energy_used = consumption * trip.route.distance / 1000  # kWh
-                current_soc = soc_start - energy_used / vehicle_type.battery_capacity
+                    logger.debug(f"Using pre-calculated timeseries for trip {trip.id}")
+                    if (
+                        calculate_timeseries
+                        and consumption_result[trip.id].timestamps is not None
+                    ):
+                        assert consumption_result[trip.id].delta_soc is not None
+                        timestamps = consumption_result[trip.id].timestamps
+
+                        # Make sure the delta_soc is a monotonic decreasing function, with the same length as timestamps
+                        if len(consumption_result[trip.id].delta_soc) != len(
+                            timestamps
+                        ):
+                            raise ValueError(
+                                "The length of the delta_soc and timestamps lists must be the same."
+                            )
+                        delta_socs = consumption_result[trip.id].delta_soc
+                        if delta_socs[-1] > 0:
+                            raise ValueError(
+                                "The delta_soc must be a decreasing function."
+                            )
+
+                        socs = [current_soc + d for d in delta_socs]
+                        timeseries = {
+                            "time": [t.isoformat() for t in timestamps],
+                            "soc": socs,
+                        }
+                    else:
+                        timeseries = None
+
+                    if consumption_result[trip.id].delta_soc_total > 0:
+                        raise ValueError(
+                            "The current SoC must be <= 0 when using a consumption result."
+                        )
+                    soc_start = current_soc
+                    current_soc += consumption_result[trip.id].delta_soc_total
 
                 # Create a driving event
                 current_event = Event(
@@ -328,68 +409,20 @@ def simple_consumption_simulation(
                     rotation.vehicle_type.opportunity_charging_capable
                     and rotation.allow_opportunity_charging
                     and trip.route.arrival_station.is_electrified
+                    and trip.route.arrival_station.charge_type == ChargeType.OPPORTUNITY
                     and trip != rotation.trips[-1]
                 ):
-                    logger.debug(
-                        f"Adding opportunity charging event for trip {trip.id}"
-                    )
-                    # Identify the break time between trips
                     trip_index = rotation.trips.index(trip)
                     next_trip = rotation.trips[trip_index + 1]
-                    break_time = next_trip.departure_time - trip.arrival_time
-
-                    # How much energy can be charged in this time?
-                    energy_charged = (
-                        max([v[1] for v in vehicle_type.charging_curve])
-                        * (
-                            break_time.total_seconds()
-                            - terminus_deadtime.total_seconds()
-                        )
-                        / 3600
-                    )
-
-                    if energy_charged > 0:
-                        # Calculate the end SoC
-                        post_charge_soc = min(
-                            current_soc
-                            + energy_charged / vehicle_type.battery_capacity,
-                            1,
-                        )
-
-                        # Create a simple timeseries for the charging event
-                        timeseries = {
-                            "time": [
-                                trip.arrival_time.isoformat(),
-                                (trip.arrival_time + terminus_deadtime / 2).isoformat(),
-                                (
-                                    next_trip.departure_time - terminus_deadtime / 2
-                                ).isoformat(),
-                                next_trip.departure_time.isoformat(),
-                            ],
-                            "soc": [
-                                current_soc,
-                                current_soc,
-                                post_charge_soc,
-                                post_charge_soc,
-                            ],
-                        }
 
-                        # Create the charging event
-                        current_event = Event(
-                            scenario_id=scenario.id,
-                            vehicle_type_id=rotation.vehicle_type_id,
-                            vehicle=vehicle,
-                            station_id=trip.route.arrival_station_id,
-                            time_start=trip.arrival_time,
-                            time_end=next_trip.departure_time,
-                            soc_start=current_soc,
-                            soc_end=post_charge_soc,
-                            event_type=EventType.CHARGING_OPPORTUNITY,
-                            description=f"Opportunity charging event for trip {trip.id}.",
-                            timeseries=timeseries,
-                        )
-                        current_soc = post_charge_soc
-                        session.add(current_event)
+                    current_soc = attempt_opportunity_charging_event(
+                        previous_trip=trip,
+                        next_trip=next_trip,
+                        vehicle=vehicle,
+                        charge_start_soc=current_soc,
+                        terminus_deadtime=terminus_deadtime,
+                        session=session,
+                    )
 
 
 def generate_depot_layout(
@@ -555,22 +588,23 @@ def simulate_scenario(
     repetition_period: Optional[timedelta] = None,
     database_url: Optional[str] = None,
     smart_charging_strategy: SmartChargingStrategy = SmartChargingStrategy.EVEN,
+    ignore_unstable_simulation: bool = False,
 ) -> None:
     """
     This method simulates a scenario and adds the results to the database.
 
     It fills in the "Charging Events" in the :class:`eflips.model.Event` table and associates
     :class:`eflips.model.Vehicle` objects with all the existing "Driving Events" in the :class:`eflips.model.Event`
-    table.
+    table. If the simulation becomes unstable, an :class:`UnstableSimulationException` is raised.
 
     :param scenario: Either a :class:`eflips.model.Scenario` object containing the input data for the simulation. Or
         an integer specifying the ID of a scenario in the database. Or any other object that has an attribute
         ``id`` that is an integer. If no :class:`eflips.model.Scenario` object is passed, the ``database_url``
-        parameter must be set to a valid database URL ot the environment variable ``DATABASE_URL`` must be set to a
+        parameter must be set to a valid database URL or the environment variable ``DATABASE_URL`` must be set to a
         valid database URL.
 
     :param repetition_period: An optional timedelta object specifying the period of the vehicle schedules. This
-        is needed because the result should be a steady-state result. THis can only be achieved by simulating a
+        is needed because the result should be a steady-state result. This can only be achieved by simulating a
         time period before and after our actual simulation, and then only using the "middle". eFLIPS tries to
         automatically detect whether the schedule should be repeated daily or weekly. If this fails, a ValueError is
         raised and repetition needs to be specified manually.
@@ -580,14 +614,22 @@ def simulate_scenario(
         URL.
 
     :param smart_charging_strategy: An optional parameter specifying the smart charging strategy to be used. The
-        default is SmartChargingStragegy.NONE. The following strategies are available:
-        - SmartChargingStragegy.NONE: Do not use smart charging. Buses are charged with the maximum power available,
+        default is SmartChargingStrategy.NONE. The following strategies are available:
+        - SmartChargingStrategy.NONE: Do not use smart charging. Buses are charged with the maximum power available,
         from the time they arrive at the depot until they are full (or leave the depot).
-        - SmartChargingStragegy.EVEN: Use smart charging with an even distribution of charging power over the time the
+        - SmartChargingStrategy.EVEN: Use smart charging with an even distribution of charging power over the time the
         bus is at the depot. This aims to minimize the peak power demand.
+        - SmartChargingStrategy.MIN_PRICE: Not implemented yet.
+
+    :param ignore_unstable_simulation: If True, the simulation will not raise an exception if it becomes unstable.
 
     :return: Nothing. The results are added to the database.
+
+    :raises UnstableSimulationException: If the simulation becomes numerically unstable or if
+        the parameters cause the solver to diverge.
     """
+    logger = logging.getLogger(__name__)
+
     with create_session(scenario, database_url) as (session, scenario):
         simulation_host = init_simulation(
             scenario=scenario,
@@ -595,7 +637,13 @@ def simulate_scenario(
             repetition_period=repetition_period,
         )
         ev = run_simulation(simulation_host)
-        add_evaluation_to_database(scenario, ev, session)
+        try:
+            add_evaluation_to_database(scenario, ev, session)
+        except eflips.depot.UnstableSimulationException as e:
+            if ignore_unstable_simulation:
+                logger.warning("Simulation is unstable. Continuing.")
+            else:
+                raise e
 
         match smart_charging_strategy:
             case SmartChargingStrategy.NONE:
@@ -842,7 +890,7 @@ def run_simulation(simulation_host: SimulationHost) -> Dict[str, DepotEvaluation
 
 
 def insert_dummy_standby_departure_events(
-    depot_id: int, session: Session, sim_time_end: Optional[datetime.datetime] = None
+    depot_id: int, session: Session, sim_time_end: Optional[datetime] = None
 ) -> None:
     """
     Workaround for the missing STANDBY_DEPARTURE events in the database.
@@ -934,6 +982,9 @@ def add_evaluation_to_database(
         database.
 
     :return: Nothing. The results are added to the database.
+
+    :raises UnstableSimulationException: If the simulation becomes numerically unstable or if
+        the parameters cause the solver to diverge.
     """
 
     # Read simulation start time

eflips/depot/api/private/consumption.py

@@ -0,0 +1,389 @@
+import logging
+from datetime import timedelta, datetime
+from math import ceil
+from typing import Tuple
+from zoneinfo import ZoneInfo
+
+import numpy as np
+import sqlalchemy.orm
+from eflips.model import (
+    Area,
+    Event,
+    EventType,
+    Rotation,
+    Vehicle,
+    Trip,
+    Station,
+    ChargeType,
+)
+
+
+def initialize_vehicle(rotation: Rotation, session: sqlalchemy.orm.session.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.
+    """
+    vehicle = Vehicle(
+        vehicle_type_id=rotation.vehicle_type_id,
+        scenario_id=rotation.scenario_id,
+        name=f"Vehicle for rotation {rotation.id}",
+    )
+    session.add(vehicle)
+    rotation.vehicle = vehicle
+
+
+def add_initial_standby_event(
+    vehicle: Vehicle, session: sqlalchemy.orm.session.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.
+    """
+    logger = logging.getLogger(__name__)
+
+    rotation_per_vehicle = sorted(
+        vehicle.rotations, key=lambda r: r.trips[0].departure_time
+    )
+
+    # Only keep the rotations that contain trips
+    rotation_per_vehicle = [r for r in rotation_per_vehicle if len(r.trips) > 0]
+    if len(rotation_per_vehicle) == 0:
+        logger.warning(f"No trips found for vehicle {vehicle.id}.")
+        return
+
+    earliest_trip = rotation_per_vehicle[0].trips[0]
+    area = (
+        session.query(Area)
+        .filter(Area.scenario_id == vehicle.scenario_id)
+        .filter(Area.vehicle_type_id == vehicle.vehicle_type_id)
+        .first()
+    )
+
+    standby_start = earliest_trip.departure_time - timedelta(seconds=1)
+    standby_event = Event(
+        scenario_id=vehicle.scenario_id,
+        vehicle_type_id=vehicle.vehicle_type_id,
+        vehicle=vehicle,
+        station_id=earliest_trip.route.departure_station_id,
+        subloc_no=0,
+        time_start=standby_start,
+        time_end=earliest_trip.departure_time,
+        soc_start=1,
+        soc_end=1,
+        event_type=EventType.STANDBY_DEPARTURE,
+        description=f"DUMMY Initial standby event for vehicle {vehicle.id}",
+        timeseries=None,
+    )
+    session.add(standby_event)
+
+
+def find_charger_occupancy(
+    station: Station,
+    time_start: datetime,
+    time_end: datetime,
+    session: sqlalchemy.orm.session.Session,
+    resolution=timedelta(seconds=1),
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    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.
+    """
+    # Load all charging events that could be relevant
+    charging_events = (
+        session.query(Event)
+        .filter(
+            Event.station_id == station.id,
+            Event.time_start < time_end,
+            Event.time_end > time_start,
+        )
+        .all()
+    )
+
+    # We need to change the times to numpy datetime64 with implicit UTC timezone
+    tz = ZoneInfo("UTC")
+    time_start = np.datetime64(time_start.astimezone(tz).replace(tzinfo=None))
+    time_end = np.datetime64(time_end.astimezone(tz).replace(tzinfo=None))
+
+    times = np.arange(time_start, time_end, resolution)
+    occupancy = np.zeros_like(times, dtype=int)
+    for event in charging_events:
+        event_start = np.datetime64(
+            event.time_start.astimezone(tz).replace(tzinfo=None)
+        )
+        event_end = np.datetime64(event.time_end.astimezone(tz).replace(tzinfo=None))
+        start_idx = np.argmax(times >= event_start)
+        end_idx = np.argmax(times >= event_end)
+        occupancy[start_idx:end_idx] += 1
+
+    return times, occupancy
+
+
+def find_best_timeslot(
+    station: Station,
+    time_start: datetime,
+    time_end: datetime,
+    charging_duration: timedelta,
+    session: sqlalchemy.orm.session.Session,
+    resolution: timedelta = timedelta(seconds=1),
+) -> datetime:
+    times, occupancy = find_charger_occupancy(
+        station, time_start, time_end, session, resolution=resolution
+    )
+
+    total_span = times[-1] - times[0]
+    if charging_duration > total_span:
+        raise ValueError("The event duration exceeds the entire timeseries span.")
+
+    ## AUTHOR: ChatGPT o-1
+    # Step 1: Compute how many indices are needed to cover `event_duration`.
+    steps_needed = int(charging_duration / resolution)
+    if steps_needed == 0:
+        raise ValueError("event_duration is too small for the timeseries resolution.")
+
+    # Step 2: Build a prefix-sum array for occupancy
+    prefix_sum = np.zeros(len(occupancy) + 1, dtype=float)
+    for i in range(len(occupancy)):
+        prefix_sum[i + 1] = prefix_sum[i] + occupancy[i]
+
+    # Step 3: Slide over every possible start index, compute sum in O(1)
+    best_start_idx = 0
+    min_sum = float("inf")
+    max_start_idx = len(occupancy) - steps_needed
+    if max_start_idx < 0:
+        raise ValueError("event_duration is too large for the timeseries resolution.")
+
+    for start_idx in range(max_start_idx + 1):
+        window_sum = prefix_sum[start_idx + steps_needed] - prefix_sum[start_idx]
+        if window_sum < min_sum:
+            min_sum = window_sum
+            best_start_idx = start_idx
+
+    best_start_time = times[best_start_idx]
+    # Turn it back into a datetime object with explicit UTC timezone
+    tz = ZoneInfo("UTC")
+    best_start_time = best_start_time.astype(datetime).replace(tzinfo=tz)
+
+    # Unused plot code to visually verify that it's working
+    if False:
+        # Convert numpy datetime array to matplotlib format
+        # If `times` is not numpy datetime64, you can skip this or adapt as needed.
+        # If `times` is a list of Python `datetime` objects, also skip the conversion step.
+        import matplotlib.pyplot as plt
+        import matplotlib.dates as mdates
+
+        fig, ax = plt.subplots(figsize=(10, 6))
+
+        # Plot the occupancy as a step or line plot
+        ax.plot(times, occupancy, label="Occupancy", drawstyle="steps-post", color="C0")
+
+        # Create a shaded region representing the best interval for the event
+        event_start = best_start_time
+        event_end = best_start_time + charging_duration
+        ax.axvspan(
+            event_start, event_end, color="C2", alpha=0.3, label="Chosen Interval"
+        )
+
+        # Format the x-axis to show date/time
+        # This only applies if your `times` are datetime objects or convertible to them
+        ax.xaxis.set_major_formatter(mdates.DateFormatter("%Y-%m-%d %H:%M:%S"))
+        plt.xticks(rotation=45, ha="right")
+
+        ax.set_xlabel("Time")
+        ax.set_ylabel("Occupancy (# of events)")
+        ax.set_title("Charger Occupancy with Chosen Event Interval")
+        ax.legend()
+        ax.grid(True)
+
+        plt.tight_layout()
+        plt.show()
+
+    return best_start_time
+
+
+def attempt_opportunity_charging_event(
+    previous_trip: Trip,
+    next_trip: Trip,
+    vehicle: Vehicle,
+    charge_start_soc: float,
+    terminus_deadtime: timedelta,
+    session: sqlalchemy.orm.session.Session,
+) -> float:
+    logger = logging.getLogger(__name__)
+
+    # Sanity checks
+    if previous_trip.route.arrival_station_id != next_trip.route.departure_station_id:
+        raise ValueError(
+            f"Trips {previous_trip.id} and {next_trip.id} are not consecutive."
+        )
+    if previous_trip.rotation_id != next_trip.rotation_id:
+        raise ValueError(
+            f"Trips {previous_trip.id} and {next_trip.id} are not in the same rotation."
+        )
+    if not (previous_trip.scenario_id == next_trip.scenario_id == vehicle.scenario_id):
+        raise ValueError(
+            f"Trips {previous_trip.id} and {next_trip.id} are not in the same scenario."
+        )
+    if not (
+        vehicle.vehicle_type.opportunity_charging_capable
+        and next_trip.rotation.allow_opportunity_charging
+        and previous_trip.route.arrival_station.is_electrified
+        and previous_trip.route.arrival_station.charge_type == ChargeType.OPPORTUNITY
+    ):
+        raise ValueError(
+            "Opportunity charging was requested even though it is not possible."
+        )
+
+    # Identify the break time between trips
+    break_time = next_trip.departure_time - previous_trip.arrival_time
+
+    if break_time > terminus_deadtime:
+        logger.debug(f"Adding opportunity charging event after trip {previous_trip.id}")
+
+        # How much energy can be charged in this time?
+        max_recharged_energy = (
+            max([v[1] for v in vehicle.vehicle_type.charging_curve])
+            * (break_time.total_seconds() - terminus_deadtime.total_seconds())
+            / 3600
+        )
+        needed_energy = (1 - charge_start_soc) * vehicle.vehicle_type.battery_capacity
+
+        if max_recharged_energy < needed_energy:
+            # We do not need to shift the time around. Just charge as much as possible
+            time_event_start = previous_trip.arrival_time
+            time_charge_start = time_event_start + terminus_deadtime / 2
+            time_charge_end = next_trip.departure_time - terminus_deadtime / 2
+            time_event_end = next_trip.departure_time
+
+            soc_event_start = charge_start_soc
+            soc_charge_start = charge_start_soc
+            soc_charge_end = (
+                charge_start_soc
+                + max_recharged_energy / vehicle.vehicle_type.battery_capacity
+            )
+            assert soc_charge_end <= 1
+            soc_event_end = soc_charge_end
+        else:
+            needed_duration_purely_charing = timedelta(
+                seconds=(
+                    ceil(
+                        needed_energy
+                        * 3600
+                        / max([v[1] for v in vehicle.vehicle_type.charging_curve])
+                    )
+                )
+            )
+            needed_duration_total = needed_duration_purely_charing + terminus_deadtime
+
+            # We have to shift the time around to the time with the lowest occupancy
+            # Within this time band.
+
+            best_start_time = find_best_timeslot(
+                previous_trip.route.arrival_station,
+                previous_trip.arrival_time,
+                next_trip.departure_time,
+                needed_duration_total,
+                session,
+            )
+            time_event_start = best_start_time
+            time_charge_start = best_start_time + terminus_deadtime / 2
+            time_charge_end = time_charge_start + needed_duration_purely_charing
+            time_event_end = time_charge_end + (terminus_deadtime / 2)
+
+            soc_event_start = charge_start_soc
+            soc_charge_start = charge_start_soc
+            soc_charge_end = 1
+            soc_event_end = 1
+
+        # Create a simple timeseries for the charging event
+        timeseries = {
+            "time": [
+                time_event_start.isoformat(),
+                time_charge_start.isoformat(),
+                time_charge_end.isoformat(),
+                time_event_end.isoformat(),
+            ],
+            "soc": [soc_event_start, soc_charge_start, soc_charge_end, soc_event_end],
+        }
+
+        # Create the charging event
+        current_event = Event(
+            scenario_id=vehicle.scenario_id,
+            vehicle_type_id=vehicle.vehicle_type_id,
+            vehicle=vehicle,
+            station_id=previous_trip.route.arrival_station_id,
+            time_start=time_event_start,
+            time_end=time_event_end,
+            soc_start=charge_start_soc,
+            soc_end=soc_event_end,
+            event_type=EventType.CHARGING_OPPORTUNITY,
+            description=f"Opportunity charging event after trip {previous_trip.id}.",
+            timeseries=timeseries,
+        )
+        session.add(current_event)
+        session.flush()
+        return soc_event_end
+
+    else:
+        logger.debug(
+            f"No opportunity charging event added after trip {previous_trip.id}"
+        )
+        return charge_start_soc

{eflips_depot-4.4.3.dist-info → eflips_depot-4.6.0.dist-info}/METADATA

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: eflips-depot
-Version: 4.4.3
+Version: 4.6.0
 Summary: Depot Simulation for eFLIPS
-Home-page: https://github.com/mpm-tu-berlin/eflips-depot
 License: AGPL-3.0-or-later
 Author: Enrico Lauth
 Author-email: enrico.lauth@tu-berlin.de
@@ -21,6 +20,7 @@ Requires-Dist: simpy (>=4.0.1,<5.0.0)
 Requires-Dist: tqdm (>=4.67.0,<5.0.0)
 Requires-Dist: xlrd (<=1.2.0)
 Requires-Dist: xlsxwriter (>=3.1.9,<4.0.0)
+Project-URL: Homepage, https://github.com/mpm-tu-berlin/eflips-depot
 Project-URL: Repository, https://github.com/mpm-tu-berlin/eflips-depot
 Description-Content-Type: text/markdown
 

{eflips_depot-4.4.3.dist-info → eflips_depot-4.6.0.dist-info}/RECORD

@@ -1,7 +1,8 @@
-eflips/depot/__init__.py,sha256=n7jte8R6j_Ad4Mp4hkklKwil5r8u8Q_SbXrCC-nf5jM,1556
-eflips/depot/api/__init__.py,sha256=b_9a248tY_U-511FVJJmPDsmyYV5VLwbEQx2mNV7Gag,45991
+eflips/depot/__init__.py,sha256=RQ_UKNrGWA6q17TZFu86ai8pC7qCpcbmAgVKh7aImwo,1613
+eflips/depot/api/__init__.py,sha256=Sxsqj5qIcSK-dqtE2UqaHVWEWnycU65N-pDnLuTJfeU,48244
 eflips/depot/api/defaults/default_settings.json,sha256=0eUDTw_rtLQFvthP8oJL93iRXlmAOravAg-4qqGMQAY,5375
 eflips/depot/api/private/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+eflips/depot/api/private/consumption.py,sha256=EbWuQnCXVXU3jAPbcig4OunZBJ6-pUCtVwPwWssjf8E,14769
 eflips/depot/api/private/depot.py,sha256=v5Edb0sQP2QNIyBLvccVzAK9_kxCszar0cOu5ciFyrw,40780
 eflips/depot/api/private/results_to_database.py,sha256=Sh2VJ3k60QJ5RGkc8sw-7XbljiMe65EHeoagKIpYlHM,24585
 eflips/depot/api/private/smart_charging.py,sha256=MQ9fXdKByHAz6RSKXYcpJXDBccdJKZ2qGReCHagVCyo,13033
@@ -36,7 +37,7 @@ eflips/depot/simulation.py,sha256=ee0qTzOzG-8ybN36ie_NJallXfC7jUaS9JZvaYFziLs,10
 eflips/depot/smart_charging.py,sha256=C3BYqzn2-OYY4ipXm0ETtavbAM9QXZMYULBpVoChf0E,54311
 eflips/depot/standalone.py,sha256=VxcTzBaB67fNJUMmjPRwKXjhqTy6oQ41Coote2LvAmk,22338
 eflips/depot/validation.py,sha256=TIuY7cQtEJI4H2VVMSuY5IIVkacEEZ67weeMuY3NSAM,7097
-eflips_depot-4.4.3.dist-info/LICENSE.md,sha256=KB4XTk1fPHjtZCYDyPyreu6h1LVJVZXYg-5vePcWZAc,34143
-eflips_depot-4.4.3.dist-info/METADATA,sha256=6tmqhHQ1mH8hj9bh5GtyjA9XNHSiFa-9b93uM_eB_pM,5928
-eflips_depot-4.4.3.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-eflips_depot-4.4.3.dist-info/RECORD,,
+eflips_depot-4.6.0.dist-info/LICENSE.md,sha256=KB4XTk1fPHjtZCYDyPyreu6h1LVJVZXYg-5vePcWZAc,34143
+eflips_depot-4.6.0.dist-info/METADATA,sha256=yWVUD74eqK640IbC6LoH_Ko0INybTuxU3KEuBqP3LjY,5940
+eflips_depot-4.6.0.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+eflips_depot-4.6.0.dist-info/RECORD,,

{eflips_depot-4.4.3.dist-info → eflips_depot-4.6.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.9.1
+Generator: poetry-core 2.0.1
 Root-Is-Purelib: true
 Tag: py3-none-any