Merge pull request flow-project#561 from kjang96/issue_436

Documentation for bottleneck

examples/sumo/bottlenecks.py

@@ -15,6 +15,7 @@
 import numpy as np
 SCALING = 1
 DISABLE_TB = True
+
 # If set to False, ALINEA will control the ramp meter
 DISABLE_RAMP_METER = True
 INFLOW = 2300
@@ -23,9 +24,11 @@
 class BottleneckDensityExperiment(Experiment):
 
     def __init__(self, env):
+        """Instantiate the bottleneck experiment"""
         super().__init__(env)
 
     def run(self, num_runs, num_steps, rl_actions=None, convert_to_csv=False):
+        """See parent class."""
         info_dict = {}
         if rl_actions is None:
 

flow/envs/bottleneck_env.py

@@ -25,24 +25,24 @@
 
 MAX_LANES = 4  # base number of largest number of lanes in the network
 EDGE_LIST = ["1", "2", "3", "4", "5"]  # Edge 1 is before the toll booth
-EDGE_BEFORE_TOLL = "1"
+EDGE_BEFORE_TOLL = "1"  # Specifies which edge number is before toll booth
 TB_TL_ID = "2"
-EDGE_AFTER_TOLL = "2"
+EDGE_AFTER_TOLL = "2"  # Specifies which edge number is after toll booth
 NUM_TOLL_LANES = MAX_LANES
 
 TOLL_BOOTH_AREA = 10  # how far into the edge lane changing is disabled
 RED_LIGHT_DIST = 50  # how close for the ramp meter to start going off
 
-EDGE_BEFORE_RAMP_METER = "2"
-EDGE_AFTER_RAMP_METER = "3"
+EDGE_BEFORE_RAMP_METER = "2"  # Specifies which edge is before ramp meter
+EDGE_AFTER_RAMP_METER = "3"  # Specifies which edge is after ramp meter
 NUM_RAMP_METERS = MAX_LANES
 
-RAMP_METER_AREA = 80
+RAMP_METER_AREA = 80  # Area occupied by ramp meter
 
-MEAN_NUM_SECONDS_WAIT_AT_FAST_TRACK = 3
-MEAN_NUM_SECONDS_WAIT_AT_TOLL = 15
+MEAN_NUM_SECONDS_WAIT_AT_FAST_TRACK = 3  # Average waiting time at fast track
+MEAN_NUM_SECONDS_WAIT_AT_TOLL = 15  # Average waiting time at toll
 
-BOTTLE_NECK_LEN = 280
+BOTTLE_NECK_LEN = 280  # Length of bottleneck
 NUM_VEHICLE_NORM = 20
 
 ADDITIONAL_ENV_PARAMS = {
@@ -85,7 +85,7 @@
     "inflow_range": [1000, 2000]
 }
 
-START_RECORD_TIME = 0.0
+START_RECORD_TIME = 0.0  # Time to start recording
 PERIOD = 10.0
 
 
@@ -102,6 +102,7 @@ class BottleneckEnv(Env):
     """
 
     def __init__(self, env_params, sim_params, scenario, simulator='traci'):
+        """Initialize the BottleneckEnv class."""
         for p in ADDITIONAL_ENV_PARAMS.keys():
             if p not in env_params.additional_params:
                 raise KeyError(
@@ -142,6 +143,11 @@ def __init__(self, env_params, sim_params, scenario, simulator='traci'):
         self.outflow_index = 0
 
     def additional_command(self):
+        """Build a dict with vehicle information.
+
+        The dict contains the list of vehicles and their position for each edge
+        and for each edge within the edge.
+        """
         super().additional_command()
 
         # build a dict containing the list of vehicles and their position for
@@ -176,6 +182,12 @@ def additional_command(self):
             self.next_period += PERIOD / self.sim_step
 
     def ramp_meter_lane_change_control(self):
+        """Control the lane changing behavior.
+
+        Specify/Toggle the lane changing behavior of the vehicles
+        depending on factors like whether or not they are before
+        the toll.
+        """
         cars_that_have_left = []
         for veh_id in self.cars_before_ramp:
             if self.k.vehicle.get_edge(veh_id) == EDGE_AFTER_RAMP_METER:
@@ -246,6 +258,7 @@ def alinea(self):
         self.k.traffic_light.set_state('3', ''.join(colors))
 
     def apply_toll_bridge_control(self):
+        """Apply control to the toll bridge."""
         cars_that_have_left = []
         for veh_id in self.cars_waiting_for_toll:
             if self.k.vehicle.get_edge(veh_id) == EDGE_AFTER_TOLL:
@@ -312,7 +325,11 @@ def apply_toll_bridge_control(self):
                 node_id=TB_TL_ID, state=new_tl_state)
 
     def get_bottleneck_density(self, lanes=None):
-        """Return the density of the bottleneck."""
+        """Return the density of specified lanes.
+
+        If no lanes are specified, this function calculates the
+        density of all vehicles on all lanes of the bottleneck edges.
+        """
         bottleneck_ids = self.k.vehicle.get_ids_by_edge(['3', '4'])
         if lanes:
             veh_ids = [
@@ -355,7 +372,10 @@ def get_state(self):
 
 
 class BottleNeckAccelEnv(BottleneckEnv):
-    """Environment used to train vehicles to pass through a bottleneck.
+    """BottleNeckAccelEnv.
+
+    Environment used to train vehicles to effectively pass through a
+    bottleneck.
 
     States
         An observation is the edge position, speed, lane, and edge number of
@@ -382,6 +402,7 @@ class BottleNeckAccelEnv(BottleneckEnv):
     """
 
     def __init__(self, env_params, sim_params, scenario, simulator='traci'):
+        """Initialize BottleNeckAccelEnv."""
         for p in ADDITIONAL_RL_ENV_PARAMS.keys():
             if p not in env_params.additional_params:
                 raise KeyError(
@@ -585,7 +606,7 @@ class DesiredVelocityEnv(BottleneckEnv):
 
     Environment used to train vehicles to effectively pass through a
     bottleneck by specifying the velocity that RL vehicles should attempt to
-    travel in certain regions of space
+    travel in certain regions of space.
 
     States
         An observation is the number of vehicles in each lane in each
@@ -602,6 +623,7 @@ class DesiredVelocityEnv(BottleneckEnv):
     """
 
     def __init__(self, env_params, sim_params, scenario, simulator='traci'):
+        """Initialize DesiredVelocityEnv."""
         super().__init__(env_params, sim_params, scenario, simulator)
         for p in ADDITIONAL_VSL_ENV_PARAMS.keys():
             if p not in env_params.additional_params:

flow/envs/green_wave_env.py

@@ -37,9 +37,10 @@ class TrafficLightGridEnv(Env):
 
     Required from env_params:
 
-    * switch_time: minimum switch time for each traffic light (in seconds).
+    * switch_time: minimum time a light must be constant before
+      it switches (in seconds).
       Earlier RL commands are ignored.
-    * tl_type: whether the traffic lights should be actuated by sumo or RL
+    * tl_type: whether the traffic lights should be actuated by sumo or RL,
       options are respectively "actuated" and "controlled"
     * discrete: determines whether the action space is meant to be discrete or
       continuous

tests/fast_tests/test_examples.py

@@ -135,7 +135,7 @@ def test_minicity(self):
 
     def test_density_exp(self):
         """Verifies that examples/sumo/density_exp.py is working."""
-        _ = run_bottleneck.remote(100, 1, 10, render=False)
+        run_bottleneck.remote(100, 1, 10, render=False)
 
 
 class TestRllibExamples(unittest.TestCase):