FleetState

The FleetState class is the core component that a user needs in order to setting up and running a simulation using ridepy, as described in Conceptual overview. Once the user creates a FleetState with the desired number of vehicles of appropriate capacities and initial positions, a simulation can be run by calling FleetState.simulate(), supplying iterator or requests. The FleetState advances the simulator “clock”, processes the TransportationRequest objects one by one, “moves” the vehicles so that they pick up and deliver the requests. It yields a sequence of Event objects describing what happened during the simulation.

The FleetState interface

The fleet_state module contains an abstract base class FleetState that defines the following interface, which is implemented in different inherited classes using different strategies for performing the core computations.

class FleetState(*, initial_locations, vehicle_state_class, space, dispatcher, seat_capacities)

Provides the interface for running the whole simulation. The fleet state is stored as a dictionary of (vehicle_id, VehicleState) pairs. Exposes the methods fast_forward, handle_request and simulate.

To gain maximum computational efficiency, one can:

• Subclass VehicleState and implement the main methods in Cython.

• Implement fast_forward and handle_request using distributed computing e.g. MPI

Create a FleetState, holding a number of VehicleState objects.

Parameters:

• initial_locations (Union[Dict[int, int], Dict[int, Tuple[float, ...]]]) – Dictionary with vehicle ids as keys and initial locations as values.

• vehicle_state_class (Union[Type[VehicleState], Type[CyVehicleState]]) – The vehicle state class to be used. Can be either vehicle_state.VehicleState (pure pythonic) or vehicle_state_cython.VehicleState (implemented in cython).

• space (Union[TransportSpace, CyTransportSpace]) – The data_structures.TransportSpace (e.g. Euclidean2D, Graph) in which the simulation will be run.

• dispatcher (Dispatcher) – The dispatching algorithm that maps a (stoplist, TransportationRequest) pair into a cost and new stoplist. See Introduction for more details.

• seat_capacities (Union[int, Dict[int, int]]) – Integers denoting the maximum number of persons a vehicle can hold. Either a dictionary with vehicle ids as keys or a positive integer (Causes each vehicle to have the same capacity).

Note

• Explain the graph nodes have in notes and why.

• define LocType in a central place and motivate why we have it.

classmethod from_fleet(*, fleet, space, dispatcher, validate=True)

Create a FleetState from a dictionary of VehicleState objects, keyed by an integer vehicle_id.

Parameters:

• fleet (Dict[int, VehicleState]) – Initial stoplists must contain current position element (CPE) stops with StopAction.internal and InternalRequest with request_id==-1 as their first entries.

• space (TransportSpace | TransportSpace) – TransportSpace to operate on

• dispatcher (Callable[[TransportationRequest, List[Stop], TransportSpace, int], tuple[float, List[Stop], tuple[float, float, float, float]]]) – dispatcher to use to assign requests to vehicles or reject them.

• validate (bool) – If true, try to figure out whether something is off. If not, raise.

simulate(requests, t_cutoff=inf)

Run a simulation.

Parameters:

• requests (Iterator[Request]) – Iterator that supplies incoming requests.

• t_cutoff (float) – optional cutoff time after which the simulation is forcefully ended, disregarding any remaining stops or requests.

Returns:

Iterator of events that have been emitted during the simulation.

Return type:

Iterator[ridepy.events.Event]

Note

Because of lazy evaluation the returned iterator must be exhausted for the simulation to be actually be performed.

abstract fast_forward(t)

Advance the simulator’s state in time from the previous time \(t'\) to the new time \(t\), with \(t >= t'\). E.g. vehicle locations may change and vehicle stops may be serviced. The latter will emit StopEvent s which are returned.

Parameters:

t (SupportsFloat) – Time to advance to.

Returns:

Iterator of stop events. May be empty if no stop is serviced.

Return type:

Iterator[ridepy.events.StopEvent]

handle_transportation_request(req)

Handle a request by mapping the request and the fleet state onto a request response, modifying the fleet state in-place.

This method can be implemented in child classes using various parallelization techniques like multiprocessing, OpenMPI or dask.

Parameters:

req (TransportationRequest) – Request to handle.

Returns:

An Event.

Return type:

ridepy.events.RequestEvent

abstract handle_internal_request(req)

Parameters:

req (InternalRequest) – request to handle.

Returns:

An Event.

Return type:

ridepy.events.RequestEvent

_apply_request_solution(req, all_solutions)

Given a request and a bunch of solutions, pick the one with the minimum cost and apply it, thereby changing the stoplist of the chosen vehicle and emitting an RequestAcceptanceEvent. If the minimum cost is infinite, RequestRejectionEvent is returned.

Parameters:

• req – request to handle.

• all_solutions (Iterable[ridepy.data_structures.SingleVehicleSolution]) – a dictionary mapping a vehicle_id to a SingleVehicleSolution.

Returns:

Either a RequestAcceptanceEvent, or a RequestRejectionEvent if no suitable vehicle could be found.

Return type:

ridepy.events.RequestEvent

Note

Modifies the VehicleState of the vehicle with the least cost inplace.

Different implementations of the FleetState interface

The following implementation of this base class is included:

SlowSimpleFleetState

Performs all computations in a single process without any paralllelization.

The users are of course free to implement their own subclass of FleetState in order to parallelize the core computations differently, e.g. by using job schedulers or multiprocessing.

class SlowSimpleFleetState(*, initial_locations, vehicle_state_class, space, dispatcher, seat_capacities)

Create a FleetState, holding a number of VehicleState objects.

Parameters:

• initial_locations (Union[Dict[int, int], Dict[int, Tuple[float, ...]]]) – Dictionary with vehicle ids as keys and initial locations as values.

• vehicle_state_class (Union[Type[VehicleState], Type[CyVehicleState]]) – The vehicle state class to be used. Can be either vehicle_state.VehicleState (pure pythonic) or vehicle_state_cython.VehicleState (implemented in cython).

• space (Union[TransportSpace, CyTransportSpace]) – The data_structures.TransportSpace (e.g. Euclidean2D, Graph) in which the simulation will be run.

• dispatcher (Dispatcher) – The dispatching algorithm that maps a (stoplist, TransportationRequest) pair into a cost and new stoplist. See Introduction for more details.

• seat_capacities (Union[int, Dict[int, int]]) – Integers denoting the maximum number of persons a vehicle can hold. Either a dictionary with vehicle ids as keys or a positive integer (Causes each vehicle to have the same capacity).

Note

• Explain the graph nodes have in notes and why.

• define LocType in a central place and motivate why we have it.