depot.api ========= .. py:module:: depot.api .. autoapi-nested-parse:: This package contains the public API for eFLIPS-Depot. It is to be used in conjunction with the `eflips.model `_ package, where the Scenario is defined. Notes on the usage of the API ----------------------------- The following steps are recommended for using the API: 1. Check if there are already "driving events" in the database. They come from a "consumption simulation" and are associated with a vehicle. If there are no driving events, you may use the :func:`simple_consumption_simulation` (with ``initialize_vehicles=True``) to create them. This function will also initialize the vehicles in the database with the correct vehicle type and assign them to rotations. 2. Check if there is already a depot layout in the database. If there is not, you may use the :func:`generate_depot_layout` function to create a simple depot layout and plan. 3. Either use the :func:`simulate_scenario` function to run the whole simulation in one go, or use the following steps: a. Use the :func:`init_simulation` function to create a simulation host, which is a "black box" object containing all input data for the simulation. b. Use the :func:`run_simulation` function to run the simulation and obtain the results. c. Use the :func:`add_evaluation_to_database` function to add the results to the database. 4. For the results to be valid, the consumption simulation should now be run again. a. If you are using an external consumption model, run it again making sure it does not create new vehicles. b. Run the :func:`simple_consumption_simulation` function again, this time with ``initialize_vehicles=False``. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/depot/api/private/index Classes ------- .. autoapisummary:: depot.api.SmartChargingStrategy Functions --------- .. autoapisummary:: depot.api.generate_consumption_result depot.api.simple_consumption_simulation depot.api.generate_depot_layout depot.api.apply_even_smart_charging depot.api.simulate_scenario depot.api.init_simulation depot.api.run_simulation depot.api.insert_dummy_standby_departure_events depot.api.add_evaluation_to_database depot.api.generate_depot_optimal_size depot.api.schedule_duration_days Package Contents ---------------- .. py:class:: SmartChargingStrategy(*args, **kwds) Bases: :py:obj:`enum.Enum` Enum class for different smart charging strategies. .. py:attribute:: NONE :value: 0 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). .. py:attribute:: EVEN :value: 1 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. .. py:attribute:: MIN_PRICE :value: 2 Use smart charging in order to minimize the cost of charging. The price profile can be specified using the PRICE_PROFILE environment variable. If this is not set, the price is loaded using an API. .. py:function:: generate_consumption_result(scenario) Generate consumption information for the scenario. This function retrieves the consumption LUT and vehicle classes from the database and returns a dictionary containing the consumption information for each vehicle type in the scenario. If a trip has no corresponding consumption LUT, it won't be included in the results. :param scenario: A :class:`eflips.model.Scenario` object containing the input data for the simulation. :return: A dictionary containing the consumption information for each vehicle type in the scenario. .. py:function:: simple_consumption_simulation(scenario, initialize_vehicles, database_url = None, calculate_timeseries = False, terminus_deadtime = timedelta(minutes=1), consumption_result = None) 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``. .. py:function:: generate_depot_layout(scenario, charging_power = 90, database_url = None, delete_existing_depot = False) Generates one or more depots for the scenario. First, the rotations are scanned to identify all the spots that serve as start *and* end of a rotation. Then the set of rotations for these spots are checked for vehicle types that are used there. Next, the amount of vehicles that are simultaneously present at the depot is calculated. Then a depot layout with an arrival and a charging area for each vehicle type is created. The capacity of each area is taken from the calculated amount of vehicles. The depot layout is then added to the database. A default plan will also be generated, which includes the following default processes: standby_arrival, cleaning, charging and standby_departure. Each vehicle will be processed with this exact order (standby_arrival is optional because it only happens if a vehicle needs to wait for the next process). The function only deletes the depot if the `delete_existing_depot` parameter is set to True. If there is already a depot existing in this scenario and this parameter is set to False, a ValueError will be 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 valid database URL. :param charging_power: the charging power of the charging area in kW :param delete_existing_depot: if there is already a depot existing in this scenario, set True to delete this existing depot. Set to False and a ValueError will be raised if there is a depot in this scenario. :return: None. The depot layout will be added to the database. .. py:function:: apply_even_smart_charging(scenario, database_url = None, standby_departure_duration = timedelta(minutes=5)) Takes a scenario where depot simulation has been run and applies smart charging to the depot. This modifies the time and power of the charging events in the database. The arrival and departure times and SoCs at these times are not modified. :param scenario: A :class:`eflips.model.Scenario` object containing the input data for the simulation. :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 standby_departure_duration: The duration of the STANDBY_DEPARTURE event. This is the time the vehicle is allowed to wait at the depot before it has to leave. The default is 5 minutes. :return: None. The results are added to the database. .. py:function:: simulate_scenario(scenario, repetition_period = None, database_url = None, smart_charging_strategy = SmartChargingStrategy.NONE, ignore_unstable_simulation = False, ignore_delayed_trips = False) 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. 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 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 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. :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 smart_charging_strategy: An optional parameter specifying the smart charging strategy to be used. The 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). - 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. :param ignore_delayed_trips: If True, the simulation will not raise an exception if there are delayed trips. :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. :raises DelayedTripException: If there are delayed trips in the simulation. .. py:function:: init_simulation(scenario, session, repetition_period = None, vehicle_count_dict = None) This methods checks the input data for consistency, initializes a simulation host object and returns it. The simulation host object can then be passed to :func:`run_simulation()`. :param scenario: A :class:`eflips.model.Scenario` object containing the input data for the simulation. :param session: A SQLAlchemy session object. :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 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. :param vehicle_count_dict: An optional dictionary specifying the number of vehicles for each vehicle type for each depot. The dictionary should have the following structure: :: { "1" (depot.id as str): { "1" (vehicle_type.id as str): 10, "2" (vehicle_type.id as str): 20, ... }, "2" (depot.id as str): { "1" (vehicle_type.id as str): 10, "2" (vehicle_type.id as str): 20, ... }, :return: A :class:`eflips.depot.Simulation.SimulationHost` object. This object should be reagrded as a "black box" by the user. It should be passed to :func:`run_simulation()` to run the simulation and obtain the results. .. py:function:: run_simulation(simulation_host) Run simulation and return simulation results. :param simulation_host: A "black box" object containing all input data for the simulation. :return: A dictionary of :class:`eflips.depot.evaluation.DepotEvaluation` objects. The keys are the depot IDs, as strings. .. py:function:: insert_dummy_standby_departure_events(depot_id, session, sim_time_end = None) Workaround for the missing STANDBY_DEPARTURE events in the database. :param session: The database session :param scenario: A scenario object :param sim_time_end: The end time of the simulation. If None, final events might not be properly handled. :return: .. py:function:: add_evaluation_to_database(scenario, depot_evaluations, session) This method adds a simulation result to the database. It reads the simulation results from the :class:`eflips.depot.evaluation.DepotEvaluation` object and adds them into the database. Tables of Event, Rotation and Vehicle will be updated. :param scenario: A :class:`eflips.model.Scenario` object containing the input data for the simulation. :param depot_evaluations: A dictionary of :class:`eflips.depot.evaluation.DepotEvaluation` objects. The keys are the depot IDs, as strings. :param session: a SQLAlchemy session object. This is used to add all the simulation results to the 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. :raises DelayedTripException: If there are delayed trips in the simulation. .. py:function:: generate_depot_optimal_size(scenario, standard_block_length = 6, charging_power = 90, database_url = None, delete_existing_depot = False, use_consumption_lut = False, repetition_period = None) Generates an optimal depot layout with the smallest possible size for each depot in the scenario. Line charging areas with given block length area preferred. The existing depot will be deleted if `delete_existing_depot` is set to True. :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" containing an integer pointing to a unique scenario id. :param standard_block_length: The standard block length for the depot layout in meters. Default is 6. :param charging_power: The charging power of the charging area in kW. Default is 90. :param database_url: An optional database URL. Used if no database url is given by the environment variable. :param delete_existing_depot: If there is already a depot existing in this scenario, set True to delete this existing depot. Set to False and a ValueError will be raised if there is a depot in this scenario. :param use_consumption_lut: If True, the depot layout will be generated based on the consumption lookup table. If False, constant consumption stored in VehicleType table will be used. :param repetition_period: An optional timedelta object specifying the period of the vehicle schedules. If not specified, a default repetition period will be generated in simulate_scenario(). If the depot layout generated in this function will be used for further simulations, make sure that the repetition period is set to the same value as in the simulation. :return: None. The depot layout will be added to the database. .. py:function:: schedule_duration_days(scenario, database_url = None) This method calculates the duration of a given scenario in days. This is the duration between the first departure of the first day, and the last departure on the last day, rounded up to full days. Most of the time, this is the "natural" repetition period of the scenario. We are simulating one full period, and this period – continuously repeated – is what happens in reality. This method can be used to show the user what the detected repetition period is and to auto-set the repetition period if none is provided. :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" containing an integer pointing to a unique scenario id. :param database_url: An optional database URL. Used if no database url is given by the environment variable. :return: a timedelta object representing the duration in days.