:py:mod:`starling_sim.basemodel.agent.operators.operator` ========================================================= .. py:module:: starling_sim.basemodel.agent.operators.operator Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: starling_sim.basemodel.agent.operators.operator.Operator .. py:class:: 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: :py:obj:`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. .. py:property:: servicePoints Return a dict mapping both stop points and depot points. .. py:attribute:: OPERATION_PARAMETERS_SCHEMA .. py:attribute:: SCHEMA .. py:attribute:: DISPATCHERS .. py:method:: get_schema() :classmethod: Compute and return the class parameters schema. This is the place to add eventual schema post-processing :return: class schema .. py:method:: compute_schema() :classmethod: 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. :return: json schema of the class init parameters .. py:method:: 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. :param operation_parameters: dict of operational parameters .. py:method:: init_service_info() Import and initialise the data structures containing service information and line shapes. .. py:method:: init_line_shapes() Set the service lines shapes file according to the dedicated parameter. .. py:method:: 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. :param zone_polygon: list of points describing a polygon .. py:method:: 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. :param depot_points: { id, coordinates, name } information dict .. py:method:: init_stops(stop_points_from) Initialise the stopPoints attribute using the provided method. .. py:method:: _stops_table_from_geojson(filename) Create a stops table from the provided GeoJSON input filename. :param filename: input filename (*.geojson) :return: stops table .. py:method:: _stops_table_from_gtfs() Create a stops table from the operator's GTFS (service_info). :return: stops table .. py:method:: _trips_table_from_gtfs() -> pandas.DataFrame Evaluate a table of trips with their first stop time. An additional "arrival_time_num" column is added, containing arrival times in seconds. :return: DataFrame of trips and stop times, sorted by arrival_time .. py:method:: 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. :param stops_table: gtfs-like DataFrame :param id_prefix: prefix to add to stop ids .. py:method:: 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. :param stop_point_id: new stop id :param stop_point_position: new stop position :param stop_point_name: new stop name :param allow_existing: allow existence of a stop point with same id :param is_depot: indicates if new stop point is a depot :return: corresponding StopPoint object .. py:method:: init_trips() Initialise the trips attribute using simulation data. .. py:method:: 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 _T. :param agent: agent realising the trip, or None if the agent is not known yet :param planning: planning of the trip :param trip_id: id of the trip, or None :return: id of the trip .. py:method:: position_in_zone(position) Test if the given position belongs to the service zone. The method returns (the operator) if the position is in the service zone, and None otherwise. :param position: topology node :return: either self (operator), if in zone, or None otherwise .. py:method:: init_dispatchers() Initialise the punctual_dispatcher and online_dispatcher attributes. .. py:method:: dispatcher_parameters() .. py:method:: 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$" :param agent: requesting agent :param number: number of seats requested :return: Request object .. py:method:: 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. :param agent: :param number: :param pickup_position: :param dropoff_position: :param pickup_request_time: :param dropoff_request_time: :param pickup_max_time: :param dropoff_max_time: :param pickup_stop_point: :param dropoff_stop_point: :param direct_travel_time: :param max_travel_time: :param trip_id: :return: .. py:method:: 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. :param request: .. py:method:: 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. :param request: cancelled request .. py:method:: 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 . :param agent: agent making the trip request :param number: number of seats requested :param origin_position: trip origin position in environment :param origin_stop: trip origin stop id :param origin_time: trip origin time :param destination_position: trip destination position in environment :param destination_stop: trip destination stop id :param destination_time: trip destination time :param kwargs: other eventual parameters :return: TripRequest completed with trip information set .. py:method:: 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. :param agent: Agent object :return: yield a process describing an idle behaviour .. py:method:: new_service_vehicle(feature) Create and initialise a new service vehicle using the model's dynamic input :param feature: dictionary containing the service vehicle information :return: newly generated ServiceVehicle .. py:method:: 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. :param base_time: base for the evaluation of the time window :param time_window: time window width :return: (time window_end, time_window_end) tuple .. py:method:: compute_max_travel_time(direct_travel_time: int) -> Union[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" :param direct_travel_time: value of the direct travel time (int) :return: value of the maximum travel time (int) or None if no constraint is applied :raises: ValueError if the evaluation of the formula fails