Document all attributes in classes (#661)

* add doc in merge

* Added attribute documentation for loop_accel.py

* Added attribute documenation for green_wave_env.py

* added attributes for kernel/simulation/aimsun.py

* added attributes to LaneChangeAccelPOEnv in lane_changing.py

* added attributes to kernel.scenario.aimsun

* Add missing attributes for base env.

* Add missing attribute documentation to base env.

* Add missing attribute documentation to pyglet renderer.

* Fix pip8.

* removed private attributes from the docstring

* changed <str> to 'of str'

* Added attributes for bottleneck env

* pep8

* Apply suggestions from code review

flow/core/kernel/scenario/aimsun.py

@@ -19,6 +19,19 @@ class AimsunKernelScenario(KernelScenario):
     This class is responsible for passing features to and calling the
     "generate.py" file within flow/utils/aimsun/. All other features are
     designed to extend KernelScenario.
+
+    Attributes
+    ----------
+    kernel_api : any
+        an API that may be used to interact with the simulator
+    network : flow.scenarios.Scenario
+        an object containing relevant network-specific features such as the
+        locations and properties of nodes and edges in the network
+    rts : dict
+        specifies routes vehicles can take. See the parent class for
+        description of the attribute.
+    aimsun_proc : subprocess.Popen
+        an object which is used to start or shut down Aimsun from the script
     """
 
     def __init__(self, master_kernel, sim_params):

flow/core/kernel/simulation/aimsun.py

@@ -10,6 +10,22 @@ class AimsunKernelSimulation(KernelSimulation):
     """Aimsun simulation kernel.
 
     Extends KernelSimulation.
+
+    Attributes
+    ----------
+    master_kernel : flow.core.kernel.Kernel
+        the higher level kernel (used to call methods from other sub-kernels)
+    kernel_api : any
+        an API that may be used to interact with the simulator
+    sim_step : float
+        seconds per simulation step; 0.5 by default
+    emission_path : str
+        Path to the folder in which to create the emissions output.
+        Emissions output is not generated if this value is not specified
+    time : float
+        used to internally keep track of the simulation time
+    stored_data : dict
+        a file used to store data if an emission file is provided
     """
 
     def __init__(self, master_kernel):
@@ -20,11 +36,7 @@ def __init__(self, master_kernel):
         self.kernel_api = None
         self.sim_step = None
         self.emission_path = None
-
-        # used to internally keep track of the simulation time
         self.time = 0
-
-        # a file used to store data if an emission file is provided
         self.stored_data = {
             'time': [],
             'x': [],

flow/envs/base_env.py

@@ -58,9 +58,13 @@ class Env(*classdef):
     Attributes
     ----------
     env_params : flow.core.params.EnvParams
-       see flow/core/params.py
+        see flow/core/params.py
     sim_params : flow.core.params.SimParams
-       see flow/core/params.py
+        see flow/core/params.py
+    net_params : flow.core.params.NetParams
+        see flow/core/params.py
+    initial_config : flow.core.params.InitialConfig
+        see flow/core/params.py
     scenario : flow.scenarios.Scenario
         see flow/scenarios/base_scenario.py
     simulator : str
@@ -69,6 +73,12 @@ class Env(*classdef):
         Flow kernel object, using for state acquisition and issuing commands to
         the certain components of the simulator. For more information, see:
         flow/core/kernel/kernel.py
+    state : to be defined in observation space
+        state of the simulation
+    obs_var_labels : list
+        optional labels for each entries in observed state
+    sim_step : float optional
+        seconds per simulation step; 0.1 by default
     time_counter : int
         number of steps taken since the start of a rollout
     step_counter : int

flow/envs/bottleneck_env.py

@@ -96,9 +96,99 @@ class BottleneckEnv(Env):
     portion of the bay bridge. Contains ramp meters, and a toll both.
 
     Additional
+    ----------
         Vehicles are rerouted to the start of their original routes once
         they reach the end of the network in order to ensure a constant
         number of vehicles.
+
+    Attributes
+    ----------
+    scaling : int
+        A factor describing how many lanes are in the system. Scaling=1 implies
+        4 lanes going to 2 going to 1, scaling=2 implies 8 lanes going to 4
+        going to 2, etc.
+    edge_dict : dict of dicts
+        A dict mapping edges to a dict of lanes where each entry in the lane
+        dict tracks the vehicles that are in that lane. Used to save on
+        unnecessary lookups.
+    cars_waiting_for_toll : {veh_id: {lane_change_mode: int, color: (int)}}
+        A dict mapping vehicle ids to a dict tracking the color and lane change
+        mode of vehicles before they entered the toll area. When vehicles exit
+        the tollbooth area, these values are used to set the lane change mode
+        and color of the vehicle back to how they were before they entered the
+        toll area.
+    cars_before_ramp : {veh_id: {lane_change_mode: int, color: (int)}}
+        Identical to cars_waiting_for_toll, but used to track cars approaching
+        the ramp meter versus approaching the tollbooth.
+    toll_wait_time : np.ndarray(float)
+        Random value, sampled from a gaussian indicating how much a vehicle in
+        each lane should wait to pass through the toll area. This value is
+        re-sampled for each approaching vehicle. That is, whenever a vehicle
+        approaches the toll area, we re-sample from the Gaussian to determine
+        its weight time.
+    fast_track_lanes : np.ndarray(int)
+        Middle lanes of the tollbooth are declared fast-track lanes, this numpy
+        array keeps track of which lanes these are. At a fast track lane, the
+        mean of the Gaussian from which we sample wait times is given by
+        MEAN_NUM_SECONDS_WAIT_AT_FAST_TRACK.
+    tl_state : str
+        String tracking the color of the traffic lights at the tollbooth. These
+        traffic lights are used imitate the effect of a tollbooth. If lane 1-4
+        are respectively green, red, red, green, then this string would be
+        "GrrG"
+    n_crit : int
+        The ALINEA algorithm adjusts the ratio of red to green time for the
+        ramp-metering traffic light based on feedback on how congested the
+        system is. As the measure of congestion, we use the number of vehicles
+        stuck in the bottleneck (edge 4). The critical operating value it tries
+        to stabilize the number of vehicles in edge 4 is n_crit. If there are
+        more than n_crit vehicles on edge 4, we increase the fraction of red
+        time to decrease the inflow to edge 4.
+    q_max : float
+        The ALINEA algorithm tries to control the flow rate through the ramp
+        meter. q_max is the maximum possible estimated flow we allow through
+        the bottleneck and can be converted into a maximum value for the ratio
+        of green to red time that we allow.
+    q_min : float
+        Similar to q_max, this is used to set the minimum value of green to red
+        ratio that we allow.
+    q : float
+        This value tracks the flow we intend to allow through the bottleneck.
+        For details on how it is computed, please read the alinea method or the
+        paper linked in that method.
+    feedback_update_time : float
+        The parameters of the ALINEA algorithm are only updated every
+        feedback_update_time seconds.
+    feedback_timer : float
+        This keeps track of how many seconds have passed since the ALINEA
+        parameters were last updated. If it exceeds feedback_update_time, the
+        parameters are updated
+    cycle_time : int
+        This value tracks how long a green-red cycle of the ramp meter is. The
+        first self.green_time seconds will be green and the remainder of the
+        cycle will be red.
+    ramp_state : np.ndarray
+        Array of floats of length equal to the number of lanes. For each lane,
+        this value tracks how many seconds of a given cycle have passed in that
+        lane. Each lane is offset from its adjacent lanes by
+        cycle_offset/(self.scaling * MAX_LANES) seconds. This offsetting means
+        that lights are offset in when they releasse vehicles into the
+        bottleneck. This helps maximize the throughput of the ramp meter.
+    green_time : float
+        How many seconds of a given cycle the light should remain green 4.
+        Defaults to 4 as this is just enough time for two vehicles to enter the
+        bottleneck from a given traffic light.
+    feedback_coeff : float
+        This is the gain on the feedback in the ALINEA algorithm
+    smoothed_num : np.ndarray
+        Numpy array keeping track of how many vehicles were in edge 4 over the
+        last 10 time seconds. This provides a more stable estimate of the
+        number of vehicles in edge 4.
+    outflow_index : int
+        Keeps track of which index of smoothed_num we should update with the
+        latest number of vehicles in the bottleneck. Should eventually be
+        deprecated as smoothed_num should be switched to a queue instead of an
+        array.
     """
 
     def __init__(self, env_params, sim_params, scenario, simulator='traci'):
@@ -122,7 +212,6 @@ def __init__(self, env_params, sim_params, scenario, simulator='traci'):
             int(np.ceil(1.5 * self.scaling)), int(np.ceil(2.6 * self.scaling)))
 
         self.tl_state = ""
