Package util

The module contains some utility functions and classes.

The dispatchers

The spaces

class Euclidean(n_dim=1, coord_range=None, velocity=1)[source]

n-dimensional Euclidean space with constant velocity.

Initialize n-dimensional Euclidean space with constant velocity.

Parameters:

  • n_dim (int) – number of dimensions

  • coord_range (List[Tuple[int | float, int | float]]) – coordinate range of the space as a list of 2-tuples (x_i,min, x_i,max) where x_i represents the ith dimension.

  • velocity (float) – constant scaling factor as discriminator between distance and travel time

class Manhattan2D(coord_range=None, velocity=1)[source]

\(\mathbb{R}^2\) with \(L_1\)-induced metric (Manhattan).

Parameters:

  • coord_range (List[Tuple[int | float, int | float]]) – coordinate range of the space as a list of 2-tuples (x_i,min, x_i,max) where x_i represents the ith dimension.

  • velocity (float) – constant scaling factor as discriminator between distance and travel time

class Graph(vertices, edges, weights=None, velocity=1)[source]

A location is identified with a one-dimensional coordinate, namely the node index.

Weighted undirected graph with integer vertex labels

Parameters:

  • vertices (Sequence[int]) – sequence of vertices

  • edges (Sequence[Tuple[int, int]]) – sequence of edge tuples

  • weights (None | float | Sequence[float]) – Edge weights. - if None is supplied, the resulting graph is unweighted (unit edge length) - if a single float is supplied, every edge length will be equal to this number - if a sequence is supplied, this will be mapped onto the edge sequence

  • velocity (float) – constant velocity to compute travel time, optional.

static _make_attribute_distance(G, attribute_name)[source]

Set the distance attribute on the edges of the graph inplace.

Parameters:

  • G – The graph to modify

  • attribute_name (str | None) – The name of the attribute to use as distance. If None, the distance will be set to 1 for each edge.

classmethod from_nx(G, velocity=1, make_attribute_distance='distance')[source]

Create a graph space from NetworkX graph.

Parameters:

  • G (Graph) – the networkx.Graph instance, will be deepcopied

  • velocity (float) – velocity to use for travel time computation

  • make_attribute_distance (str) – attribute to rename to “distance” and use as such If None is supplied, the resulting graph is unweighted (unit edge length).

Returns:

graph space instance

interp_dist(u, v, dist_to_dest)[source]
Parameters:

  • u

  • v

  • dist_to_dest

Returns:

  • next_node

  • jump_distance

interp_time(u, v, time_to_dest)[source]
Parameters:

  • u

  • v

  • time_to_dest

Returns:

  • next_node

  • jump_time

The request generators

class RandomRequestGenerator(*, space, rate=1, seed=42, pickup_timewindow_offset=0, request_class=<class 'ridepy.data_structures.TransportationRequest'>, max_pickup_delay=inf, max_delivery_delay_abs=inf, max_delivery_delay_rel=inf)[source]

Generates random requests in the chosen transport space with a certain rate. The timewindows for the request are configurable.

Note:
The pickup and dropoff timewindows are calculated as follows:

  1. request_pickup_time < request.creation_timestamp + max_pickup_delay

  2. request_delivery_time < request.creation_timestamp + direct_travel_time + max_delivery_delay_abs

  3. request_delivery_time < request.creation_timestamp + direct_travel_time*(1+max_delivery_delay_rel)

Parameters:

  • space (TransportSpace) – the TransportSpace in which the requests will be generated.

  • rate – the rate of requests per time unit

  • seed – the random seed

  • request_class – the generated requests will be instances of this class. Needed to generate pythonic or cythonic requests at will.

  • pickup_timewindow_offset – Each request’s pickup_timewindow_min will be this much from the creation timestamp.

  • max_pickup_delay (float) – The maximum delay between the request creation timestamp and the pickup time.

  • max_delivery_delay_abs (float) – The maximum absolute delay between the request creation timestamp and the delivery time.

  • max_delivery_delay_rel (float) – The maximum delay between the request creation timestamp and the delivery time relative to the direct actual direct travel time. Example: if the direct travel time is 10 minutes and max_delivery_delay_rel is 0.5, the delivery time will be at most 15 minutes after request creation. I.e., delta_max = 1 + max_delivery_delay_rel.

The analytics package

get_stops_and_requests(*, events, space)[source]

Prepare two DataFrames, containing stops and requests.

# NOTE: This assumes occupancy delta of +1/-1, i.e. only single-customer requests. # If the simulator should allow for multi-customer requests in the future, # this must be changed. # See also [issue #45](https://github.com/PhysicsOfMobility/ridepy/issues/45)

The stops DataFrame returned has the following schema:

Column                                       Dtype
------                                       -----
vehicle_id                                 float64
stop_id                                      int64
timestamp                                  float64
delta_occupancy                            float64
request_id                                   int64
state_duration                             float64
occupancy                                  float64
location                                    object
dist_to_next                               float64
time_to_next                               float64
timestamp_submitted                        float64
insertion_index                            float64
leg_1_dist_service_time                    float64
leg_2_dist_service_time                    float64
leg_direct_dist_service_time               float64
detour_dist_service_time                   float64
leg_1_dist_submission_time                 float64
leg_2_dist_submission_time                 float64
leg_direct_dist_submission_time            float64
detour_dist_submission_time                float64
stoplist_length_submission_time            float64
stoplist_length_service_time               float64
avg_segment_dist_submission_time           float64
avg_segment_time_submission_time           float64
avg_segment_dist_service_time              float64
avg_segment_time_service_time              float64
system_stoplist_length_submission_time     float64
system_stoplist_length_service_time        float64
avg_system_segment_dist_submission_time    float64
avg_system_segment_time_submission_time    float64
avg_system_segment_dist_service_time       float64
avg_system_segment_time_service_time       float64
relative_insertion_position                float6

