flow.networks package

Contains all available networks in Flow.

class flow.networks.BayBridgeNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

A network used to simulate the Bay Bridge.

The bay bridge was originally imported from OpenStreetMap and subsequently modified to more closely match the network geometry of the actual Bay Bridge. Vehicles are only allowed to exist of and traverse the edges leading up to and which the westbound Bay Bridge.

specify_routes(net_params)[source]

See parent class.

Routes for vehicles moving through the bay bridge from Oakland to San Francisco.

class flow.networks.BayBridgeTollNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

A network used to simulate the bottleneck portion of the Bay Bridge.

The bay bridge was originally imported from OpenStreetMap and subsequently modified to more closely match the network geometry of the actual Bay Bridge. As opposed to BayBridgeNetwork, this network places vehicles on a reduced portion of the Bay Bridge in order to reduce the number of vehicles that need to be simulated.

specify_routes(net_params)[source]

See parent class.

Routes for vehicles moving through the bay bridge from Oakland to San Francisco.

class flow.networks.BottleneckNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

Network class for bottleneck simulations.

This network acts as a scalable representation of the Bay Bridge. It consists of a two-stage lane-drop bottleneck where 4n lanes reduce to 2n and then to n, where n is the scaling value. The length of the bottleneck is fixed.

Requires from net_params:

  • scaling : the factor multiplying number of lanes

  • speed_limit : edge speed limit

get_bottleneck_lanes(lane)[source]

Return the reduced number of lanes.

specify_centroids(net_params)[source]

See parent class.

specify_connections(net_params)[source]

See parent class.

specify_edge_starts()[source]

See parent class.

specify_edges(net_params)[source]

See parent class.

