Addressed Eugene's comments

tutorials/tutorial11_traffic_lights.ipynb

@@ -108,7 +108,7 @@
     "## 2. Defining Traffic Light Phases \n",
     "\n",
     "\n",
-    "To start off, we define how SUMO represents traffic light phases. A phase is defined as the states that the traffic lights around an intersection can take. The phase of a typical four-way, traffic-light-controlled intersection is modeled by a string (of length 4, 8, or 12, etc., depending on the type of the signal). \n",
+    "To start off, we define how SUMO represents traffic light phases. A phase is defined as the states that the traffic lights around an intersection can take. The phase of a typical four-way, traffic-light-controlled intersection is modeled by a string (of length 4, 8, or 12, etc., depending on the structure of the intersection). \n",
     "\n",
     "Consider the phase \"GrGr\". Every letter in this phase string (\"G\", \"r\", \"G\", \"r\") corresponds to a signal of an edge in the intersection, in clockwise order (starting from the northbound). Explicitly, the northern and southern edges of the intersection both have a state of \"G\" (green), where the eastern and western edges of the intersection both have a state of \"r\" (red). In this example, the intersection has 4 edges, each edge has one lane, and the only possible direction is going straight. \n",
     "\n",
@@ -127,7 +127,22 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Once the `TrafficLightParams` class is instantiated, traffic lights can be added via the `add` function. One prerequisite of using this function is knowing the node id of any node you intend to manipulate. This information is baked into the experiment's scenario class, as well as the experiment's `nod.xml` file. For the experiment we are using with 2 rows and 3 columns, there are 6 nodes: \"center0\" to \"center5\"."
+    "Once the `TrafficLightParams` class is instantiated, traffic lights can be added via the `add` function. One prerequisite of using this function is knowing the node id of any node you intend to manipulate. This information is baked into the experiment's scenario class, as well as the experiment's `nod.xml` file. For the experiment we are using with 2 rows and 3 columns, there are 6 nodes: \"center0\" to \"center5\". \n",
+    "\n",
+    "This will be the ordering of \"centers\" in our scenario:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    " | | |\n",
+    "-3-4-5-\n",
+    " | | |\n",
+    "-0-1-2-\n",
+    " | | |"
    ]
   },
   {
@@ -149,7 +164,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In this particular example, each of the 6 intersections corresponds to the same set of possible phases; in other words, at any time, all intersections will be at the same phase. You can, however, customize each traffic light node to have different phases."
+    "In this particular example, each of the 6 intersections corresponds to the same set of possible phases; in other words, at any time, all intersections will be at the same phase in this example. "
    ]
   },
   {
@@ -166,6 +181,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "You can, however, customize a scenario in which each traffic light node has different phases. \n",
+    "\n",
     "Following this step, the instance `tl_logic` of `TrafficLightParams` class should be passed into the scenario as element `traffic_lights`."
    ]
   },
