Merge pull request flow-project#555 from kjang96/issue_42

Issue 42

flow/benchmarks/rllib/ars_runner.py

@@ -1,4 +1,5 @@
 """Runs the environments located in flow/benchmarks.
+
 The environment file can be modified in the imports to change the environment
 this runner script is executed on. This file runs the ARS algorithm in rllib
 and utilizes the hyper-parameters specified in:

flow/benchmarks/rllib/es_runner.py

@@ -1,5 +1,5 @@
-"""
-Runner script for environments located in flow/benchmarks.
+"""Runner script for environments located in flow/benchmarks.
+
 The environment file can be modified in the imports to change the environment
 this runner script is executed on. Furthermore, the rllib specific algorithm/
 parameters can be specified here once and used on multiple environments.

flow/benchmarks/rllib/ppo_runner.py

@@ -1,4 +1,5 @@
 """Runs the environments located in flow/benchmarks.
+
 The environment file can be modified in the imports to change the environment
 this runner script is executed on. This file runs the PPO algorithm in rllib
 and utilizes the hyper-parameters specified in:

flow/controllers/rlcontroller.py

@@ -30,7 +30,7 @@ class RLController(BaseController):
     """
 
     def __init__(self, veh_id, car_following_params):
-        """Instantiates an RL Controller."""
+        """Instantiate an RL Controller."""
         BaseController.__init__(
             self,
             veh_id,

flow/controllers/routing_controllers.py

@@ -78,6 +78,7 @@ class GridRouter(BaseRouter):
     """A router used to re-route a vehicle within a grid environment."""
 
     def choose_route(self, env):
+        """See parent class."""
         if len(env.k.vehicle.get_route(self.veh_id)) == 0:
             # this occurs to inflowing vehicles, whose information is not added
             # to the subscriptions in the first step that they departed

flow/controllers/velocity_controllers.py

@@ -1,9 +1,11 @@
+"""Contains a list of custom velocity controllers."""
+
 from flow.controllers.base_controller import BaseController
 import numpy as np
 
 
 class FollowerStopper(BaseController):
-    """Inspired by Dan Work's... work:
+    """Inspired by Dan Work's... work.
 
     Dissipation of stop-and-go waves via control of autonomous vehicles:
     Field experiments https://arxiv.org/abs/1705.01693
@@ -111,7 +113,7 @@ def get_accel(self, env):
 
 
 class PISaturation(BaseController):
-    """Inspired by Dan Work's... work:
+    """Inspired by Dan Work's... work.
 
     Dissipation of stop-and-go waves via control of autonomous vehicles:
     Field experiments https://arxiv.org/abs/1705.01693

flow/core/kernel/__init__.py

@@ -1,3 +1,5 @@
+"""Empty init file to ensure documentation for kernel is created."""
+
 from flow.core.kernel.kernel import Kernel
 
 __all__ = ["Kernel"]

flow/core/kernel/scenario/__init__.py

@@ -1,3 +1,5 @@
+"""Empty init file to ensure documentation for the scenario is created."""
+
 from flow.core.kernel.scenario.base import KernelScenario
 from flow.core.kernel.scenario.traci import TraCIScenario
 from flow.core.kernel.scenario.aimsun import AimsunKernelScenario

flow/core/kernel/scenario/aimsun.py

@@ -38,6 +38,7 @@ def __init__(self, master_kernel, sim_params):
         self.aimsun_proc = None
 
     def generate_network(self, scenario):
+        """See parent class."""
         self.network = scenario
 
         output = {
@@ -328,11 +329,11 @@ def prev_edge(self, edge, lane):
             return []
 
     def aimsun_edge_name(self, edge):
-        """Returns the edge name in Aimsun."""
+        """Return the edge name in Aimsun."""
         return self._edge_flow2aimsun[edge]
 
     def flow_edge_name(self, edge):
-        """Returns the edge name in Aimsun."""
+        """Return the edge name in Aimsun."""
         if edge not in self._edge_aimsun2flow:
             # print("aimsun edge unknown: {}".format(edge))
             return ''

flow/core/kernel/simulation/__init__.py

@@ -1,3 +1,5 @@
+"""Empty init file to ensure documentation for the simulation is created."""
+
 from flow.core.kernel.simulation.base import KernelSimulation
 from flow.core.kernel.simulation.traci import TraCISimulation
 from flow.core.kernel.simulation.aimsun import AimsunKernelSimulation

flow/core/kernel/simulation/base.py

@@ -81,5 +81,5 @@ def check_collision(self):
         raise NotImplementedError
 
     def close(self):
-        """Closes the current simulation instance."""
+        """Close the current simulation instance."""
         raise NotImplementedError

flow/core/kernel/traffic_light/__init__.py

@@ -1,3 +1,5 @@
+"""Empty init file to ensure documentation for traffic lights is created."""
+
 from flow.core.kernel.traffic_light.base import KernelTrafficLight
 from flow.core.kernel.traffic_light.traci import TraCITrafficLight
 from flow.core.kernel.traffic_light.aimsun import AimsunKernelTrafficLight

flow/core/kernel/vehicle/__init__.py

@@ -1,3 +1,5 @@
+"""Empty init file to ensure documentation for the vehicle class is created."""
+
 from flow.core.kernel.vehicle.base import KernelVehicle
 from flow.core.kernel.vehicle.traci import TraCIVehicle
 from flow.core.kernel.vehicle.aimsun import AimsunKernelVehicle

flow/core/kernel/vehicle/base.py

@@ -303,7 +303,7 @@ def get_speed(self, veh_id, error=-1001):
         raise NotImplementedError
 
     def get_default_speed(self, veh_id, error=-1001):
-        """Return the expected speed if no control were applied
+        """Return the expected speed if no control were applied.
 
         Parameters
         ----------

flow/core/kernel/vehicle/traci.py

@@ -401,6 +401,7 @@ def get_type(self, veh_id):
         return self.__vehicles[veh_id]["type"]
 
     def get_initial_speed(self, veh_id):
+        """Return the initial speed of the vehicle of veh_id."""
         return self.__vehicles[veh_id]["initial_speed"]
 
     def get_ids(self):

flow/core/params.py

@@ -149,9 +149,10 @@ def get_properties(self):
         return self.__tls_properties
 
     def actuated_default(self):
-        """
-        Return the default values to be used for the scenario
-        for a system where all junctions are actuated traffic lights.
+        """Return the default values for an actuated scenario.
+
+        An actuated scenario is a scenario for a system where
+        all junctions are actuated traffic lights.
 
         Returns
         -------
@@ -344,6 +345,13 @@ def add(self,
         self.types.append({"veh_id": veh_id, "type_params": type_params})
 
     def get_type(self, veh_id):
+        """Return the type of a specified vehicle.
+
+        Parameters
+        ----------
+        veh_id : str
+            vehicle ID whose type the user is querying
+        """
         return self.__vehicles[veh_id]["type"]
 
 
@@ -460,6 +468,7 @@ class AimsunParams(SimParams):
         the objects contained in this subnetwork. If set to None or if the
         specified subnetwork does not exist, the whole network will be loaded.
     """