specify_nodes(net_params)[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

class flow.networks.FigureEightNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

Figure eight network class.

The figure eight network is an extension of the ring road network: Two rings, placed at opposite ends of the network, are connected by an intersection with road segments of length equal to the diameter of the rings. Serves as a simulation of a closed ring intersection.

Requires from net_params:

  • ring_radius : radius of the circular portions of the network. Also corresponds to half the length of the perpendicular straight lanes.

  • resolution : number of nodes resolution in the circular portions

  • lanes : number of lanes in the network

  • speed : max speed of vehicles in the network

specify_connections(net_params)[source]

See parent class.

specify_edge_starts()[source]

See base class.

specify_edges(net_params)[source]

See parent class.

specify_internal_edge_starts()[source]

See base class.

specify_nodes(net_params)[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

specify_types(net_params)[source]

See parent class.

class flow.networks.HighwayNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

Highway network class.

This network consists of num_edges different straight highway sections with a total characteristic length and number of lanes.

Requires from net_params:

  • length : length of the highway

  • lanes : number of lanes in the highway

  • speed_limit : max speed limit of the highway

  • num_edges : number of edges to divide the highway into

  • use_ghost_edge : whether to include a ghost edge. This edge is provided a different speed limit.

  • ghost_speed_limit : speed limit for the ghost edge

  • boundary_cell_length : length of the downstream ghost edge with the reduced speed limit

static gen_custom_start_pos(cls, net_params, initial_config, num_vehicles)[source]

Generate a user defined set of starting positions.

This method is just used for testing.

specify_edge_starts()[source]

See parent class.

specify_edges(net_params)[source]

See parent class.

specify_internal_edge_starts()[source]

See parent class.

specify_nodes(net_params)[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

specify_types(net_params)[source]

See parent class.

class flow.networks.HighwayRampsNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

Network class for a highway section with on and off ramps.

This network consists of a single or multi-lane highway network with a variable number of on-ramps and off-ramps at arbitrary positions, with arbitrary numbers of lanes. It can be used to generate periodic perturbation on a more realistic highway.

Parameters in net_params:

  • highway_length : total length of the highway

  • on_ramps_length : length of each on-ramp

  • off_ramps_length : length of each off-ramp

  • highway_lanes : number of lanes on the highway

  • on_ramps_lanes : number of lanes on each on-ramp

  • off_ramps_lanes : number of lanes on each off-ramp

  • highway_speed : speed limit on the highway

  • on_ramps_speed : speed limit on each on-ramp

  • off_ramps_speed : speed limit on each off-ramp

  • on_ramps_pos : positions of the in-ramps on the highway (int list)

  • off_ramps_pos : positions of the off-ramps on the highway (int list)

  • next_off_ramp_probaprobability for a vehicle to exit the highway

    at the next off-ramp

specify_edges(net_params)[source]

See parent class.

specify_nodes(net_params)[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

specify_types(net_params)[source]

See parent class.

class flow.networks.I210SubNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

A network used to simulate the I-210 sub-network.

Requires from net_params:

  • on_ramp : whether to include vehicle on the on-ramp

  • ghost_edge : whether to include the downstream slow-down edge in the network

specify_edge_starts()[source]

See parent class.

specify_internal_edge_starts()[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

class flow.networks.MergeNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

Network class for highways with a single in-merge.

This network consists of a single or multi-lane highway network with an on-ramp with a variable number of lanes that can be used to generate periodic perturbation.

Requires from net_params:

  • merge_length : length of the merge edge

  • pre_merge_length : length of the highway leading to the merge

  • post_merge_length : length of the highway past the merge

  • merge_lanes : number of lanes in the merge

  • highway_lanes : number of lanes in the highway

  • speed_limit : max speed limit of the network

specify_edge_starts()[source]

See parent class.

specify_edges(net_params)[source]

See parent class.

specify_internal_edge_starts()[source]

See parent class.

specify_nodes(net_params)[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

specify_types(net_params)[source]

See parent class.

class flow.networks.MiniCityNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

Network class for bottleneck simulations.

This network is a recreation of the blank (get from something). The size of the network can be modified by updating the SCALING variable within the script.

specify_connections(net_params)[source]

See parent class.

specify_edge_starts()[source]

See parent class.

specify_edges(net_params)[source]

See parent class.

specify_nodes(net_params)[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

specify_types(net_params)[source]

See parent class.

class flow.networks.MultiRingNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

Ring road network.

This network is similar to RingNetwork, but generates multiple separate ring roads in the same simulation.

Requires from net_params:

  • length : length of the circle

  • lanes : number of lanes in the circle

  • speed_limit : max speed limit of the circle

  • resolution : number of nodes resolution

  • num_ring : number of rings in the system

static gen_custom_start_pos(cls, net_params, initial_config, num_vehicles)[source]

Generate uniformly spaced starting positions on each ring.

It is assumed that there are an equal number of vehicles per ring. If the perturbation term in initial_config is set to some positive value, then the start positions are perturbed from a uniformly spaced distribution by a gaussian whose std is equal to this perturbation term.

specify_edge_starts()[source]

See parent class.

specify_edges(net_params)[source]

See parent class.

specify_nodes(net_params)[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

specify_types(net_params)[source]

See parent class.

class flow.networks.Network(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: object

Base network class.

Initializes a new network. Networks are used to specify features of a network, including the positions of nodes, properties of the edges and junctions connecting these nodes, properties of vehicles and traffic lights, and other features as well. These features can later be acquired from this class via a plethora of get methods (see documentation).

This class uses network specific features to generate the necessary network configuration files needed to initialize a simulation instance. The methods of this class are called by the base network class.

The network files can be created in one of three ways:

  • Custom networks can be generated by defining the properties of the network’s directed graph. This is done by defining the nodes and edges properties using the specify_nodes and specify_edges methods, respectively, as well as other properties via methods including specify_types, specify_connections, etc… For more on this, see the tutorial on creating custom networks or refer to some of the available networks.

  • Network data can be collected from an OpenStreetMap (.osm) file. The .osm file is specified in the NetParams object. For example:

    >>> from flow.core.params import NetParams
    >>> net_params = NetParams(osm_path='/path/to/osm_file.osm')
    

    In this case, no specify_nodes and specify_edges methods are needed. However, a specify_routes method is still needed to specify the appropriate routes vehicles can traverse in the network.

  • Network data can be collected from an sumo-specific network (.net.xml) file. This file is specified in the NetParams object. For example:

    >>> from flow.core.params import NetParams
    >>> net_params = NetParams(template='/path/to/template')
    

    In this case, no specify_nodes and specify_edges methods are needed. However, a specify_routes method is still needed to specify the appropriate routes vehicles can traverse in the network.

This class can be instantiated once and reused in multiple experiments. Note that this function stores all the relevant parameters. The generate() function still needs to be called separately.

Attributes

orig_name : str

the variable provided under the name parameter to this object upon instantiation

name : str

the variable provided under the name parameter to this object upon instantiation, appended with a timestamp variable. This timestamp is meant to differentiate generated network files during parallelism

vehicles : flow.core.params.VehicleParams

vehicle specific parameters, used to specify the types and number of vehicles at the start of a simulation

net_params : flow.core.params.NetParams

network specific parameters, used primarily to identify properties of a network such as the lengths of edges and the number of lanes in each edge. This attribute is very network-specific, and should contain the variables denoted by the ADDITIONAL_NET_PARAMS dict in each network class file

initial_config : flow.core.params.InitialConfig

specifies parameters that affect the positioning of vehicle in the network at the start of a simulation. For more, see flow/core/params.py

traffic_lights : flow.core.params.TrafficLightParams

used to describe the positions and types of traffic lights in the network. For more, see flow/core/params.py

nodes : list of dict or None

list of nodes that are assigned to the network via the specify_nodes method. All nodes in this variable are expected to have the following properties:

  • name: a unique identifier for the node

  • x: x-coordinate of the node, in meters

  • y: y-coordinate of the node, in meters

If the network is meant to generate the network from an OpenStreetMap or template file, this variable is set to None

edges : list of dict or None

edges that are assigned to the network via the specify_edges method. This include the shape, position, and properties of all edges in the network. These properties include the following mandatory properties:

  • id: name of the edge

  • from: name of the node the edge starts from

  • to: the name of the node the edges ends at

  • length: length of the edge

In addition, either the following properties need to be specifically defined or a type variable property must be defined with equivalent attributes in self.types:

  • numLanes: the number of lanes on the edge

  • speed: the speed limit for vehicles on the edge

Moreover, the following attributes may optionally be available:

  • shape: the positions of intermediary nodes used to define the shape of an edge. If no shape is specified, then the edge will appear as a straight line.

Note that, if the network is meant to generate the network from an OpenStreetMap or template file, this variable is set to None

types : list of dict or None

A variable used to ease the definition of the properties of various edges. Each element in the list consists of a dict consisting of the following property:

  • id: name of the edge type. Edges in the self.edges attribute with a similar value under the “type” key will adopt the properties of other components of this list, such as “speed” and “numLanes”.

If the type variable is None, then no types are available within the network. Furthermore, a proper example of this variable being used can be found under specify_types in flow/networks/loop.py.

Note that, if the network is meant to generate the network from an OpenStreetMap or template file, this variable is set to None

connections : list of dict or None

A variable used to describe how any specific node’s incoming and outgoing edges/lane pairs are connected. If no connections are specified, sumo generates default connections.

If the connections attribute is set to None, then the connections within the network will be specified by the simulator.

Note that, if the network is meant to generate the network from an OpenStreetMap or template file, this variable is set to None

routes : dict

A variable whose keys are the starting edge of a specific route, and whose values are the list of edges a vehicle is meant to traverse starting from that edge. These are only applied at the start of a simulation; vehicles are allowed to reroute within the environment immediately afterwards.

edge_starts : list of (str, float)

a list of tuples in which the first element of the tuple is the name of the edge/intersection/internal_link, and the second value is the distance of the link from some global reference, i.e. [(link_0, pos_0), (link_1, pos_1), …]

internal_edge_starts : list of (str, float)

A variable similar to edge_starts but for junctions within the network. If no junctions are available, this variable will return the default variable: [(‘:’, -1)] needed by sumo simulations.

intersection_edge_starts : list of (str, float)

A variable similar to edge_starts but for intersections within the network. This variable will be deprecated in future releases.

static gen_custom_start_pos(cls, net_params, initial_config, num_vehicles)[source]

Generate a user defined set of starting positions.

Parameters

cls : flow.core.kernel.network.BaseKernelNetwork

flow network kernel, with all the relevant methods implemented

net_params : flow.core.params.NetParams

network-specific parameters

initial_config : flow.core.params.InitialConfig

see flow/core/params.py

num_vehicles : int

number of vehicles to be placed on the network

Returns

list of tuple (float, float)

list of start positions [(edge0, pos0), (edge1, pos1), …]

list of int

list of start lanes

list of float

list of start speeds

specify_connections(net_params)[source]

Specify the attributes of connections.

These attributes are used to describe how any specific node’s incoming and outgoing edges/lane pairs are connected. If no connections are specified, sumo generates default connections.

Parameters

net_params : flow.core.params.NetParams

see flow/core/params.py

Returns

list of dict

A list of connection attributes. If none are specified, no .con.xml file is created.

For information on type attributes, see:
http://sumo.dlr.de/wiki/Networks/Building_Networks_from_own_XML-descriptions#Connection_Descriptions
specify_edge_starts()[source]

Define edge starts for road sections in the network.

This is meant to provide some global reference frame for the road edges in the network.

By default, the edge starts are specified from the network configuration file. Note that, the values are arbitrary but do not allow the positions of any two edges to overlap, thereby making them compatible with all starting position methods for vehicles.

Returns

list of (str, float)

list of edge names and starting positions, ex: [(edge0, pos0), (edge1, pos1), …]

specify_edges(net_params)[source]

Specify the attributes of edges connecting pairs on nodes.

Parameters

net_params : flow.core.params.NetParams

see flow/core/params.py

Returns

list of dict

A list of edges attributes (a separate dict for each edge). Edge attributes must include:

  • id {string} – name of the edge

  • from {string} – name of node the directed edge starts from

  • to {string} – name of the node the directed edge ends at

In addition, the attributes must contain at least one of the following:

  • “numLanes” {int} and “speed” {float} – the number of lanes and speed limit of the edge, respectively

  • type {string} – a type identifier for the edge, which can be used if several edges are supposed to possess the same number of lanes, speed limits, etc…

Other attributes may also be specified. See:
http://sumo.dlr.de/wiki/Networks/Building_Networks_from_own_XML-descriptions#Edge_Descriptions
specify_internal_edge_starts()[source]

Define the edge starts for internal edge nodes.

This is meant to provide some global reference frame for the internal edges in the network.

These edges are the result of finite-length connections between road sections. This methods does not need to be specified if “no-internal- links” is set to True in net_params.

By default, all internal edge starts are given a position of -1. This may be overridden; however, in general we do not worry about internal edges and junctions in large networks.

Returns

list of (str, float)

list of internal junction names and starting positions, ex: [(internal0, pos0), (internal1, pos1), …]

specify_nodes(net_params)[source]

Specify the attributes of nodes in the network.

Parameters

net_params : flow.core.params.NetParams

see flow/core/params.py

Returns

list of dict

A list of node attributes (a separate dict for each node). Nodes attributes must include:

  • id {string} – name of the node

  • x {float} – x coordinate of the node

  • y {float} – y coordinate of the node

Other attributes may also be specified. See:
http://sumo.dlr.de/wiki/Networks/Building_Networks_from_own_XML-descriptions#Node_Descriptions
specify_routes(net_params)[source]

Specify the routes vehicles can take starting from any edge.

Routes can be specified in one of three ways:

  • In this case of deterministic routes (as is the case in the ring road network), the routes can be specified as dictionary where the key element represents the starting edge and the element is a single list of edges the vehicle must traverse, with the first edge corresponding to the edge the vehicle begins on. Note that the edges must be connected for the route to be valid.

    For example (from flow/networks/ring.py):

    >>> def specify_routes(self, net_params):
    >>>     return {
    >>>         "top": ["top", "left", "bottom", "right"],
    >>>         "left": ["left", "bottom", "right", "top"],
    >>>         "bottom": ["bottom", "right", "top", "left"],
    >>>         "right": ["right", "top", "left", "bottom"]
    >>>     }
    
  • Alternatively, if the routes are meant to be stochastic, each element can consist of a list of (route, probability) tuples, where the first element in the tuple is one of the routes a vehicle can take from a specific starting edge, and the second element is the probability that vehicles will choose that route. Note that, in this case, the sum of probability values for each dictionary key must sum up to one.

    For example, if we were to imagine the edge “right” in the ring road examples where split into two edges, “right_0” and “right_1”, the routes for vehicles in this network in the probabilistic setting can be:

    >>> def specify_routes(self, net_params):
    >>>     return {
    >>>         "top": [
    >>>             (["top", "left", "bottom", "right_0"], 0.9),
    >>>             (["top", "left", "bottom", "right_1"], 0.1)
    >>>         ],
    >>>         "left": [
    >>>             (["left", "bottom", "right_0", "top"], 0.3),
    >>>             (["left", "bottom", "right_1", "top"], 0.7)
    >>>         ],
    >>>         "bottom": [
    >>>             (["bottom", "right_0", "top", "left"], 0.5),
    >>>             (["bottom", "right_1", "top", "left"], 0.5)
    >>>         ],
    >>>         "right_0": [
    >>>             (["right_0", "top", "left", "bottom"], 1)
    >>>         ],
    >>>         "right_1": [
    >>>             (["right_1", "top", "left", "bottom"], 1)
    >>>         ]
    >>>     }
    
  • Finally, if you would like to assign a specific starting edge and route to a vehicle with a specific ID, you can do so by adding a element into the dictionary whose key is the name of the vehicle and whose content is the list of edges the vehicle is meant to traverse as soon as it is introduced to the network.

    As an example, assume we have 4 vehicles named ‘human_0’, ‘human_1’, ‘human_2’, and ‘human_3’ in the original ring road. Then, an appropriate definition of the routes may look something like:

    >>> def specify_routes(self, net_params):
    >>>     return {
    >>>         "human_0": ["top", "left", "bottom", "right"],
    >>>         "human_1": ["left", "bottom", "right", "top"],
    >>>         "human_2": ["bottom", "right", "top", "left"],
    >>>         "human_3": ["right", "top", "left", "bottom"]
    >>>     }
    

    Note: This feature is experimental, and may not always work as expected (for example if the starting positions and routes of a specific vehicle do not match).

The define_routes method is optional, and need not be defined. If it is not implemented, vehicles that enter a network are assigned routes consisting solely on their current edges, and exit the network once they reach the end of their edge. Routes, however, can be reassigned during simulation via a routing controller (see flow/controllers/routing_controllers.py).

Parameters

net_params : flow.core.params.NetParams

see flow/core/params.py

Returns

dict

Key = name of the starting edge Element = list of edges a vehicle starting from this edge must traverse OR a list of (route, probability) tuples for each starting edge

specify_types(net_params)[source]

Specify the attributes of various edge types (if any exist).

Parameters

net_params : flow.core.params.NetParams

see flow/core/params.py

Returns

list of dict

A list of type attributes for specific groups of edges. If none are specified, no .typ.xml file is created.

For information on type attributes, see:
http://sumo.dlr.de/wiki/Networks/Building_Networks_from_own_XML-descriptions#Type_Descriptions
class flow.networks.RingNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

Ring road network.

This network consists of nodes at the top, bottom, left, and right peripheries of the circles, connected by four 90 degree arcs. It is parametrized by the length of the entire network and the number of lanes and speed limit of the edges.

Requires from net_params:

  • length : length of the circle

  • lanes : number of lanes in the circle

  • speed_limit : max speed limit of the circle

  • resolution : number of nodes resolution

specify_edge_starts()[source]

See parent class.

specify_edges(net_params)[source]

See parent class.

specify_internal_edge_starts()[source]

See parent class.

specify_nodes(net_params)[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

specify_types(net_params)[source]

See parent class.

class flow.networks.TrafficLightGridNetwork(name, vehicles, net_params, initial_config=<flow.core.params.InitialConfig object>, traffic_lights=<flow.core.params.TrafficLightParams object>)[source]

Bases: flow.networks.base.Network

Traffic Light Grid network class.

The traffic light grid network consists of m vertical lanes and n horizontal lanes, with a total of nxm intersections where the vertical and horizontal edges meet.

Requires from net_params:

  • grid_array : dictionary of grid array data, with the following keys

    • row_num : number of horizontal rows of edges

    • col_num : number of vertical columns of edges

    • inner_length : length of inner edges in traffic light grid network

    • short_length : length of edges that vehicles start on

    • long_length : length of final edge in route

    • cars_top : number of cars starting at the edges heading to the top

    • cars_bot : number of cars starting at the edges heading to the bottom

    • cars_left : number of cars starting at the edges heading to the left

    • cars_right : number of cars starting at the edges heading to the right

  • horizontal_lanes : number of lanes in the horizontal edges

  • vertical_lanes : number of lanes in the vertical edges

  • speed_limit : speed limit for all edges. This may be represented as a float value, or a dictionary with separate values for vertical and horizontal lanes.

static gen_custom_start_pos(cls, net_params, initial_config, num_vehicles)[source]

See parent class.

property node_mapping

Map nodes to edges.

Returns a list of pairs (node, connected edges) of all inner nodes and for each of them, the 4 edges that leave this node.

The nodes are listed in alphabetical order, and within that, edges are listed in order: [bot, right, top, left].

specify_connections(net_params)[source]

Build out connections at each inner node.

Connections describe what happens at the intersections. Here we link lanes in straight lines, which means vehicles cannot turn at intersections, they can only continue in a straight line.

specify_edge_starts()[source]

See parent class.

specify_edges(net_params)[source]

See parent class.

specify_nodes(net_params)[source]

See parent class.

specify_routes(net_params)[source]

See parent class.

specify_types(net_params)[source]

See parent class.