The requests DataFrame returned has the following schema:

Column                               Dtype
------                               -----
(submitted, timestamp)                float64
(submitted, origin)                   Union[float64, int, Tuple[float64]]
(submitted, destination)              Union[float64, int, Tuple[float64]]
(submitted, pickup_timewindow_min)    float64
(submitted, pickup_timewindow_max)    float64
(submitted, delivery_timewindow_min)  float64
(submitted, delivery_timewindow_max)  float64
(submitted, direct_travel_distance)   float64
(submitted, direct_travel_time)       float64
(accepted, timestamp)                 float64
(accepted, origin)                    Union[float64, int, Tuple[float64]]
(accepted, destination)               Union[float64, int, Tuple[float64]]
(accepted, pickup_timewindow_min)     float64
(accepted, pickup_timewindow_max)     float64
(accepted, delivery_timewindow_min)   float64
(accepted, delivery_timewindow_max)   float64
(rejected, timestamp)                 float64
(inferred, relative_travel_time)      float64
(inferred, travel_time)               float64
(inferred, waiting_time)              float64
(serviced, timestamp_dropoff)         float64
(serviced, timestamp_pickup)          float64
(serviced, vehicle_id)                float64
Parameters:

  • events (List[dict]) – list of all the events returned by the simulation

  • space (TransportSpace) – transportation space that was used for the simulations

Returns:

  • stops – dataframe indexed by [vehicle_id, timestamp] containing all stops

  • requests – dataframe indexed by request_id containing all requests

Return type:

tuple[DataFrame, DataFrame]

get_stops_and_requests_from_events_dataframe(*, events_df, space)[source]

Prepare stops and requests dataframes from an events dataframe. For details on the returned dataframes see doc on outside-facing get_stops_and_requests.

Parameters:
Returns:

  • stops – dataframe indexed by [vehicle_id, timestamp] containing all stops

  • requests – dataframe indexed by request_id containing all requests

Return type:

tuple[DataFrame, DataFrame]

get_vehicle_quantities(stops, requests)[source]

Compute various quantities aggregated per vehicle.

Currently, the following observables are returned:

  • avg_occupancy

  • avg_segment_dist

  • avg_segment_time

  • total_dist_driven

  • total_time_driven

  • avg_direct_dist

  • avg_direct_time

  • total_direct_dist

  • total_direct_time

  • efficiency_dist

  • efficiency_time

  • avg_system_stoplist_length_service_time

  • avg_system_stoplist_length_submission_time

  • avg_stoplist_length_service_time

  • avg_stoplist_length_submission_time

Parameters:

  • stops (DataFrame) – Stops dataframe

  • requests (DataFrame) – Requests dataframe

Returns:

pd.DataFrame containing the aforementioned observables as columns, indexed by vehicle_id

Return type:

DataFrame

get_system_quantities(stops, requests, params=None)[source]

Compute various quantities aggregated for the entire simulation.

Currently, the following observables are returned (quantities in parentheses may not be returned if params is not given/stops does not contain the respective quantities):

  • (n_vehicles) – number of vehicles (simulation parameter)

  • (request_rate) – request rate (simulation parameter)

  • (velocity) – vehicle velocity (simulation parameter)

  • (load_requested) – load requested (derived from request rate, velocity, and number of vehicles as input parameters and the spaces’ average distance)

  • (load_serviced) – load requested (derived from request rate times (1-rejection ratio), velocity, and number of vehicles as input parameters and the spaces’ average distance)

  • (avg_direct_dist_space) – average direct distance in space, computed by taking 1e5 random samples

  • avg_occupancy

  • avg_segment_dist

  • avg_segment_time

  • total_dist_driven

  • total_time_driven

  • avg_direct_dist

  • avg_direct_time

  • total_direct_dist

  • total_direct_time

  • efficiency_dist

  • efficiency_time

  • avg_waiting_time

  • rejection_ratio

  • median_stoplist_length – median per-vehicle stoplist length, taken over all “stoplist states” (vehicles x time)

  • median_stoplist_length – median per-vehicle stoplist length, taken over all “stoplist states” (vehicles x time)

  • mean_system_stoplist_length – arithmetic mean system-wide stoplist length, taken over all “stoplist states” (time)

  • mean_system_stoplist_length – arithmetic mean system-wide stoplist length, taken over all “stoplist states” (time)

  • avg_detour

  • (avg_system_stoplist_length_service_time)

  • (avg_system_stoplist_length_submission_time)

  • (avg_stoplist_length_service_time)

  • (avg_stoplist_length_submission_time)

Parameters:

  • stops (DataFrame) – Stops dataframe

  • requests (DataFrame) – Requests dataframe

  • params (dict[str, dict[str, Any]] | None) – Optional, adds more data (the fields in parentheses) to the result for convenience purposes

Returns:

system_quantities – dict containing the aforementioned observables

Return type:

dict[str, int | float]