+
     def __init__(self,
                  sim_step=0.1,
                  render=False,

flow/core/rewards.py

@@ -1,10 +1,10 @@
-"""This script contains of series of reward functions."""
+"""A series of reward functions."""
 
 import numpy as np
 
 
 def desired_velocity(env, fail=False, edge_list=None):
-    """Encourage proximity to a desired velocity.
+    r"""Encourage proximity to a desired velocity.
 
     This function measures the deviation of a system of vehicles from a
     user-specified desired velocity peaking when all vehicles in the ring
@@ -60,6 +60,24 @@ def desired_velocity(env, fail=False, edge_list=None):
 
 
 def average_velocity(env, fail=False):
+    """Encourage proximity to an average velocity.
+
+    This reward function returns the average velocity of all
+    vehicles in the system.
+
+    Parameters
+    ----------
+    env : flow.envs.Env
+        the environment variable, which contains information on the current
+        state of the system.
+    fail : bool, optional
+        specifies if any crash or other failure occurred in the system
+
+    Returns
+    -------
+    float
+        reward value
+    """
     vel = np.array(env.k.vehicle.get_speed(env.k.vehicle.get_ids()))
 
     if any(vel < -100) or fail:
@@ -71,7 +89,7 @@ def average_velocity(env, fail=False):
 
 
 def rl_forward_progress(env, gain=0.1):
-    """A reward function used to reward the RL vehicles travelling forward.
+    """Rewared function used to reward the RL vehicles for travelling forward.
 
     Parameters
     ----------
@@ -92,12 +110,12 @@ def rl_forward_progress(env, gain=0.1):
 
 
 def boolean_action_penalty(discrete_actions, gain=1.0):
-    """Penalize boolean actions that indicate a switch"""
+    """Penalize boolean actions that indicate a switch."""
     return gain * np.sum(discrete_actions)
 
 
 def min_delay(env):
-    """A reward function used to encourage minimization of total delay.
+    """Reward function used to encourage minimization of total delay.
 
     This function measures the deviation of a system of vehicles from all the
     vehicles smoothly travelling at a fixed speed to their destinations.
@@ -131,7 +149,7 @@ def min_delay(env):
 
 
 def min_delay_unscaled(env):
-    """The average delay for all vehicles in the system
+    """Return the average delay for all vehicles in the system.
 
     Parameters
     ----------
@@ -160,7 +178,7 @@ def min_delay_unscaled(env):
 
 
 def penalize_standstill(env, gain=1):
-    """A reward function that penalizes vehicle standstill
+    """Reward function that penalizes vehicle standstill.
 
     Is it better for this to be:
         a) penalize standstill in general?
