starling_sim.basemodel.agent.operators.operator

Module Contents

Classes

Operator

Class describing an operator of a transport service.
class starling_sim.basemodel.agent.operators.operator.Operator(simulation_model, agent_id, fleet_dict, mode=None, staff_dict=None, depot_points=None, stop_points_from=None, extend_graph_with_stops=False, zone_polygon=None, operation_parameters=None, **kwargs)

Bases: starling_sim.basemodel.agent.agent.Agent

Class describing an operator of a transport service.

Operators manage a fleet of vehicle, and receive requests for the service they provide.

The assignment of these requests is managed by a Dispatcher object.

property servicePoints

Return a dict mapping both stop points and depot points.

OPERATION_PARAMETERS_SCHEMA
SCHEMA
DISPATCHERS
classmethod get_schema()

Compute and return the class parameters schema.

This is the place to add eventual schema post-processing

Returns:

class schema

classmethod compute_schema()

Get the json schema that specifies the class init parameters.

The schema is generated recursively, by adding/mixing the properties of the current class to the schema of its parent class.

Returns:

json schema of the class init parameters

init_operation_parameters(operation_parameters)

Initialise the operation parameters of the operator.

If the class attribute OPERATION_PARAMETERS_SCHEMA is provided, it is used to validate the given parameters and set default values if needed.

Parameters:

operation_parameters – dict of operational parameters

init_service_info()

Import and initialise the data structures containing service information and line shapes.

init_line_shapes()

Set the service lines shapes file according to the dedicated parameter.

init_zone(zone_polygon)

Set the operator service zone according to the given polygon.

The service zone is described by a GeoDataFrame containing a shapely Polygon.

Parameters:

zone_polygon – list of points describing a polygon

init_depot_points(depot_points)

Initialise the depotPoints attribute using the given depots information.

Depot points are StopPoint instances but are stored in a separate attribute named depotPoints.

Parameters:

depot_points – { id, coordinates, name } information dict

init_stops(stop_points_from)

Initialise the stopPoints attribute using the provided method.

_stops_table_from_geojson(filename)

Create a stops table from the provided GeoJSON input filename.

Parameters:

filename – input filename (*.geojson)

Returns:

stops table

_stops_table_from_gtfs()

Create a stops table from the operator’s GTFS (service_info).

Returns:

stops table

add_stops(stops_table, id_prefix='')

Add the sequence of stops to the stopPoints dict.

The stops table is a gtfs-like DataFrame, with the columns “stop_id” and “stop_name”. The method also uses the ‘stop_correspondence_file”, which links service stops to topology positions.

Parameters:

  • stops_table – gtfs-like DataFrame

  • id_prefix – prefix to add to stop ids

new_stop_point(stop_point_position, stop_point_id, stop_point_name=None, allow_existing=True, is_depot=False)

Create or get existing StopPoint and add it to the operator stop points.

Parameters:

  • stop_point_id – new stop id

  • stop_point_position – new stop position

  • stop_point_name – new stop name

  • allow_existing – allow existence of a stop point with same id

  • is_depot – indicates if new stop point is a depot

Returns:

corresponding StopPoint object

init_trips()

Initialise the trips attribute using simulation data.

add_trip(agent, planning, trip_id=None)

Add a new trip to the trips dict.

Associate the trip_id to the agent that realises the trip and the planning that describes the trip.

The default trip id built as <self.id>_T<self.tripCount>.

Parameters:

  • agent – agent realising the trip, or None if the agent is not known yet

  • planning – planning of the trip

  • trip_id – id of the trip, or None

Returns:

id of the trip

position_in_zone(position)

Test if the given position belongs to the service zone.

The method returns <self> (the operator) if the position is in the service zone, and None otherwise.

Parameters:

position – topology node

Returns:

either self (operator), if in zone, or None otherwise

init_dispatchers()

Initialise the punctual_dispatcher and online_dispatcher attributes.

dispatcher_parameters()
new_request(agent, number)

Create a new request object to the operator, and return it to the requesting agent.

In the basic Operator’s method, the request object is a TripRequest, the event is a simple SimPy event, and the request id looks like “R$self.request_count$”

Parameters:

  • agent – requesting agent

  • number – number of seats requested

Returns:

Request object

create_trip_request(agent, number, pickup_position, dropoff_position, pickup_request_time, dropoff_request_time=None, pickup_max_time=None, dropoff_max_time=None, pickup_stop_point=None, dropoff_stop_point=None, direct_travel_time=None, max_travel_time=None, trip_id=None)

Create a TripRequest object containing the given trip constraints.

Parameters:

  • agent –

  • number –

  • pickup_position –

  • dropoff_position –

  • pickup_request_time –

  • dropoff_request_time –

  • pickup_max_time –

  • dropoff_max_time –

  • pickup_stop_point –

  • dropoff_stop_point –

  • direct_travel_time –

  • max_travel_time –

  • trip_id –

Returns:

assign_request(request)

Assign the given request to an agent of the fleet

Call the dispatch algorithm in order to assign a vehicle to the given request, and signal the schedule change to the chosen vehicle.

Parameters:

request –

cancel_request(request)

Remove the pending queues of the given assigned request.

For instance, remove the UserStop objects from the stop points lists.

Called when a request is canceled by the requesting user or the operator.

Parameters:

request – cancelled request

build_trip_request(number, agent=None, origin_position=None, origin_stop=None, origin_time=None, destination_position=None, destination_stop=None, destination_time=None, **kwargs)

Build a request for a trip with the operator service from the given information.

Depending on the operator, all parameters may not be necessary, and others mays be added .

Parameters:

  • agent – agent making the trip request

  • number – number of seats requested

  • origin_position – trip origin position in environment

  • origin_stop – trip origin stop id

  • origin_time – trip origin time

  • destination_position – trip destination position in environment

  • destination_stop – trip destination stop id

  • destination_time – trip destination time

  • kwargs – other eventual parameters

Returns:

TripRequest completed with trip information set

idle_behaviour_(agent)

Perform an idle behaviour.

This method is called when an agent of the operator’s fleet is idle. The agent then executes the behaviour until it is interrupted. The default behaviour is to wait indefinitely.

Parameters:

agent – Agent object

Returns:

yield a process describing an idle behaviour

new_service_vehicle(feature)

Create and initialise a new service vehicle using the model’s dynamic input

Parameters:

feature – dictionary containing the service vehicle information

Returns:

newly generated ServiceVehicle

evaluate_time_window(base_time: int, time_window: int)

Evaluate a time window from the reference and the time window width.

If the time window width is negative, the reference time is the upper bound, and the lower bound is evaluated.

Parameters:

  • base_time – base for the evaluation of the time window

  • time_window – time window width

Returns:

(time window_end, time_window_end) tuple

compute_max_travel_time(direct_travel_time: int) → int | None

Evaluate the max travel time formula to get a maximum travel time value [seconds].

The formula is a Python expression, evaluated using the builtin eval function. It can use the direct travel time value by using the following placeholder: {direct_travel_time} It must return something that can be cast or rounded using int().

Examples (without the brackets):

  • “{direct_travel_time} * 1.5”

  • “{direct_travel_time} + 900”

  • “1800”

Parameters:

direct_travel_time – value of the direct travel time (int)

Returns:

value of the maximum travel time (int) or None if no constraint is applied

Raises:

ValueError if the evaluation of the formula fails