@@ -240,14 +257,14 @@
    "source": [
     "For more flexibility than the static traffic lights defined above, and more control than RL-controlled traffic lights, actuated traffic lights are a good option to consider.\n",
     "\n",
-    "To explain the actuated traffic ligjts, we refer to an excerpt from SUMO's documentation: \"SUMO supports gap-based actuated traffic control. This control scheme is common in Germany and works by prolonging traffic phases whenever a continuous stream of traffic is detected. It switches to the next phase after detecting a sufficent time gap between sucessive vehicles. This allows for better distribution of green-time among phases and also affects cycle duration in response to dynamic traffic conditions.\""
+    "To explain the actuated traffic lights, we refer to an excerpt from SUMO's documentation: \"SUMO supports gap-based actuated traffic control. This control scheme is common in Germany and works by prolonging traffic phases whenever a continuous stream of traffic is detected. It switches to the next phase after detecting a sufficent time gap between sucessive vehicles. This allows for better distribution of green-time among phases and also affects cycle duration in response to dynamic traffic conditions.\""
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The difference between phases for static and actuated traffic lights is that actuated traffic light has two additional parameters in `phases`, namely `minDur` and `maxDur`, which describe the allowed range of time durations for each phase.\n",
+    "The difference between phases for static and actuated traffic lights is that actuated traffic light has two additional parameters in `phases`, namely `minDur` and `maxDur`, which describe the allowed range of time durations for each phase. `minDur` is the minimum duration the phase will be held for, and `masDur` is the maximum duration the phase will be held for.\n",
     "\n",
     "In addition to these parameters of `phases` and all the required parameters of static of traffic lights, the following optional parameters are involved. The default values are set by SUMO: \n",
     "\n",
@@ -345,7 +362,7 @@
     "\n",
     "This is where we switch from the non-RL experiment script to the RL experiment. \n",
     "\n",
-    "To control traffic lights via RL, no `tl_logic` element is necessary. This is because rllib is controlling all the parameters you were able to customize in the prior sections. The `additional_net_params` should look something like this: "
+    "To control traffic lights via RL, no `tl_logic` element is necessary. This is because the RL agent is controlling all the parameters you were able to customize in the prior sections. The `additional_net_params` should look something like this: "
    ]
   },
   {
@@ -383,7 +400,8 @@
     "self.last_change = np.zeros((self.rows * self.cols, 1))\n",
     "# keeps track of the direction of the intersection (the direction that is currently being allowed to flow. 0 indicates flow from top to bottom, and 1 indicates flow from left to right.)\n",
     "self.direction = np.zeros((self.rows * self.cols, 1))\n",
-    "# value of 1 indicates that the intersection is in a red-yellow state. 0 indicates that the intersection is in a red-green state.\n",
+    "# value of 1 indicates that the intersection is in a red-yellow state (traffic lights are red for one way (e.g. north-south), while the traffic lights for the other way (e.g. west-east) are yellow\n",
+    ". 0 indicates that the intersection is in a red-green state.\n",
     "self.currently_yellow = np.zeros((self.rows * self.cols, 1))"
    ]
   },
@@ -452,7 +470,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In the case that the action space is discrete, we need 1-bit (that can be 0 or 1) for the action of each traffic light node. Hence, we need `self.num_traffic_lights` bits to represent the action spacs. To make a `self.num_traffic_lights`-bit number, we use the pyhton's `Discrete(range)`, and since we have `self.num_traffic_lights` bits, the `range` will be 2^`self.num_traffic_lights`.\n",
+    "In the case that the action space is discrete, we need 1-bit (that can be 0 or 1) for the action of each traffic light node. Hence, we need `self.num_traffic_lights` bits to represent the action space. To make a `self.num_traffic_lights`-bit number, we use the pyhton's `Discrete(range)`, and since we have `self.num_traffic_lights` bits, the `range` will be 2^`self.num_traffic_lights`.\n",
     "\n",
     "In the case that the action space is continuous, we use a range (that is currently (0,1)) of numbers for each traffic light node. Hence, we will define `self.num_traffic_lights` \"Boxes\", each in the range (0,1). \n",
     "\n",
@@ -470,7 +488,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The observation space may be any set of state information the user wishes to provide to the agent. This information may fully or partially describe the state of the environment. The existing observation space for our existing traffic lights experiments is designed to be a fully observable state space with the following metrics. For each vehicle, we want to know its velocity, its distance (in [unit]) from the next intersection, and the unique edge it is traveling on. For each traffic light, we want to know its current state (i.e. what direction it is flowing), when it last changed, and whether it was yellow. "
+    "The observation space may be any set of state information the user wishes to provide to the agent. This information may fully or partially describe the state of the environment. The existing observation space for this example is designed to be a fully observable state space with the following metrics. For all vehicle, we want to know its velocity, its distance (in [unit]) from the next intersection, and the unique edge it is traveling on. For each traffic light, we want to know its current state (i.e. what direction it is flowing), when it last changed, and whether it was yellow. "
    ]
   },
   {
@@ -504,6 +522,13 @@
     "        return Tuple((speed, dist_to_intersec, edge_num, traffic_lights))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that in the case that the observation space is not fully-observable (e.g. cannot observe all the vehicles in the system), the observation space should be changed to only "
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},