-        self.next_period = START_RECORD_TIME / self.sim_step
 
         # values for the ALINEA ramp meter algorithm
         self.n_crit = env_add_params.get("n_crit", 8)
@@ -178,9 +267,6 @@ def additional_command(self):
         self.outflow_index = \
             (self.outflow_index + 1) % self.smoothed_num.shape[0]
 
-        if self.time_counter > self.next_period:
-            self.next_period += PERIOD / self.sim_step
-
     def ramp_meter_lane_change_control(self):
         """Control the lane changing behavior.
 
@@ -235,6 +321,14 @@ def alinea(self):
         Papageorgiou. "Toll plaza merging traffic control for throughput
         maximization." Journal of Transportation Engineering 136.1 (2009):
         67-76.
+
+        Essentially, we apply feedback control around the value self.n_crit.
+        We keep track of the number of vehicles in edge 4, average them across
+        time ot get a smoothed value and then compute
+        q_{t+1} = clip(q_t + K * (n_crit - n_avg), q_min, q_max). We then
+        convert this into a cycle_time value via cycle_time = 7200 / q.
+        Cycle_time = self.green_time + red_time i.e. the first self.green_time
+        seconds of a cycle will be green, and the remainder will be all red.
         """
         self.feedback_timer += self.sim_step
         self.ramp_state += self.sim_step

