depot.api.private.util

This module contains miscellaneous utility functions for the eflips-depot API.

Classes

VehicleSchedule

This class represents a vehicle schedule in eFLIPS-Depot.

Functions

create_session(scenario[, database_url])	Create a valid session from various inputs.
vehicle_type_to_global_constants_dict(vt)	This converts the VehicleType object into a dictionary, which is the input.
repeat_vehicle_schedules(vehicle_schedules, ...)	This method repeats the vehicle schedules in the list vehicle_schedules by the timedelta repetition_period.
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.
check_depot_validity(depot)	Check if the depot is valid for the eflips-depot simulation.
temperature_for_trip(trip_id, session[, at_time, ...])	Returns the temperature for a trip.

Module Contents

depot.api.private.util.create_session(scenario, database_url=None)

Create a valid session from various inputs.

This method takes a scenario, which can be either a 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 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.

Parameters:

• scenario (Union[eflips.model.Scenario, int, Any]) – Either a 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.

• database_url (Optional[str])

Returns:

Yield a Tuple of the session and the scenario.

Return type:

Tuple[sqlalchemy.orm.Session, eflips.model.Scenario]

depot.api.private.util.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.

Returns:

A dictionary describing some of the properties of the vehicle type.

Parameters:

vt (eflips.model.VehicleType)

Return type:

Dict[str, float]

depot.api.private.util.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.

Parameters:

• vehicle_schedules (List[VehicleSchedule]) – A list of eflips.depot.api.input.VehicleSchedule objects.

• repetition_period (datetime.timedelta) – A timedelta object specifying the period of the vehicle schedules.

Returns:

a list of eflips.depot.api.input.VehicleSchedule objects.

Return type:

List[VehicleSchedule]

depot.api.private.util.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.

Parameters:

vehicle_schedules – A list of eflips.depot.api.input.VehicleSchedule objects.

Returns:

The datetime of midnight of the day of the first departure and the total duration of the simulation in seconds.

Return type:

Tuple[datetime.datetime, int]

depot.api.private.util.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 eflips.model.Depot object. :return: None

Parameters:

depot (eflips.model.Depot)

Return type:

None

depot.api.private.util.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).

Parameters:

• trip_id (int) – The ID of the trip

• session (sqlalchemy.orm.Session) – The SQLAlchemy session

• at_time (Optional[datetime.datetime]) – Optional timestamp at which to evaluate the temperature. Must carry tzinfo. If None, the trip mid-point is used.

• temperatures (Optional[eflips.model.Temperatures]) – Optional preloaded Temperatures to skip the per-call query. Hot loops should hoist this lookup.

Returns:

A temperature in °C, or None if no temperatures are recorded.

Return type:

Optional[float]

class depot.api.private.util.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.

id: str

Unique ID of this vehicle schedule.

This identifier will be returned in the output of eFLIPS-Depot.

vehicle_type: str

The vehicle type of this vehicle schedule.

This is the ID of a vehicle type in the database.

departure: datetime.datetime

The departure time of the vehicle from the depot.

It must include the timezone information.

arrival: datetime.datetime

The arrival time of the vehicle at the depot.

It must include the timezone information.

departure_soc: 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.

arrival_soc: 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.

minimal_soc: 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.

opportunity_charging: bool

Whether the vehicle is opportunity-charged (meaning charging at terminus stations) during the trip.

start_depot_id: str

The ID of the depot where the vehicle starts its trip.

end_depot_id: str

The ID of the depot where the vehicle ends its trip.

_is_copy: bool = False

Whether this vehicle schedule is a copy of another vehicle schedule.

It should not be set manually, but only by calling the repeat() method.

classmethod from_rotation(rot, scenario, session)

This constructor creates a VehicleSchedule object from a Rotation object.

It is intended to be used by the eflips-depot API.

Parameters:

• rot (eflips.model.Rotation) – The Rotation object from which the VehicleSchedule is created.

• scenario – The Scenario object to which the Rotation belongs.

• session – The database session object.

• 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.

_to_simple_trip(simulation_start_time, env)

This converts the vehicle schedule into a eflips.depot.standalone.SimpleTrip object, which is the.

input format of the depot simulation.

Parameters:

• simulation_start_time (datetime.datetime) – 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.

• env (simpy.Environment) – The simulation environment object. It should be the env of the SimulationHost object.

Returns:

A eflips.depot.standalone.SimpleTrip object.

Return type:

eflips.depot.SimpleTrip

repeat(interval)

Repeats a given VehicleSchedule.

Returns a new vehicle schdule offset by a given timedelta that has the _copy_of field filled

Returns:

A VehicleSchedule object

Parameters:

interval (datetime.timedelta)

Return type:

VehicleSchedule

static _to_timetable(vehicle_schedules, env, start_of_simulation)

This converts a list of VehicleSchedule objects into a 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 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.

Returns:

A eflips.depot.standalone.Timetable object.

Parameters:

• vehicle_schedules (List[VehicleSchedule])

• env (simpy.Environment)

• start_of_simulation (datetime.datetime)

Return type:

eflips.depot.Timetable