Module Contents



Describes an environment in which the simulation will take place

class starling_sim.basemodel.environment.environment.Environment(scenario, network='osm')

Describes an environment in which the simulation will take place


Setup the environment for the simulation run.

Set the simulation model attribute and prepare the environment for the simulation


simulation_model – simulation model

compute_route_data(route, duration, origin, destination, parameters, mode)

Compute a route data from the given parameters

  • route – list of consecutive nodes in the environment. If None, a shortest path from <origin> to <destination> is computed

  • duration – total duration of the route execution. If None, use the “time” links of the environment

  • origin – origin used for the shortest path computation

  • destination – destination used for the shortest path computation

  • parameters – agent specific parameters used for path evaluation

  • mode – mode of the move


route_data={“route”: position_list, “length”: length_list, “time”: time_list}

add_route_data(route_data, mode, data, speed=None)

Complete the given route_data with the relevant list

  • route_data – route_data to be completed

  • mode – mode of the move

  • data – type of data to add, either “length” or “time”

  • speed – speed of the move, used for “time” data. If None, use the links’ speeds

compute_shaped_route(operator, shape_table, from_stop, to_stop, duration)
static get_position(obj, position_lambda=None)
get_localisation(node, mode=None)
compute_network_distance(source, target, mode, parameters=None, return_path=False)
compute_euclidean_distance(position1, position2, mode=None)
distance_dict_between(position, obj_list, distance_type, n=None, maximum_distance=None, position_lambda=None, mode=None, is_origin=True, parameters=None, return_path=False)
euclidean_n_closest(position, obj_list, n, maximum_distance=None, position_lambda=None)
closest_object(position, obj_list, is_origin, mode, parameters=None, position_lambda=None, return_path=False, n=None)

Find the object of the list that is closest to the given position.

We compute network distances between the objects of the list and the given position. If the n param is provided, we pre-process the list, and only keep the n euclidean closest objects.

  • position

  • obj_list

  • is_origin – boolean indicating if the

  • mode

  • parameters

  • position_lambda

  • return_path

  • n


nearest_node_in_modes(localisation, modes)

Find the node common to given topologies that is closest (euclidean distance) to the localisation

  • localisation – (lat, lng) localisation

  • modes – transport modes, each corresponding to a topology


closest node that belongs to all topologies

localisations_nearest_nodes(x_coordinates, y_coordinates, modes, return_dist=False)

Call the topology localisations_nearest_nodes method.

If a list of modes is provided, consider only nodes that are present in all provided topologies.

If a node as no neighbour, assign None

  • x_coordinates – list of X coordinates of the localisations

  • y_coordinates – list of Y coordinates of the localisations

  • modes – topology modes

  • return_dist – optionally also return distance between points and nearest nodes


list of nearest nodes or (nearest_nodes, distances)


Find the nodes that are common to the given topologies


modes – transport modes, each corresponding to a topology


set object, containing the intersection of the topology nodes

get_object_at(position, obj_list, position_lambda=None)

Return the first agent of the list that is at the given position.

  • position

  • obj_list

  • position_lambda


approximate_path(origin, destination, distance_factor, speed, mode=None)

Approximate the length and time of a trip based on the euclidean distance and speed.

The computation is based on a factor that is applied to the euclidean distance.

  • origin – origin position

  • destination – destination position

  • distance_factor – value multiplied to euclidean distance to get trip distance.

  • speed – speed of the travelling agent, in m/s. If None, travel time is not computed

  • mode – position’s topology. Default is None, then look at all environment’s topologies.


tuple (travel_length, travel_time)

add_node(node_id, properties, modes)

Add a node id and its properties to the given modes.

  • node_id – id of the new node

  • properties – properties of the node

  • modes – list topologies to add the node to

add_stops_correspondence(stops_table, modes, extend_graph, max_distance=config['max_stop_distance'])

Add a ‘nearest_node’ column to the given table containing the stop’s nearest environment position.

If extend_graph is True and the nearest node is further than max_distance from the stop, add a new node to the graph.

  • stops_table – DataFrame with columns [“stop_id”, “stop_lat”, “stop_lon”]

  • modes – list of modes

  • extend_graph – boolean indicating if the graph should be extended when nearest nodes are too far

  • max_distance – maximum node distance before extending graph