flow/envs/green_wave_env.py

@@ -67,6 +67,46 @@ class TrafficLightGridEnv(Env):
         Vehicles are rerouted to the start of their original routes once they
         reach the end of the network in order to ensure a constant number of
         vehicles.
+
+    Attributes
+    ----------
+    grid_array : dict
+        Array containing information on the grid, such as the length of roads,
+        row_num, col_num, number of initial cars
+    rows : int
+        Number of rows in this grid scenario
+    cols : int
+        Number of columns in this grid scenario
+    num_traffic_lights : int
+        Number of intersection in this grid scenario
+    tl_type : str
+        Type of traffic lights, either 'actuated' or 'static'
+    steps : int
+        Horizon of this experiment, see EnvParams.horion
+    obs_var_labels : dict
+        Referenced in the visualizer. Tells the visualizer which
+        metrics to track
+    node_mapping : dict
+        Dictionary mapping intersections / nodes (nomenclature is used
+        interchangeably here) to the edges that are leading to said
+        intersection / node
+    last_change : np array [num_traffic_lights]x1 np array
+        Multi-dimensional array keeping track, in timesteps, of how much time
+        has passed since the last change to yellow for each traffic light
+    direction : np array [num_traffic_lights]x1 np array
+        Multi-dimensional array keeping track of which direction in traffic
+        light is flowing. 0 indicates flow from top to bottom, and
+        1 indicates flow from left to right
+    currently_yellow : np array [num_traffic_lights]x1 np array
+        Multi-dimensional array keeping track of whether or not each traffic
+        light is currently yellow. 1 if yellow, 0 if not
+    min_switch_time : np array [num_traffic_lights]x1 np array
+        The minimum time in timesteps that a light can be yellow. Serves
+        as a lower bound
+    discrete : bool
+        Indicates whether or not the action space is discrete. See below for
+        more information:
+        https://github.com/openai/gym/blob/master/gym/spaces/discrete.py
     """
 
     def __init__(self, env_params, sim_params, scenario, simulator='traci'):

flow/envs/loop/lane_changing.py

@@ -186,16 +186,20 @@ class LaneChangeAccelPOEnv(LaneChangeAccelEnv):
 
     Termination
         See parent class.
+
+    Attributes
+    ----------
+    num_lanes : int
+        maximum number of lanes on any edge in the network
+    visible : list of str
+        lists of visible vehicles, used for visualization purposes
     """
 
     def __init__(self, env_params, sim_params, scenario, simulator='traci'):
         super().__init__(env_params, sim_params, scenario, simulator)
 
-        # maximum number of lanes on any edge in the network
         self.num_lanes = max(self.k.scenario.num_lanes(edge)
                              for edge in self.k.scenario.get_edge_list())
-
-        # lists of visible vehicles, used for visualization purposes
         self.visible = []
 
     @property

flow/envs/loop/loop_accel.py

@@ -54,6 +54,16 @@ class AccelEnv(Env):
     Termination
         A rollout is terminated if the time horizon is reached or if two
         vehicles collide into one another.
+
+    Attributes
+    ----------
+    prev_pos : dict
+        dictionary keeping track of each veh_id's previous position
+    absolute_position : dict
+        dictionary keeping track of each veh_id's absolute position
+    obs_var_labels : list of str
+        referenced in the visualizer. Tells the visualizer which
+        metrics to track
     """
 
     def __init__(self, env_params, sim_params, scenario, simulator='traci'):

flow/envs/merge.py

@@ -78,11 +78,15 @@ def __init__(self, env_params, sim_params, scenario, simulator='traci'):
 
         # maximum number of controlled vehicles
         self.num_rl = env_params.additional_params["num_rl"]
+
         # queue of rl vehicles waiting to be controlled
         self.rl_queue = collections.deque()
+
         # names of the rl vehicles controlled at any step
         self.rl_veh = []
-        # used for visualization
+
+        # used for visualization: the vehicles behind and after RL vehicles
+        # (ie the observed vehicles) will have a different color
         self.leader = []
         self.follower = []