depot.api.private.util ====================== .. py:module:: depot.api.private.util .. autoapi-nested-parse:: This module contains miscellaneous utility functions for the eflips-depot API. Classes ------- .. autoapisummary:: depot.api.private.util.VehicleSchedule Functions --------- .. autoapisummary:: depot.api.private.util.create_session depot.api.private.util.vehicle_type_to_global_constants_dict depot.api.private.util.repeat_vehicle_schedules depot.api.private.util.start_and_end_times depot.api.private.util.check_depot_validity depot.api.private.util.temperature_for_trip Module Contents --------------- .. py:function:: create_session(scenario, database_url = None) Create a valid session from various inputs. This method takes a scenario, which can be either a :class:`eflips.model.Scenario` object, an integer specifying the ID of a scenario in the database, or any other object that has an attribute `id` that is an integer. It then creates a SQLAlchemy session and returns it. If the scenario is a :class:`eflips.model.Scenario` object, the session is created and returned. If the scenario is an integer or an object with an `id` attribute, the session is created, returned and closed after the context manager is exited. :param scenario: Either a :class:`eflips.model.Scenario` object, an integer specifying the ID of a scenario in the database, or any other object that has an attribute `id` that is an integer. :return: Yield a Tuple of the session and the scenario. .. py:function:: vehicle_type_to_global_constants_dict(vt) This converts the VehicleType object into a dictionary, which is the input. format of the eflips.globalConstants object. :return: A dictionary describing some of the properties of the vehicle type. .. py:function:: repeat_vehicle_schedules(vehicle_schedules, repetition_period) This method repeats the vehicle schedules in the list `vehicle_schedules` by the timedelta `repetition_period`. It takes the given vehicle schedules and creates two copies, one `repetition_period` earlier, one `repetition_period` later. It then returns the concatenation of the three lists. :param vehicle_schedules: A list of :class:`eflips.depot.api.input.VehicleSchedule` objects. :param repetition_period: A timedelta object specifying the period of the vehicle schedules. :return: a list of :class:`eflips.depot.api.input.VehicleSchedule` objects. .. py:function:: start_and_end_times(vehicle_schedules) This method is used to find the start time and duration for simulating a given list of vehicle schedules. It finds the times of midnight of the day of the first departure and midnight of the day after the last arrival. :param vehicle_schedules: A list of :class:`eflips.depot.api.input.VehicleSchedule` objects. :return: The datetime of midnight of the day of the first departure and the total duration of the simulation in seconds. .. py:function:: check_depot_validity(depot) Check if the depot is valid for the eflips-depot simulation. Raise an AssertionError if it is not. :param depot: a :class:`eflips.model.Depot` object. :return: None .. py:function:: temperature_for_trip(trip_id, session, at_time = None, *, temperatures = None) Returns the temperature for a trip. By default this evaluates the temperature at the mid-point of the trip. Pass ``at_time`` to evaluate at a specific timestamp (e.g. a per-segment midpoint). :param trip_id: The ID of the trip :param session: The SQLAlchemy session :param at_time: Optional timestamp at which to evaluate the temperature. Must carry tzinfo. If ``None``, the trip mid-point is used. :param temperatures: Optional preloaded :class:`Temperatures` to skip the per-call query. Hot loops should hoist this lookup. :return: A temperature in °C, or ``None`` if no temperatures are recorded. .. py:class:: VehicleSchedule This class represents a vehicle schedule in eFLIPS-Depot. A vehicle schedule presents everything a vehicle does between leaving the depot and returning to the depot. In eFLIPS-Depot, we only care about a reduced set of information, limited to the interaction with the depot. .. py:attribute:: id :type: str Unique ID of this vehicle schedule. This identifier will be returned in the output of eFLIPS-Depot. .. py:attribute:: vehicle_type :type: str The vehicle type of this vehicle schedule. This is the ID of a vehicle type in the database. .. py:attribute:: departure :type: datetime.datetime The departure time of the vehicle from the depot. It *must* include the timezone information. .. py:attribute:: arrival :type: datetime.datetime The arrival time of the vehicle at the depot. It *must* include the timezone information. .. py:attribute:: departure_soc :type: float The battery state of charge (SoC) of the vehicle at the departure time. It must be in the range [0, 1]. Note that this SoC may not be ctually reached, e.g. if the vehicle is not fully charged when it leaves the depot. The depot simulation should always be run multiple times until the `departure_soc` stabilizes. .. py:attribute:: arrival_soc :type: float The battery state of charge (SoC) of the vehicles at the arrival time. It must be in the range [-inf, 1]. This value is calculated by a consumption model, e.g. the consumption model of the `ebustoolbox` package. It is a dictionary mapping vehicle types to floats. The dictionary must contain an entry for each vehicle type that is part of the `vehicle_class` of this vehicle schedule. **NOTE**: For the current API version, we only support a single vehicle type per vehicle schedule. This means that the dictionary must contain exactly one entry. .. py:attribute:: minimal_soc :type: float The minimal battery state of charge (SoC) of the vehicle during the trip. It must be in the range [-inf, 1]. This value is calculated by a consumption model, e.g. the consumption model of the `ebustoolbox` package. .. py:attribute:: opportunity_charging :type: bool Whether the vehicle is opportunity-charged (meaning charging at terminus stations) during the trip. .. py:attribute:: start_depot_id :type: str The ID of the depot where the vehicle starts its trip. .. py:attribute:: end_depot_id :type: str The ID of the depot where the vehicle ends its trip. .. py:attribute:: _is_copy :type: bool :value: False Whether this vehicle schedule is a copy of another vehicle schedule. It should not be set manually, but only by calling the :meth:`repeat` method. .. py:method:: from_rotation(rot, scenario, session) :classmethod: This constructor creates a VehicleSchedule object from a Rotation object. It is intended to be used by the eflips-depot API. :param rot: The Rotation object from which the VehicleSchedule is created. :param scenario: The Scenario object to which the Rotation belongs. :param session: The database session object. :param use_builtin_consumption_model: Whether to use the built-in consumption model of eflips-depot. If set to `True`, the `VehicleType.consumption` field is used. If set to `False`, consumption is calculated from the `Event` table in the database. This (and an external consumption model) is the recommended way. .. py:method:: _to_simple_trip(simulation_start_time, env) This converts the vehicle schedule into a :class:`eflips.depot.standalone.SimpleTrip` object, which is the. input format of the depot simulation. :param simulation_start_time: The time that serves as "zero" for the simulation. It must be before the `departure` time of the first of all vehicle schedules, probably midnight of the first day. :param env: The simulation environment object. It should be the `env` of the SimulationHost object. :return: A :class:`eflips.depot.standalone.SimpleTrip` object. .. py:method:: repeat(interval) Repeats a given VehicleSchedule. Returns a new vehicle schdule offset by a given timedelta that has the _copy_of field filled :return: A VehicleSchedule object .. py:method:: _to_timetable(vehicle_schedules, env, start_of_simulation) :staticmethod: This converts a list of VehicleSchedule objects into a :class:`eflips.depot.standalone.Timetable` object, which. is the input format of the depot simulation. This Timetable object is part of the "black box" not covered by the API documentation. :param: vehicle_schedules: A list of :class:`eflips.depot.api.input.VehicleSchedule` objects. :param: env: The simulation environment object. It should be the `env` of the SimulationHost object. :param: start_of_simulation The datetime that will be used as "zero" for the simulation. It should be before the `departure` time of the first of all vehicle schedules, probably midnight of the first day. :return: A :class:`eflips.depot.standalone.Timetable` object.