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.
-
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.
-
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
-
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
-
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
-
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
-
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
-
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
-
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.
-
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.
-
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
andspecify_edges
methods, respectively, as well as other properties via methods includingspecify_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
andspecify_edges
methods are needed. However, aspecify_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
andspecify_edges
methods are needed. However, aspecify_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
-
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].