@@ -187,6 +205,22 @@ def penalize_standstill(env, gain=1):
 
 
 def penalize_near_standstill(env, thresh=0.3, gain=1):
+    """Reward function which penalizes vehicles at a low velocity.
+
+    This reward function is used to penalize vehicles below a
+    specified threshold. This assists with discouraging RL from
+    gamifying a scenario, which can result in standstill behavior
+    or similarly bad, near-zero velocities.
+
+    Parameters
+    ----------
+    env : flow.envs.Env
+        the environment variable, which contains information on the current
+    thresh : float
+        the velocity threshold below which penalties are applied
+    gain : float
+        multiplicative factor on the action penalty
+    """
     veh_ids = env.k.vehicle.get_ids()
     vel = np.array(env.k.vehicle.get_speed(veh_ids))
     penalize = len(vel[vel < thresh])
@@ -199,7 +233,7 @@ def penalize_headway_variance(vehicles,
                               normalization=1,
                               penalty_gain=1,
                               penalty_exponent=1):
-    """A reward function used to train rl vehicles to encourage large headways
+    """Reward function used to train rl vehicles to encourage large headways.
 
     Parameters
     ----------

flow/core/util.py

@@ -1,6 +1,5 @@
-"""
-A collection of utility functions for Flow.
-"""
+"""A collection of utility functions for Flow."""
+
 import csv
 import errno
 import os

flow/envs/bottleneck_env.py

@@ -90,7 +90,7 @@
 
 
 class BottleneckEnv(Env):
-    """Abstract bottleneck environment
+    """Abstract bottleneck environment.
 
     This environment is used as a simplified representation of the toll booth
     portion of the bay bridge. Contains ramp meters, and a toll both.
@@ -312,6 +312,7 @@ 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."""
         bottleneck_ids = self.k.vehicle.get_ids_by_edge(['3', '4'])
         if lanes:
             veh_ids = [
@@ -343,7 +344,7 @@ def observation_space(self):
             dtype=np.float32)
 
     def compute_reward(self, rl_actions, **kwargs):
-        """ Outflow rate over last ten seconds normalized to max of 1 """
+        """Outflow rate over last ten seconds normalized to max of 1."""
         reward = self.k.vehicle.get_outflow_rate(10 * self.sim_step) / \
             (2000.0 * self.scaling)
         return reward
@@ -354,8 +355,7 @@ def get_state(self):
 
 
 class BottleNeckAccelEnv(BottleneckEnv):
-    """Environment used to train vehicles to effectively pass through a
-    bottleneck.
+    """Environment used to train vehicles to pass through a bottleneck.
 
     States
         An observation is the edge position, speed, lane, and edge number of
@@ -379,7 +379,7 @@ class BottleNeckAccelEnv(BottleneckEnv):
 
     Termination
         A rollout is terminated once the time horizon is reached.
-   """
+    """
 
     def __init__(self, env_params, sim_params, scenario, simulator='traci'):
         for p in ADDITIONAL_RL_ENV_PARAMS.keys():
@@ -581,7 +581,9 @@ def additional_command(self):
 
 
 class DesiredVelocityEnv(BottleneckEnv):
-    """Environment used to train vehicles to effectively pass through a
+    """DesiredVelocityEnv.
+
+    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