Created
May 17, 2023 07:26
-
-
Save johnleung8888/4922a74d4656c2fca7b59a1bb7cf1f3f to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| { | |
| "cells": [ | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "7784c6aa8890d8f94e327df0e2046c06", | |
| "grade": false, | |
| "grade_id": "cell-772b7b8774cc890e", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "# Assignment 4 - Average Reward Softmax Actor-Critic\n", | |
| "\n", | |
| "Welcome to your Course 3 Programming Assignment 4. In this assignment, you will implement **Average Reward Softmax Actor-Critic** in the Pendulum Swing-Up problem that you have seen earlier in the lecture. Through this assignment you will get hands-on experience in implementing actor-critic methods on a continuing task.\n", | |
| "\n", | |
| "**In this assignment, you will:**\n", | |
| " 1. Implement softmax actor-critic agent on a continuing task using the average reward formulation.\n", | |
| " 2. Understand how to parameterize the policy as a function to learn, in a discrete action environment.\n", | |
| " 3. Understand how to (approximately) sample the gradient of this objective to update the actor.\n", | |
| " 4. Understand how to update the critic using differential TD error.\n" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "49b8848ca28f7c932ea7a55ca5558a32", | |
| "grade": false, | |
| "grade_id": "cell-7c3b4d0ef54cf2bf", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Pendulum Swing-Up Environment\n", | |
| "\n", | |
| "In this assignment, we will be using a Pendulum environment, adapted from [Santamaría et al. (1998)](http://www.incompleteideas.net/papers/SSR-98.pdf). This is also the same environment that we used in the lecture. The diagram below illustrates the environment.\n", | |
| "\n", | |
| "<img src=\"data/pendulum_env.png\" alt=\"Drawing\" style=\"width: 400px;\"/>\n", | |
| "\n", | |
| "The environment consists of single pendulum that can swing 360 degrees. The pendulum is actuated by applying a torque on its pivot point. The goal is to get the pendulum to balance up-right from its resting position (hanging down at the bottom with no velocity) and maintain it as long as possible. The pendulum can move freely, subject only to gravity and the action applied by the agent. \n", | |
| "\n", | |
| "The state is 2-dimensional, which consists of the current angle $\\beta \\in [-\\pi, \\pi]$ (angle from the vertical upright position) and current angular velocity $\\dot{\\beta} \\in (-2\\pi, 2\\pi)$. The angular velocity is constrained in order to avoid damaging the pendulum system. If the angular velocity reaches this limit during simulation, the pendulum is reset to the resting position. \n", | |
| "The action is the angular acceleration, with discrete values $a \\in \\{-1, 0, 1\\}$ applied to the pendulum.\n", | |
| "For more details on environment dynamics you can refer to the original paper.\n", | |
| "\n", | |
| "The goal is to swing-up the pendulum and maintain its upright angle. Hence, the reward is the negative absolute angle from the vertical position: $R_{t} = -|\\beta_{t}|$\n", | |
| "\n", | |
| "Furthermore, since the goal is to reach and maintain a vertical position, there are no terminations nor episodes. Thus this problem can be formulated as a continuing task.\n", | |
| "\n", | |
| "Similar to the Mountain Car task, the action in this pendulum environment is not strong enough to move the pendulum directly to the desired position. The agent must learn to first move the pendulum away from its desired position and gain enough momentum to successfully swing-up the pendulum. And even after reaching the upright position the agent must learn to continually balance the pendulum in this unstable position." | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "053cd6d5d174e9ad5e09566c5b77fb9a", | |
| "grade": false, | |
| "grade_id": "cell-77355b0e578b51a6", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Packages\n", | |
| "\n", | |
| "You will use the following packages in this assignment.\n", | |
| "\n", | |
| "- [numpy](www.numpy.org) : Fundamental package for scientific computing with Python.\n", | |
| "- [matplotlib](http://matplotlib.org) : Library for plotting graphs in Python.\n", | |
| "- [RL-Glue](http://www.jmlr.org/papers/v10/tanner09a.html) : Library for reinforcement learning experiments.\n", | |
| "- [jdc](https://alexhagen.github.io/jdc/) : Jupyter magic that allows defining classes over multiple jupyter notebook cells.\n", | |
| "- [tqdm](https://tqdm.github.io/) : A package to display progress bar when running experiments\n", | |
| "- plot_script : custom script to plot results\n", | |
| "- [tiles3](http://incompleteideas.net/tiles/tiles3.html) : A package that implements tile-coding.\n", | |
| "- pendulum_env : Pendulum Swing-up Environment\n", | |
| "\n", | |
| "**Please do not import other libraries** — this will break the autograder.\n" | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 1, | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "8074478613373060bc01819879f799e1", | |
| "grade": false, | |
| "grade_id": "cell-67bdb1b8185106d1", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [], | |
| "source": [ | |
| "# Do not modify this cell!\n", | |
| "\n", | |
| "# Import necessary libraries\n", | |
| "# DO NOT IMPORT OTHER LIBRARIES - This will break the autograder.\n", | |
| "import numpy as np\n", | |
| "import matplotlib.pyplot as plt\n", | |
| "%matplotlib inline\n", | |
| "\n", | |
| "import os\n", | |
| "import itertools\n", | |
| "from tqdm import tqdm\n", | |
| "\n", | |
| "from rl_glue import RLGlue\n", | |
| "from pendulum_env import PendulumEnvironment\n", | |
| "from agent import BaseAgent\n", | |
| "import plot_script\n", | |
| "import tiles3 as tc" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "ebe67c76b8e7e270a32f544f3fce5040", | |
| "grade": false, | |
| "grade_id": "cell-213dab5e4618e704", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Section 1: Create Tile Coding Helper Function\n", | |
| "\n", | |
| "In this section, we are going to build a tile coding class for our agent that will make it easier to make calls to our tile coder.\n", | |
| "\n", | |
| "Tile-coding is introduced in Section 9.5.4 of the textbook as a way to create features that can both provide good generalization and discrimination. We have already used it in our last programming assignment as well. \n", | |
| "\n", | |
| "Similar to the last programming assignment, we are going to make a function specific for tile coding for our Pendulum Swing-up environment. We will also use the [Tiles3 library](http://incompleteideas.net/tiles/tiles3.html).\n", | |
| "\n", | |
| "To get the tile coder working we need to:\n", | |
| "\n", | |
| " 1) create an index hash table using tc.IHT(), \n", | |
| " 2) scale the inputs for the tile coder based on number of tiles and range of values each input could take\n", | |
| " 3) call tc.tileswrap to get active tiles back.\n", | |
| "\n", | |
| "However, we need to make one small change to this tile coder.\n", | |
| "Note that in this environment the state space contains angle, which is between $[-\\pi, \\pi]$. If we tile-code this state space in the usual way, the agent may think the value of states corresponding to an angle of $-\\pi$ is very different from angle of $\\pi$ when in fact they are the same! To remedy this and allow generalization between angle $= -\\pi$ and angle $= \\pi$, we need to use **wrap tile coder**.\n", | |
| "\n", | |
| "The usage of wrap tile coder is almost identical to the original tile coder, except that we also need to provide the `wrapwidth` argument for the dimension we want to wrap over (hence only for angle, and `None` for angular velocity). More details of wrap tile coder is also provided in [Tiles3 library](http://incompleteideas.net/tiles/tiles3.html).\n" | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 2, | |
| "metadata": { | |
| "deletable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "c7798475f36f714545d25cc19324b8d6", | |
| "grade": false, | |
| "grade_id": "cell-0aea119ff5ad24aa", | |
| "locked": false, | |
| "schema_version": 3, | |
| "solution": true, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [], | |
| "source": [ | |
| "# -----------\n", | |
| "# Graded Cell\n", | |
| "# -----------\n", | |
| "class PendulumTileCoder:\n", | |
| " def __init__(self, iht_size=4096, num_tilings=32, num_tiles=8):\n", | |
| " \"\"\"\n", | |
| " Initializes the MountainCar Tile Coder\n", | |
| " Initializers:\n", | |
| " iht_size -- int, the size of the index hash table, typically a power of 2\n", | |
| " num_tilings -- int, the number of tilings\n", | |
| " num_tiles -- int, the number of tiles. Here both the width and height of the tiles are the same\n", | |
| " \n", | |
| " Class Variables:\n", | |
| " self.iht -- tc.IHT, the index hash table that the tile coder will use\n", | |
| " self.num_tilings -- int, the number of tilings the tile coder will use\n", | |
| " self.num_tiles -- int, the number of tiles the tile coder will use\n", | |
| " \"\"\"\n", | |
| " \n", | |
| " self.num_tilings = num_tilings\n", | |
| " self.num_tiles = num_tiles \n", | |
| " self.iht = tc.IHT(iht_size)\n", | |
| " \n", | |
| " def get_tiles(self, angle, ang_vel):\n", | |
| " \"\"\"\n", | |
| " Takes in an angle and angular velocity from the pendulum environment\n", | |
| " and returns a numpy array of active tiles.\n", | |
| " \n", | |
| " Arguments:\n", | |
| " angle -- float, the angle of the pendulum between -np.pi and np.pi\n", | |
| " ang_vel -- float, the angular velocity of the agent between -2*np.pi and 2*np.pi\n", | |
| " \n", | |
| " returns:\n", | |
| " tiles -- np.array, active tiles\n", | |
| " \n", | |
| " \"\"\"\n", | |
| " \n", | |
| " ### Use the ranges above and scale the angle and angular velocity between [0, 1]\n", | |
| " # then multiply by the number of tiles so they are scaled between [0, self.num_tiles]\n", | |
| " \n", | |
| " angle_scaled = 0\n", | |
| " ang_vel_scaled = 0\n", | |
| " \n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " angle_scaled = (angle-(-np.pi))/(np.pi-(-np.pi)) * self.num_tiles\n", | |
| " ang_vel_scaled = (ang_vel-(-2*np.pi))/(2*np.pi-(-2*np.pi)) * self.num_tiles\n", | |
| " # ----------------\n", | |
| " \n", | |
| " # Get tiles by calling tc.tileswrap method\n", | |
| " # wrapwidths specify which dimension to wrap over and its wrapwidth\n", | |
| " tiles = tc.tileswrap(self.iht, self.num_tilings, [angle_scaled, ang_vel_scaled], wrapwidths=[self.num_tiles, False])\n", | |
| " \n", | |
| " return np.array(tiles)" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "7a4fa9bdb9dc9e4475a08b429a512fa1", | |
| "grade": false, | |
| "grade_id": "cell-d7ec813a92c7a24a", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "Run the following code to verify `PendulumTilecoder`" | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 3, | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "3dec4aa9b5d293b1d3f1809f58e68625", | |
| "grade": true, | |
| "grade_id": "cell-25f642d5c07d3914", | |
| "locked": true, | |
| "points": 10, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [], | |
| "source": [ | |
| "# -----------\n", | |
| "# Tested Cell\n", | |
| "# -----------\n", | |
| "# The contents of the cell will be tested by the autograder.\n", | |
| "# If they do not pass here, they will not pass there.\n", | |
| "\n", | |
| "## Test Code for PendulumTileCoder ##\n", | |
| "# Your tile coder should also work for other num. tilings and num. tiles\n", | |
| "angles = np.linspace(-np.pi, np.pi, num=5)\n", | |
| "vels = np.linspace(-2 * np.pi, 2 * np.pi, num=5)\n", | |
| "test_obs = list(itertools.product(angles, vels))\n", | |
| "\n", | |
| "pdtc = PendulumTileCoder(iht_size=4096, num_tilings=8, num_tiles=2)\n", | |
| "\n", | |
| "result=[]\n", | |
| "for obs in test_obs:\n", | |
| " angle, ang_vel = obs\n", | |
| " tiles = pdtc.get_tiles(angle=angle, ang_vel=ang_vel)\n", | |
| " result.append(tiles)\n", | |
| " \n", | |
| "expected = np.array([\n", | |
| " [0, 1, 2, 3, 4, 5, 6, 7],\n", | |
| " [0, 1, 8, 3, 9, 10, 6, 11],\n", | |
| " [12, 13, 8, 14, 9, 10, 15, 11],\n", | |
| " [12, 13, 16, 14, 17, 18, 15, 19],\n", | |
| " [20, 21, 16, 22, 17, 18, 23, 19],\n", | |
| " [0, 1, 2, 3, 24, 25, 26, 27],\n", | |
| " [0, 1, 8, 3, 28, 29, 26, 30],\n", | |
| " [12, 13, 8, 14, 28, 29, 31, 30],\n", | |
| " [12, 13, 16, 14, 32, 33, 31, 34],\n", | |
| " [20, 21, 16, 22, 32, 33, 35, 34],\n", | |
| " [36, 37, 38, 39, 24, 25, 26, 27],\n", | |
| " [36, 37, 40, 39, 28, 29, 26, 30],\n", | |
| " [41, 42, 40, 43, 28, 29, 31, 30],\n", | |
| " [41, 42, 44, 43, 32, 33, 31, 34],\n", | |
| " [45, 46, 44, 47, 32, 33, 35, 34],\n", | |
| " [36, 37, 38, 39, 4, 5, 6, 7],\n", | |
| " [36, 37, 40, 39, 9, 10, 6, 11],\n", | |
| " [41, 42, 40, 43, 9, 10, 15, 11],\n", | |
| " [41, 42, 44, 43, 17, 18, 15, 19],\n", | |
| " [45, 46, 44, 47, 17, 18, 23, 19],\n", | |
| " [0, 1, 2, 3, 4, 5, 6, 7],\n", | |
| " [0, 1, 8, 3, 9, 10, 6, 11],\n", | |
| " [12, 13, 8, 14, 9, 10, 15, 11],\n", | |
| " [12, 13, 16, 14, 17, 18, 15, 19],\n", | |
| " [20, 21, 16, 22, 17, 18, 23, 19],\n", | |
| "])\n", | |
| "\n", | |
| "assert np.all(expected == np.array(result))" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "a454a99deb0ebf93f1211d1c9018d743", | |
| "grade": false, | |
| "grade_id": "cell-3137acdcbbf1cfc7", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Section 2: Create Average Reward Softmax Actor-Critic Agent\n", | |
| "\n", | |
| "Now that we implemented PendulumTileCoder let's create the agent that interacts with the environment. We will implement the same average reward Actor-Critic algorithm presented in the videos.\n", | |
| "\n", | |
| "This agent has two components: an Actor and a Critic. The Actor learns a parameterized policy while the Critic learns a state-value function. The environment has discrete actions; your Actor implementation will use a softmax policy with exponentiated action-preferences. The Actor learns with the sample-based estimate for the gradient of the average reward objective. The Critic learns using the average reward version of the semi-gradient TD(0) algorithm.\n", | |
| "\n", | |
| "In this section, you will be implementing `agent_policy`, `agent_start`, `agent_step`, and `agent_end`." | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "a4b30aeca061c0e8fffd2b9015e8af6a", | |
| "grade": false, | |
| "grade_id": "cell-517fd83fc10c06b2", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Section 2-1: Implement Helper Functions\n", | |
| "\n", | |
| "Let's first define a couple of useful helper functions." | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "303cb299c47dbf6eddf5416b76587574", | |
| "grade": false, | |
| "grade_id": "cell-4a214ace7fefd6d7", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Section 2-1a: Compute Softmax Probability\n", | |
| "\n", | |
| "In this part you will implement `compute_softmax_prob`.\n", | |
| "\n", | |
| "This function computes softmax probability for all actions, given actor weights `actor_w` and active tiles `tiles`. This function will be later used in `agent_policy` to sample appropriate action.\n", | |
| "\n", | |
| "First, recall how the softmax policy is represented from state-action preferences: $\\large \\pi(a|s, \\mathbf{\\theta}) \\doteq \\frac{e^{h(s,a,\\mathbf{\\theta})}}{\\sum_{b}e^{h(s,b,\\mathbf{\\theta})}}$.\n", | |
| "\n", | |
| "**state-action preference** is defined as $h(s,a, \\mathbf{\\theta}) \\doteq \\mathbf{\\theta}^T \\mathbf{x}_h(s,a)$.\n", | |
| "\n", | |
| "Given active tiles `tiles` for state `s`, state-action preference $\\mathbf{\\theta}^T \\mathbf{x}_h(s,a)$ can be computed by `actor_w[a][tiles].sum()`.\n", | |
| "\n", | |
| "We will also use **exp-normalize trick**, in order to avoid possible numerical overflow. \n", | |
| "Consider the following:\n", | |
| "\n", | |
| "$\\large \\pi(a|s, \\mathbf{\\theta}) \\doteq \\frac{e^{h(s,a,\\mathbf{\\theta})}}{\\sum_{b}e^{h(s,b,\\mathbf{\\theta})}} = \\frac{e^{h(s,a,\\mathbf{\\theta}) - c} e^c}{\\sum_{b}e^{h(s,b,\\mathbf{\\theta}) - c} e^c} = \\frac{e^{h(s,a,\\mathbf{\\theta}) - c}}{\\sum_{b}e^{h(s,b,\\mathbf{\\theta}) - c}}$ \n", | |
| "\n", | |
| "$\\pi(\\cdot|s, \\mathbf{\\theta})$ is shift-invariant, and the policy remains the same when we subtract a constant $c \\in \\mathbb{R}$ from state-action preferences.\n", | |
| "\n", | |
| "Normally we use $c = \\max_b h(s,b, \\mathbf{\\theta})$, to prevent any overflow due to exponentiating large numbers." | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 4, | |
| "metadata": { | |
| "deletable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "9359abf8f5989b07767b67e08a051cf8", | |
| "grade": false, | |
| "grade_id": "cell-8e687ecd856dcacd", | |
| "locked": false, | |
| "schema_version": 3, | |
| "solution": true, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [], | |
| "source": [ | |
| "# -----------\n", | |
| "# Graded Cell\n", | |
| "# -----------\n", | |
| "\n", | |
| "def compute_softmax_prob(actor_w, tiles):\n", | |
| " \"\"\"\n", | |
| " Computes softmax probability for all actions\n", | |
| " \n", | |
| " Args:\n", | |
| " actor_w - np.array, an array of actor weights\n", | |
| " tiles - np.array, an array of active tiles\n", | |
| " \n", | |
| " Returns:\n", | |
| " softmax_prob - np.array, an array of size equal to num. actions, and sums to 1.\n", | |
| " \"\"\"\n", | |
| " \n", | |
| " # First compute the list of state-action preferences (1~2 lines)\n", | |
| " # state_action_preferences = ? (list of size 3)\n", | |
| " state_action_preferences = []\n", | |
| " softmax_prob = []\n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " for i in range(num_actions):\n", | |
| " state_action_preferences.append(actor_w[i][tiles].sum())\n", | |
| " # ----------------\n", | |
| " \n", | |
| " # Set the constant c by finding the maximum of state-action preferences (use np.max) (1 line)\n", | |
| " # c = ? (float)\n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " c = np.max(state_action_preferences)\n", | |
| " # ----------------\n", | |
| " \n", | |
| " # Compute the numerator by subtracting c from state-action preferences and exponentiating it (use np.exp) (1 line)\n", | |
| " # numerator = ? (list of size 3)\n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " numerator = np.exp(state_action_preferences - c)\n", | |
| " # ----------------\n", | |
| " \n", | |
| " # Next compute the denominator by summing the values in the numerator (use np.sum) (1 line)\n", | |
| " # denominator = ? (float)\n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " denominator = np.sum(numerator)\n", | |
| " # ----------------\n", | |
| " \n", | |
| " \n", | |
| " # Create a probability array by dividing each element in numerator array by denominator (1 line)\n", | |
| " # We will store this probability array in self.softmax_prob as it will be useful later when updating the Actor\n", | |
| " # softmax_prob = ? (list of size 3)\n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " for j in numerator:\n", | |
| " softmax_prob.append(j/denominator)\n", | |
| " # ----------------\n", | |
| " \n", | |
| " return softmax_prob" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "761889b9695a5cae6f27e56d57bd9bcf", | |
| "grade": false, | |
| "grade_id": "cell-42024f3263f17369", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "Run the following code to verify `compute_softmax_prob`.\n", | |
| "\n", | |
| "We will test the method by building a softmax policy from state-action preferences [-1,1,2].\n", | |
| "\n", | |
| "The sampling probability should then roughly match $[\\frac{e^{-1}}{e^{-1}+e^1+e^2}, \\frac{e^{1}}{e^{-1}+e^1+e^2}, \\frac{e^2}{e^{-1}+e^1+e^2}] \\approx$ [0.0351, 0.2595, 0.7054]" | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 5, | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "c029cf63786e01653c60f7b2130fbba2", | |
| "grade": true, | |
| "grade_id": "cell-b27241568a857869", | |
| "locked": true, | |
| "points": 10, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [ | |
| { | |
| "name": "stdout", | |
| "output_type": "stream", | |
| "text": [ | |
| "softmax probability: [0.03511902695933972, 0.2594964603424191, 0.7053845126982411]\n" | |
| ] | |
| } | |
| ], | |
| "source": [ | |
| "# -----------\n", | |
| "# Tested Cell\n", | |
| "# -----------\n", | |
| "# The contents of the cell will be tested by the autograder.\n", | |
| "# If they do not pass here, they will not pass there.\n", | |
| "\n", | |
| "# set tile-coder\n", | |
| "iht_size = 4096\n", | |
| "num_tilings = 8\n", | |
| "num_tiles = 8\n", | |
| "test_tc = PendulumTileCoder(iht_size=iht_size, num_tilings=num_tilings, num_tiles=num_tiles)\n", | |
| "\n", | |
| "num_actions = 3\n", | |
| "actions = list(range(num_actions))\n", | |
| "actor_w = np.zeros((len(actions), iht_size))\n", | |
| "\n", | |
| "# setting actor weights such that state-action preferences are always [-1, 1, 2]\n", | |
| "actor_w[0] = -1./num_tilings\n", | |
| "actor_w[1] = 1./num_tilings\n", | |
| "actor_w[2] = 2./num_tilings\n", | |
| "\n", | |
| "# obtain active_tiles from state\n", | |
| "state = [-np.pi, 0.]\n", | |
| "angle, ang_vel = state\n", | |
| "active_tiles = test_tc.get_tiles(angle, ang_vel)\n", | |
| "\n", | |
| "# compute softmax probability\n", | |
| "softmax_prob = compute_softmax_prob(actor_w, active_tiles) \n", | |
| "print('softmax probability: {}'.format(softmax_prob))\n", | |
| "\n", | |
| "assert np.allclose(softmax_prob, [0.03511903, 0.25949646, 0.70538451])" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "4615f9dd8c5d414de6c4486197d0cf16", | |
| "grade": false, | |
| "grade_id": "cell-7d31bba88af1cbaf", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Section 2-2: Implement Agent Methods\n", | |
| "\n", | |
| "Let's first define methods that initialize the agent. `agent_init()` initializes all the variables that the agent will need.\n", | |
| "\n", | |
| "Now that we have implemented helper functions, let's create an agent. In this part, you will implement `agent_start()` and `agent_step()`. We do not need to implement `agent_end()` because there is no termination in our continuing task. \n", | |
| "\n", | |
| "`compute_softmax_prob()` is used in `agent_policy()`, which in turn will be used in `agent_start()` and `agent_step()`. We have implemented `agent_policy()` for you.\n", | |
| "\n", | |
| "When performing updates to the Actor and Critic, recall their respective updates in the Actor-Critic algorithm video.\n", | |
| "\n", | |
| "We approximate $q_\\pi$ in the Actor update using one-step bootstrapped return($R_{t+1} - \\bar{R} + \\hat{v}(S_{t+1}, \\mathbf{w})$) subtracted by current state-value($\\hat{v}(S_{t}, \\mathbf{w})$), equivalent to TD error $\\delta$.\n", | |
| "\n", | |
| "$\\delta_t = R_{t+1} - \\bar{R} + \\hat{v}(S_{t+1}, \\mathbf{w}) - \\hat{v}(S_{t}, \\mathbf{w}) \\hspace{6em} (1)$\n", | |
| "\n", | |
| "**Average Reward update rule**: $\\bar{R} \\leftarrow \\bar{R} + \\alpha^{\\bar{R}}\\delta \\hspace{4.3em} (2)$\n", | |
| "\n", | |
| "**Critic weight update rule**: $\\mathbf{w} \\leftarrow \\mathbf{w} + \\alpha^{\\mathbf{w}}\\delta\\nabla \\hat{v}(s,\\mathbf{w}) \\hspace{2.5em} (3)$\n", | |
| "\n", | |
| "**Actor weight update rule**: $\\mathbf{\\theta} \\leftarrow \\mathbf{\\theta} + \\alpha^{\\mathbf{\\theta}}\\delta\\nabla ln \\pi(A|S,\\mathbf{\\theta}) \\hspace{1.4em} (4)$\n", | |
| "\n", | |
| "\n", | |
| "However, since we are using linear function approximation and parameterizing a softmax policy, the above update rule can be further simplified using:\n", | |
| "\n", | |
| "$\\nabla \\hat{v}(s,\\mathbf{w}) = \\mathbf{x}(s) \\hspace{14.2em} (5)$\n", | |
| "\n", | |
| "$\\nabla ln \\pi(A|S,\\mathbf{\\theta}) = \\mathbf{x}_h(s,a) - \\sum_b \\pi(b|s, \\mathbf{\\theta})\\mathbf{x}_h(s,b) \\hspace{3.3em} (6)$\n" | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 6, | |
| "metadata": { | |
| "deletable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "7d2aa6794604c259643d6bad07cc6b6f", | |
| "grade": false, | |
| "grade_id": "cell-1a5afc4aed047144", | |
| "locked": false, | |
| "schema_version": 3, | |
| "solution": true, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [], | |
| "source": [ | |
| "# -----------\n", | |
| "# Graded Cell\n", | |
| "# -----------\n", | |
| "\n", | |
| "class ActorCriticSoftmaxAgent(BaseAgent): \n", | |
| " def __init__(self):\n", | |
| " self.rand_generator = None\n", | |
| "\n", | |
| " self.actor_step_size = None\n", | |
| " self.critic_step_size = None\n", | |
| " self.avg_reward_step_size = None\n", | |
| "\n", | |
| " self.tc = None\n", | |
| "\n", | |
| " self.avg_reward = None\n", | |
| " self.critic_w = None\n", | |
| " self.actor_w = None\n", | |
| "\n", | |
| " self.actions = None\n", | |
| "\n", | |
| " self.softmax_prob = None\n", | |
| " self.prev_tiles = None\n", | |
| " self.last_action = None\n", | |
| " \n", | |
| " def agent_init(self, agent_info={}):\n", | |
| " \"\"\"Setup for the agent called when the experiment first starts.\n", | |
| "\n", | |
| " Set parameters needed to setup the semi-gradient TD(0) state aggregation agent.\n", | |
| "\n", | |
| " Assume agent_info dict contains:\n", | |
| " {\n", | |
| " \"iht_size\": int\n", | |
| " \"num_tilings\": int,\n", | |
| " \"num_tiles\": int,\n", | |
| " \"actor_step_size\": float,\n", | |
| " \"critic_step_size\": float,\n", | |
| " \"avg_reward_step_size\": float,\n", | |
| " \"num_actions\": int,\n", | |
| " \"seed\": int\n", | |
| " }\n", | |
| " \"\"\"\n", | |
| "\n", | |
| " # set random seed for each run\n", | |
| " self.rand_generator = np.random.RandomState(agent_info.get(\"seed\")) \n", | |
| "\n", | |
| " iht_size = agent_info.get(\"iht_size\")\n", | |
| " num_tilings = agent_info.get(\"num_tilings\")\n", | |
| " num_tiles = agent_info.get(\"num_tiles\")\n", | |
| "\n", | |
| " # initialize self.tc to the tile coder we created\n", | |
| " self.tc = PendulumTileCoder(iht_size=iht_size, num_tilings=num_tilings, num_tiles=num_tiles)\n", | |
| "\n", | |
| " # set step-size accordingly (we normally divide actor and critic step-size by num. tilings (p.217-218 of textbook))\n", | |
| " self.actor_step_size = agent_info.get(\"actor_step_size\")/num_tilings\n", | |
| " self.critic_step_size = agent_info.get(\"critic_step_size\")/num_tilings\n", | |
| " self.avg_reward_step_size = agent_info.get(\"avg_reward_step_size\")\n", | |
| "\n", | |
| " self.actions = list(range(agent_info.get(\"num_actions\")))\n", | |
| "\n", | |
| " # Set initial values of average reward, actor weights, and critic weights\n", | |
| " # We initialize actor weights to three times the iht_size. \n", | |
| " # Recall this is because we need to have one set of weights for each of the three actions.\n", | |
| " self.avg_reward = 0.0\n", | |
| " self.actor_w = np.zeros((len(self.actions), iht_size))\n", | |
| " self.critic_w = np.zeros(iht_size)\n", | |
| "\n", | |
| " self.softmax_prob = None\n", | |
| " self.prev_tiles = None\n", | |
| " self.last_action = None\n", | |
| " \n", | |
| " def agent_policy(self, active_tiles):\n", | |
| " \"\"\" policy of the agent\n", | |
| " Args:\n", | |
| " active_tiles (Numpy array): active tiles returned by tile coder\n", | |
| " \n", | |
| " Returns:\n", | |
| " The action selected according to the policy\n", | |
| " \"\"\"\n", | |
| " \n", | |
| " # compute softmax probability\n", | |
| " softmax_prob = compute_softmax_prob(self.actor_w, active_tiles)\n", | |
| " \n", | |
| " # Sample action from the softmax probability array\n", | |
| " # self.rand_generator.choice() selects an element from the array with the specified probability\n", | |
| " chosen_action = self.rand_generator.choice(self.actions, p=softmax_prob)\n", | |
| " \n", | |
| " # save softmax_prob as it will be useful later when updating the Actor\n", | |
| " self.softmax_prob = softmax_prob\n", | |
| " \n", | |
| " return chosen_action\n", | |
| "\n", | |
| " def agent_start(self, state):\n", | |
| " \"\"\"The first method called when the experiment starts, called after\n", | |
| " the environment starts.\n", | |
| " Args:\n", | |
| " state (Numpy array): the state from the environment's env_start function.\n", | |
| " Returns:\n", | |
| " The first action the agent takes.\n", | |
| " \"\"\"\n", | |
| "\n", | |
| " angle, ang_vel = state\n", | |
| "\n", | |
| " ### Use self.tc to get active_tiles using angle and ang_vel (2 lines)\n", | |
| " # set current_action by calling self.agent_policy with active_tiles\n", | |
| " # active_tiles = ?\n", | |
| " # current_action = ?\n", | |
| "\n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " active_tiles = self.tc.get_tiles(angle, ang_vel)\n", | |
| " current_action = self.agent_policy(active_tiles)\n", | |
| " # ----------------\n", | |
| "\n", | |
| " self.last_action = current_action\n", | |
| " self.prev_tiles = np.copy(active_tiles)\n", | |
| " \n", | |
| "\n", | |
| " return self.last_action\n", | |
| "\n", | |
| "\n", | |
| " def agent_step(self, reward, state):\n", | |
| " \"\"\"A step taken by the agent.\n", | |
| " Args:\n", | |
| " reward (float): the reward received for taking the last action taken\n", | |
| " state (Numpy array): the state from the environment's step based on \n", | |
| " where the agent ended up after the\n", | |
| " last step.\n", | |
| " Returns:\n", | |
| " The action the agent is taking.\n", | |
| " \"\"\"\n", | |
| "\n", | |
| " angle, ang_vel = state\n", | |
| "\n", | |
| " ### Use self.tc to get active_tiles using angle and ang_vel (1 line)\n", | |
| " # active_tiles = ? \n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " active_tiles = self.tc.get_tiles(angle, ang_vel)\n", | |
| " # ----------------\n", | |
| "\n", | |
| " ### Compute delta using Equation (1) (1 line)\n", | |
| " # delta = ?\n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " current_action_value = self.critic_w[active_tiles].sum()\n", | |
| " last_action_value = self.critic_w[self.prev_tiles].sum()\n", | |
| " delta = reward - self.avg_reward + current_action_value - last_action_value\n", | |
| " # ----------------\n", | |
| "\n", | |
| " ### update average reward using Equation (2) (1 line)\n", | |
| " # self.avg_reward += ?\n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " self.avg_reward += self.avg_reward_step_size * delta\n", | |
| " # ----------------\n", | |
| "\n", | |
| " # update critic weights using Equation (3) and (5) (1 line)\n", | |
| " # self.critic_w[self.prev_tiles] += ?\n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " xs = np.zeros_like(self.critic_w)\n", | |
| " #print(xs)\n", | |
| " xs[self.prev_tiles]=1\n", | |
| " #print(xs)\n", | |
| " \n", | |
| " self.critic_w[self.prev_tiles] += self.critic_step_size * delta * xs[self.prev_tiles]\n", | |
| " # ----------------\n", | |
| "\n", | |
| " # update actor weights using Equation (4) and (6)\n", | |
| " # We use self.softmax_prob saved from the previous timestep\n", | |
| " # We leave it as an exercise to verify that the code below corresponds to the equation.\n", | |
| " for a in self.actions:\n", | |
| " if a == self.last_action:\n", | |
| " self.actor_w[a][self.prev_tiles] += self.actor_step_size * delta * (1 - self.softmax_prob[a])\n", | |
| " else:\n", | |
| " self.actor_w[a][self.prev_tiles] += self.actor_step_size * delta * (0 - self.softmax_prob[a])\n", | |
| "\n", | |
| " ### set current_action by calling self.agent_policy with active_tiles (1 line)\n", | |
| " # current_action = ? \n", | |
| " # ----------------\n", | |
| " # your code here\n", | |
| " current_action = self.agent_policy(active_tiles)\n", | |
| " # ----------------\n", | |
| "\n", | |
| " self.prev_tiles = active_tiles\n", | |
| " self.last_action = current_action\n", | |
| "\n", | |
| " return self.last_action\n", | |
| "\n", | |
| "\n", | |
| " def agent_message(self, message):\n", | |
| " if message == 'get avg reward':\n", | |
| " return self.avg_reward\n" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "a1433cfb90cce3e1fd4183cb96150aca", | |
| "grade": false, | |
| "grade_id": "cell-fad2d97e598fa22a", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "Run the following code to verify `agent_start()`.\n", | |
| "Although there is randomness due to `self.rand_generator.choice()` in `agent_policy()`, we control the seed so your output should match the expected output. " | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 7, | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "bc38580596ba40adffc54281e60f990b", | |
| "grade": true, | |
| "grade_id": "cell-a7d7210fe9299556", | |
| "locked": true, | |
| "points": 5, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [ | |
| { | |
| "name": "stdout", | |
| "output_type": "stream", | |
| "text": [ | |
| "agent active_tiles: [0 1 2 3 4 5 6 7]\n", | |
| "agent selected action: 2\n" | |
| ] | |
| } | |
| ], | |
| "source": [ | |
| "# -----------\n", | |
| "# Tested Cell\n", | |
| "# -----------\n", | |
| "# The contents of the cell will be tested by the autograder.\n", | |
| "# If they do not pass here, they will not pass there.\n", | |
| "\n", | |
| "agent_info = {\n", | |
| " \"iht_size\": 4096,\n", | |
| " \"num_tilings\": 8,\n", | |
| " \"num_tiles\": 8,\n", | |
| " \"actor_step_size\": 1e-1,\n", | |
| " \"critic_step_size\": 1e-0,\n", | |
| " \"avg_reward_step_size\": 1e-2,\n", | |
| " \"num_actions\": 3,\n", | |
| " \"seed\": 99,\n", | |
| "}\n", | |
| "\n", | |
| "test_agent = ActorCriticSoftmaxAgent()\n", | |
| "test_agent.agent_init(agent_info)\n", | |
| "\n", | |
| "state = [-np.pi, 0.]\n", | |
| "\n", | |
| "test_agent.agent_start(state)\n", | |
| "\n", | |
| "assert np.all(test_agent.prev_tiles == [0, 1, 2, 3, 4, 5, 6, 7])\n", | |
| "assert test_agent.last_action == 2\n", | |
| "\n", | |
| "print(\"agent active_tiles: {}\".format(test_agent.prev_tiles))\n", | |
| "print(\"agent selected action: {}\".format(test_agent.last_action))\n" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "fba7f24b5227e2b1ec26b3c8a4a36956", | |
| "grade": false, | |
| "grade_id": "cell-ac39ccab6b2747e4", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "Run the following code to verify `agent_step()`" | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 8, | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "331d10b308ac8e4820239ada569bbd29", | |
| "grade": true, | |
| "grade_id": "cell-f53c4c744932d219", | |
| "locked": true, | |
| "points": 10, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [ | |
| { | |
| "name": "stdout", | |
| "output_type": "stream", | |
| "text": [ | |
| "agent next_action: 1\n", | |
| "agent avg reward: -0.03139092653589793\n", | |
| "\n", | |
| "agent first 10 values of actor weights[0]: \n", | |
| "[0.01307955 0.01307955 0.01307955 0.01307955 0.01307955 0.01307955\n", | |
| " 0.01307955 0.01307955 0. 0. ]\n", | |
| "\n", | |
| "agent first 10 values of actor weights[1]: \n", | |
| "[0.01307955 0.01307955 0.01307955 0.01307955 0.01307955 0.01307955\n", | |
| " 0.01307955 0.01307955 0. 0. ]\n", | |
| "\n", | |
| "agent first 10 values of actor weights[2]: \n", | |
| "[-0.02615911 -0.02615911 -0.02615911 -0.02615911 -0.02615911 -0.02615911\n", | |
| " -0.02615911 -0.02615911 0. 0. ]\n", | |
| "\n", | |
| "agent first 10 values of critic weights: \n", | |
| "[-0.39238658 -0.39238658 -0.39238658 -0.39238658 -0.39238658 -0.39238658\n", | |
| " -0.39238658 -0.39238658 0. 0. ]\n" | |
| ] | |
| } | |
| ], | |
| "source": [ | |
| "# -----------\n", | |
| "# Tested Cell\n", | |
| "# -----------\n", | |
| "# The contents of the cell will be tested by the autograder.\n", | |
| "# If they do not pass here, they will not pass there.\n", | |
| "\n", | |
| "# Make sure agent_start() and agent_policy() are working correctly first.\n", | |
| "# agent_step() should work correctly for other arbitrary state transitions in addition to this test case.\n", | |
| "\n", | |
| "env_info = {\"seed\": 99}\n", | |
| "agent_info = {\n", | |
| " \"iht_size\": 4096,\n", | |
| " \"num_tilings\": 8,\n", | |
| " \"num_tiles\": 8,\n", | |
| " \"actor_step_size\": 1e-1,\n", | |
| " \"critic_step_size\": 1e-0,\n", | |
| " \"avg_reward_step_size\": 1e-2,\n", | |
| " \"num_actions\": 3,\n", | |
| " \"seed\": 99,\n", | |
| "}\n", | |
| "\n", | |
| "rl_glue = RLGlue(PendulumEnvironment, ActorCriticSoftmaxAgent)\n", | |
| "rl_glue.rl_init(agent_info, env_info)\n", | |
| "\n", | |
| "# start env/agent\n", | |
| "rl_glue.rl_start()\n", | |
| "rl_glue.rl_step()\n", | |
| "\n", | |
| "# simple alias\n", | |
| "agent = rl_glue.agent\n", | |
| "\n", | |
| "print(\"agent next_action: {}\".format(agent.last_action))\n", | |
| "print(\"agent avg reward: {}\\n\".format(agent.avg_reward))\n", | |
| "\n", | |
| "assert agent.last_action == 1\n", | |
| "assert agent.avg_reward == -0.03139092653589793\n", | |
| "\n", | |
| "print(\"agent first 10 values of actor weights[0]: \\n{}\\n\".format(agent.actor_w[0][:10]))\n", | |
| "print(\"agent first 10 values of actor weights[1]: \\n{}\\n\".format(agent.actor_w[1][:10]))\n", | |
| "print(\"agent first 10 values of actor weights[2]: \\n{}\\n\".format(agent.actor_w[2][:10]))\n", | |
| "print(\"agent first 10 values of critic weights: \\n{}\".format(agent.critic_w[:10]))\n", | |
| "\n", | |
| "assert np.allclose(agent.actor_w[0][:10], [0.01307955, 0.01307955, 0.01307955, 0.01307955, 0.01307955, 0.01307955, 0.01307955, 0.01307955, 0., 0.])\n", | |
| "assert np.allclose(agent.actor_w[1][:10], [0.01307955, 0.01307955, 0.01307955, 0.01307955, 0.01307955, 0.01307955, 0.01307955, 0.01307955, 0., 0.])\n", | |
| "assert np.allclose(agent.actor_w[2][:10], [-0.02615911, -0.02615911, -0.02615911, -0.02615911, -0.02615911, -0.02615911, -0.02615911, -0.02615911, 0., 0.])\n", | |
| "\n", | |
| "assert np.allclose(agent.critic_w[:10], [-0.39238658, -0.39238658, -0.39238658, -0.39238658, -0.39238658, -0.39238658, -0.39238658, -0.39238658, 0., 0.])" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "34b54ca88f769153b50bb9cf7a41b249", | |
| "grade": false, | |
| "grade_id": "cell-bac2950fd815375d", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Section 3: Run Experiment\n", | |
| "\n", | |
| "Now that we've implemented all the components of environment and agent, let's run an experiment! \n", | |
| "We want to see whether our agent is successful at learning the optimal policy of balancing the pendulum upright. We will plot total return over time, as well as the exponential average of the reward over time. We also do multiple runs in order to be confident about our results. \n", | |
| "\n", | |
| "The experiment/plot code is provided in the cell below." | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 9, | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "f5091c85ef2c69a7dc5992f593acc4d9", | |
| "grade": false, | |
| "grade_id": "cell-8d55fd86b9fc3769", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [], | |
| "source": [ | |
| "# ---------------\n", | |
| "# Discussion Cell\n", | |
| "# ---------------\n", | |
| "\n", | |
| "# Define function to run experiment\n", | |
| "def run_experiment(environment, agent, environment_parameters, agent_parameters, experiment_parameters):\n", | |
| "\n", | |
| " rl_glue = RLGlue(environment, agent)\n", | |
| " \n", | |
| " # sweep agent parameters\n", | |
| " for num_tilings in agent_parameters['num_tilings']:\n", | |
| " for num_tiles in agent_parameters[\"num_tiles\"]:\n", | |
| " for actor_ss in agent_parameters[\"actor_step_size\"]:\n", | |
| " for critic_ss in agent_parameters[\"critic_step_size\"]:\n", | |
| " for avg_reward_ss in agent_parameters[\"avg_reward_step_size\"]:\n", | |
| " \n", | |
| " env_info = {}\n", | |
| " agent_info = {\"num_tilings\": num_tilings,\n", | |
| " \"num_tiles\": num_tiles,\n", | |
| " \"actor_step_size\": actor_ss,\n", | |
| " \"critic_step_size\": critic_ss,\n", | |
| " \"avg_reward_step_size\": avg_reward_ss,\n", | |
| " \"num_actions\": agent_parameters[\"num_actions\"],\n", | |
| " \"iht_size\": agent_parameters[\"iht_size\"]} \n", | |
| " \n", | |
| " # results to save\n", | |
| " return_per_step = np.zeros((experiment_parameters[\"num_runs\"], experiment_parameters[\"max_steps\"]))\n", | |
| " exp_avg_reward_per_step = np.zeros((experiment_parameters[\"num_runs\"], experiment_parameters[\"max_steps\"]))\n", | |
| "\n", | |
| " # using tqdm we visualize progress bars \n", | |
| " for run in tqdm(range(1, experiment_parameters[\"num_runs\"]+1)):\n", | |
| " env_info[\"seed\"] = run\n", | |
| " agent_info[\"seed\"] = run\n", | |
| " \n", | |
| " rl_glue.rl_init(agent_info, env_info)\n", | |
| " rl_glue.rl_start()\n", | |
| "\n", | |
| " num_steps = 0\n", | |
| " total_return = 0.\n", | |
| " return_arr = []\n", | |
| "\n", | |
| " # exponential average reward without initial bias\n", | |
| " exp_avg_reward = 0.0\n", | |
| " exp_avg_reward_ss = 0.01\n", | |
| " exp_avg_reward_normalizer = 0\n", | |
| "\n", | |
| " while num_steps < experiment_parameters['max_steps']:\n", | |
| " num_steps += 1\n", | |
| " \n", | |
| " rl_step_result = rl_glue.rl_step()\n", | |
| " \n", | |
| " reward = rl_step_result[0]\n", | |
| " total_return += reward\n", | |
| " return_arr.append(reward)\n", | |
| " avg_reward = rl_glue.rl_agent_message(\"get avg reward\")\n", | |
| "\n", | |
| " exp_avg_reward_normalizer = exp_avg_reward_normalizer + exp_avg_reward_ss * (1 - exp_avg_reward_normalizer)\n", | |
| " ss = exp_avg_reward_ss / exp_avg_reward_normalizer\n", | |
| " exp_avg_reward += ss * (reward - exp_avg_reward)\n", | |
| " \n", | |
| " return_per_step[run-1][num_steps-1] = total_return\n", | |
| " exp_avg_reward_per_step[run-1][num_steps-1] = exp_avg_reward\n", | |
| " \n", | |
| " if not os.path.exists('results'):\n", | |
| " os.makedirs('results')\n", | |
| " \n", | |
| " save_name = \"ActorCriticSoftmax_tilings_{}_tiledim_{}_actor_ss_{}_critic_ss_{}_avg_reward_ss_{}\".format(num_tilings, num_tiles, actor_ss, critic_ss, avg_reward_ss)\n", | |
| " total_return_filename = \"results/{}_total_return.npy\".format(save_name)\n", | |
| " exp_avg_reward_filename = \"results/{}_exp_avg_reward.npy\".format(save_name)\n", | |
| "\n", | |
| " np.save(total_return_filename, return_per_step)\n", | |
| " np.save(exp_avg_reward_filename, exp_avg_reward_per_step)\n", | |
| " " | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "986f2c1efbd936813ceac9d1749f3feb", | |
| "grade": false, | |
| "grade_id": "cell-af8391c13e4be3c8", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Section 3-1: Run Experiment with 32 tilings, size 8x8\n", | |
| "\n", | |
| "We will first test our implementation using 32 tilings, of size 8x8. We saw from the earlier assignment using tile-coding that many tilings promote fine discrimination, and broad tiles allows more generalization.\n", | |
| "We conducted a wide sweep of meta-parameters in order to find the best meta-parameters for our Pendulum Swing-up task. \n", | |
| "\n", | |
| "We swept over the following range of meta-parameters and the best meta-parameter is boldfaced below:\n", | |
| "\n", | |
| "actor step-size: $\\{\\frac{2^{-6}}{32}, \\frac{2^{-5}}{32}, \\frac{2^{-4}}{32}, \\frac{2^{-3}}{32}, \\mathbf{\\frac{2^{-2}}{32}}, \\frac{2^{-1}}{32}, \\frac{2^{0}}{32}, \\frac{2^{1}}{32}\\}$\n", | |
| "\n", | |
| "critic step-size: $\\{\\frac{2^{-4}}{32}, \\frac{2^{-3}}{32}, \\frac{2^{-2}}{32}, \\frac{2^{-1}}{32}, \\frac{2^{0}}{32}, \\mathbf{\\frac{2^{1}}{32}}, \\frac{3}{32}, \\frac{2^{2}}{32}\\}$\n", | |
| "\n", | |
| "avg reward step-size: $\\{2^{-11}, 2^{-10} , 2^{-9} , 2^{-8}, 2^{-7}, \\mathbf{2^{-6}}, 2^{-5}, 2^{-4}, 2^{-3}, 2^{-2}\\}$ \n", | |
| "\n", | |
| "\n", | |
| "We will do 50 runs using the above best meta-parameter setting to verify your agent.\n", | |
| "Note that running the experiment cell below will take **_approximately 5 min_**.\n" | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 10, | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "9f76e04859fa6d09d18caca6b89bae8f", | |
| "grade": false, | |
| "grade_id": "cell-4d1df8adaf0d23c6", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [ | |
| { | |
| "name": "stderr", | |
| "output_type": "stream", | |
| "text": [ | |
| "100%|██████████| 50/50 [02:53<00:00, 3.47s/it]\n" | |
| ] | |
| }, | |
| { | |
| "data": { | |
| "image/png": "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NsWXX3bZZT537lzftm2bZ2dnu7v7Z5995h06dHB399WrV/u8efPc3X3r1q3erl07/+qrr0r5KA6UlZVVotvP+34uWbLEO3fuXOT1a9euneyQSk3Pnj195syZnp2d7cOHD49/7qK++uorT09P9927d/vixYu9bdu28fdk1qxZvnr16gPOQUGfiUGDBvk777zj7u7btm3zHTt2uLv766+/7tnZ2Z6dne0XXHCB/+Uvf3F39w8++MBHjBhR6LEk+lstaa6XQO5BCxYAAOXcqFGjdPzxx6tz587661//Gi9/66231L17d2VkZGjo0KFaunSpHnvsMf35z39WZmampk+frmXLlmno0KFKT0/X0KFDtXz5cknSmDFjdNNNN2nIkCG65ZZbEu536tSp8bvG3bp107Zt27RmzRoNHDhQmZmZ6tKli6ZPn15g7JMmTdLo0aMlSeecc47ee++9A+6S16pVS0OGDJEkVa9eXd27d9fKlSsLPS9TpkzR4MGDJUmHH364pODG8q5du+KD3vv166cGDRpIkvr06VOk7c6ZM0f9+vVTRkaGevXqpW3btmnChAk699xzddppp+nkk0+Ot3Ls3btXt99+uyZOnKjMzExNnDhREyZM0PXXXy9JWrt2rc4880xlZGQoIyMj39bFHTt2aMSIEcrIyFCXLl3irU/jxo1Tp06dlJ6erptvvrnAuNu3b6927dpJkpo2barGjRtr/fr18fMyf/58de/eXXXq1Imfnx07dsSfN2nSRN27d5ck1a1bVx07dtSqVasK3Ofs2bPVr18/devWTf369dOCBQskSb1799ZXX30Vrzd48GDNmzdP69ev17Bhw9S9e3ddc801atWqlTZs2HDAduvUqaPbb79dvXv31qxZs/SPf/xDvXr1UmZmpq655hrt379fL774om666SZJ0gMPPKC2bdtKkhYtWqQBAwZIku666y717NlTXbp00dVXXx2/9gYPHqzf/OY3GjRokB544AHNmzdPGRkZ6tu3rx555JGEx5ro2h83bpx27dqlzMxMXXzxxZKUMNbYMf3iF79Q9+7dNXTo0Ph7k8iDDz4Yf98vuOACScp1XcU+l5mZmTrssMM0depU7dixQ1dccYV69uypbt26adKkSQW+d2vWrNHWrVvVt29fmZkuu+wy/fOf/zyg3qRJk3TBBReoRo0aatOmjY499ljNnj1bUvCZatKkSYH7ifr666+VlZWlYcOGxc9JrVq1JEmnnnqqzExmpl69ehXps5oyJZG1lbUHLVgAgJKS965oq1v+nfRHYTZu3OjuQYtN586dfcOGDb5u3Tpv3ry5L168OFedvC1YI0eO9AkTJri7+9/+9jc/44wz3N199OjRPmLEiAJbB0aOHOkffvihuwd3mvft2+f33Xef33333e4etCxs3brV3d3Hjh3rc+bMOWAbnTt39hUrVsRft23b1tevX5/vPjdt2uRt2rTxRYsWuXtwJ/zoo4/2rl27+tlnn+3Lly+P173hhhv8vffei+pCzSYAACAASURBVL8eM2aMN27c2AcPHhy/Kx71xz/+0ceOHZvvvt2DFrQ2bdr47Nmz3T1oGdu3b58/+eST3qxZs/h5jrZy5L1bH3193nnn+Z///Gd3D87X5s2bE+735Zdf9iuvvDL+evPmzb5x40Zv3759vLUp1ho1adIk/+1vf1vgcXz88cd+3HHH+f79+93dfd68eX7ppZfGl7/66qveoUMHb9Cggc+cOfOA9ZcsWeItWrTI1TKYSOz8uLu/++67ftZZZ7m7+5/+9Ce//fbb3T1oGWvXrp27u1933XX++9//3t3d33zzTZeU8HqQ5BMnTnT34DM4cuRI37t3r7u7X3vttf7UU0/5mjVrvEePHu7ufvbZZ3uPHj185cqVPmHCBB83bpy753wu3N0vueQSnzx5srsHrSjXXnttfFnXrl19ypQp7u5+8803J2zByu/aj7be5Bdr7Jj+8Y9/uLv7nXfeWWCrZ5MmTXz37t3unvO+J2oVmjx5sg8YMMD37t3rv/71r/2ZZ56Jr9OuXTvfvn27r1q1yk855ZQD9jFnzhwfOnRo/PW0adMSthRdd9118e26u19xxRX+0ksv5aqTqAUr0ef2tdde8xEjRviZZ57pmZmZfvPNNx/wN2jv3r3erVs3nzZtmrsHLVgNGzb09PR0Hz58uH/55ZcJz1lptmDxQ8MAACTR0ntGlPo+H3zwQb322muSgnEyCxcu1Pr16zVw4MD4D2s2bNgw4bqzZs3Sq6++Kkm69NJL9atf/Sq+7Nxzz1VaWlq+++3fv79uuukmXXzxxTrrrLPUvHlz9ezZMz4+YtSoUcrMzJSkA8ZGxbgfOKYjvymVs7KydOGFF+rGG2+Mt0acdtppuvDCC1WjRg099thjGj16tN5//31J0owZM3TffffF13/yySe1f/9+3XDDDZo4caIuv/zy+LIPPvhAf/vb3+LjjfKzYMECNWnSRD179pSU0zImScOGDcv3POfn/fff19NPPy1JSktLU7169RLW69q1q26++WbdcsstGjlypE444QRlZWWpZs2auvLKKzVixAiNHDlSknT66afr9NNPz3efa9as0aWXXqqnnnpKVaoEnZneeustnXLKKfE6Z555ps4880xNmzZNv/3tb/Wf//wnvmz79u06++yzdf/99+c6/kS2bNmi0aNHa+HChTKz+LiZ8847T8OGDdOdd96pF198Ueeee64k6cMPP4xfy8OHD4+3LuaVlpams88+W5L03nvvad68efH3ZNeuXWrcuLGOPvpobd++Xdu2bdOKFSt00UUXadq0aZo+fbrOOussScH7fu+992rnzp364Ycf1LlzZ5122mmSpPPPPz9+DJs3b9agQYMkBZ+TN99884CY8rv2o/KLVZKqVKkS3+cll1wSjzGR9PR0XXzxxRo1apRGjRqVsM7ChQv1y1/+Uu+//76qVaumd955R5MnT45/Jnbv3q3ly5erY8eOucYIxhT1s1mcz3BMfp/brKwsTZ8+XZ9++qlatmyp888/XxMmTNDYsWPj6/7kJz/RwIEDdcIJJ0iSunfvrmXLlqlOnTp64403NGrUKC1cuLDA/Zc0uggCAFCOTZkyRf/5z380a9YsffbZZ+rWrZt2794tdz+o336JrlO7du0C644bN05PPPGEdu3apT59+ujbb7/VwIEDNW3aNDVr1kyXXnppPHnIT/PmzbVixQpJQQK1ZcuWfJOUq6++Wu3atdPPfvazeFmjRo1Uo0YNSdJVV12lefPmSZIWL16sFi1aqHr16rm2kZaWpvPPP1+vvPJKvOzzzz/XlVdeqUmTJqlRo0YFxlvQeS3sfB2K9u3bxycc+PWvf6277rpLVatW1ezZs3X22Wfrn//8p4YPH17odrZu3aoRI0bo7rvvVp8+feLl77zzjk4++eQD6g8cOFCLFi2Kd9Pbt2+fzj777HhSXZjf/va3GjJkiL788kv961//iv/Ya7NmzdSoUSN9/vnnmjhxYrybW6Iv64nUrFkznvy7u0aPHq358+dr/vz5WrBggcaPHy9J6tu3r5588kl16NBBJ5xwgqZPn65Zs2apf//+2r17t37yk5/o5Zdf1hdffKGrrroq14/Rxt7Pon6WinLtFxRrXgXt8/XXX9d1112nefPm6fjjj1dWVlau5Tt27NB5552nxx9/XE2bNo3v+5VXXonvO5Zc5ad58+a5uuGtXLkyvq289WKf4YLqReX3uW3evLm6deumtm3bqmrVqho1apQ++eST+Hp33nmn1q9frz/96U/xssMPPzw+icapp56qffv2JexWWprKbYJlZsPNbIGZfWdm4wpfAwCAimfLli1q0KCBatWqpW+//VYfffSRpOCL5dSpU7VkyRJJ0g8//CApGDuzbdu2+Pr9+vXTCy+8ICmYUS82NqUoFi1apK5du+qWW25Rjx499O2332rZsmVq3LixrrrqKo0dOzbXl6NETj/9dD311FOSpJdfflknnnhiwi+Wt912m7Zs2aL7778/V/maNWvizydPnhz/wvjmm2/GEw5313fffRd//q9//UvHHXecpGDGsrPOOkvPPPOM2rdvn2vbQ4cOPWCM0XHHHafVq1drzpw5kqRt27Yd8OU2r7znPO8+Hn30UUnS/v37tXXr1oT1Vq9erVq1aumSSy7RzTffrE8++UTbt2/Xli1bdOqpp+r+++/X/PnzC4xj7969OvPMM3XZZZfFW4yk4BrKysqKJ5ffffddPNH55JNPtHfvXjVq1EjurrFjx6pjx47xsU0xDz/8sB5++OED9rllyxY1a9ZMUjBGKOqCCy7Qvffeqy1btqhr166SpAEDBujFF1+UFCR9mzZtKvCYpOAcvvzyy1q3bp2k4FpftmyZpCDpue+++zRw4EB169ZNH3zwgWrUqKF69erFk6kjjjhC27dv18svv5xw+/Xr11e9evXirZvPPvtswnr5XfvVqlWLt9wVFGt2dnY8hueeey7fz2J2dnZ8Rsd7771Xmzdvjs+KGXP55Zfr8ssvj7fySNKPfvQjPfTQQ/H39tNPP833nErBmLu6devqo48+krvr6aef1hlnnHFAvdNPP10vvPCC9uzZoyVLlmjhwoXq1atXgdvO73Pbs2dPbdq0KT7+7P3331enTp0kBa3gb7/9tp5//vl4y6skff/99/Fjmj17trKzswu9UVLiSqLfYUk/JKVJWiSpraTqkj6T1Cm/+ozBAgCUlFTPIrh7924fPny4d+3a1c855xwfNGiQf/DBB+4ezIqXmZnp6enpftJJJ7l7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MWMG//Iv/8L8+fPZuXMnP/rRj1i0aBENDQ1861vfcs/NTTfdBMBXvvIVTj/9dAD+9re/8YlPfAKAL3zhCyxcuJD6+nr3dQB1dXV85zvfYcmSJfzxj3/kscceY/r06SxZsoQ///nPQx4zwCuvvMKUKVOYPHkyPp+Piy++mAceeKDfdg888ACXXnopmqaxePFiurq6aG5uBmDZsmWUlZUNu6+Cxx9/nIaGBubMmQNAeXk5hmEQCoU47bTTAPD5fMyfP/+APgNHi6RpF0IIIcQxo+7ah0e8zG0/WDnk+ttvv52ysjJSqRSLFi3iggsuwLZtrrjiCp577jkmTZpER0cHZWVlfP7znycSifCv//qvAJx77rlceumlfOpTn+L222/n6quv5v777wfgrbfe4sknn8QwDB588EEaGxv5zne+02ffu3btYvz48e7z2traYQOcX/3qV7z//e93n6fTaRYuXIjH4+Haa6/lQx/6EACvvfYac+bMcYOL++67j2984xu0trby8MP9z/O2bdt47bXXOPnkk4fc/3e/+12Ki4tZu3YtAJ2dnYATyMyaNavfMf7gBz/g5ptvZvXq1f3KevTRR7n//vt5+eWXCYVCdHR0AHDrrbcC8PnPf37Qetx7773MmzcPv98PwJNPPsny5cvd9f/zP//DjTfeSDab7deVEJwAIpvNcsIJJwx5vEuWLOGll15C0zR++ctf8sMf/pCf/OQnfPCDH+S+++7jsssu4+WXX6auro7q6mo++9nP8uUvf5mPfexj7nEM5M033+SOO+7glltu4fHHH2fTpk288sorKKU477zzeO6551i2bBk/+clPuPrqq2lsbCSTyZDL5Xj++edZunQpADfccANlZWVYlsXy5ct5/fXXaWhoAJz5n55//nnS6TRTp07lqaeeYsqUKVx00UVuPRobG7n11lv7da0b6Np8+eWX+x3HYNfw2LFjhzyvN998M3fddRcLFy7kJz/5CaWlpbz11ltomsaKFSvYu3cvF198MV/72tf6vK6rq4uHHnqIL3/5y+6ye++9l+eee44TTzyRn/70p33qczRIgCWEEEKIY8ZwwdCRcNNNN3HfffcBzpikTZs2sXfvXpYtW+bOmzPYX+FffPFFtzXgk5/8ZJ+bwQsvvBDDMAA477zz+o2PAqeVaX9DZTz7zW9+Q2NjI88++6y7bMeOHdTU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\n", | |
| "text/plain": [ | |
| "<Figure size 864x1008 with 2 Axes>" | |
| ] | |
| }, | |
| "metadata": { | |
| "needs_background": "light" | |
| }, | |
| "output_type": "display_data" | |
| } | |
| ], | |
| "source": [ | |
| "# ---------------\n", | |
| "# Discussion Cell\n", | |
| "# ---------------\n", | |
| "\n", | |
| "#### Run Experiment\n", | |
| "\n", | |
| "# Experiment parameters\n", | |
| "experiment_parameters = {\n", | |
| " \"max_steps\" : 20000,\n", | |
| " \"num_runs\" : 50\n", | |
| "}\n", | |
| "\n", | |
| "# Environment parameters\n", | |
| "environment_parameters = {}\n", | |
| "\n", | |
| "# Agent parameters\n", | |
| "# Each element is an array because we will be later sweeping over multiple values\n", | |
| "# actor and critic step-sizes are divided by num. tilings inside the agent\n", | |
| "agent_parameters = {\n", | |
| " \"num_tilings\": [32],\n", | |
| " \"num_tiles\": [8],\n", | |
| " \"actor_step_size\": [2**(-2)],\n", | |
| " \"critic_step_size\": [2**1],\n", | |
| " \"avg_reward_step_size\": [2**(-6)],\n", | |
| " \"num_actions\": 3,\n", | |
| " \"iht_size\": 4096\n", | |
| "}\n", | |
| "\n", | |
| "current_env = PendulumEnvironment\n", | |
| "current_agent = ActorCriticSoftmaxAgent\n", | |
| "\n", | |
| "\n", | |
| "run_experiment(current_env, current_agent, environment_parameters, agent_parameters, experiment_parameters)\n", | |
| "plot_script.plot_result(agent_parameters, 'results')" | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "bcffcef5262c887f5a94191b7c37915a", | |
| "grade": false, | |
| "grade_id": "cell-146b310087d1a4f5", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "Run the following code to verify your experimental result." | |
| ] | |
| }, | |
| { | |
| "cell_type": "code", | |
| "execution_count": 11, | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "code", | |
| "checksum": "32a257715ac93c6b5c648b875f396e9c", | |
| "grade": false, | |
| "grade_id": "cell-60ba9335a60d9f20", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "outputs": [ | |
| { | |
| "name": "stdout", | |
| "output_type": "stream", | |
| "text": [ | |
| "Your experiment results are correct!\n" | |
| ] | |
| } | |
| ], | |
| "source": [ | |
| "# ---------------\n", | |
| "# Discussion Cell\n", | |
| "# ---------------\n", | |
| "\n", | |
| "## Test Code for experimental result ##\n", | |
| "filename = 'ActorCriticSoftmax_tilings_32_tiledim_8_actor_ss_0.25_critic_ss_2_avg_reward_ss_0.015625_exp_avg_reward'\n", | |
| "agent_exp_avg_reward = np.load('results/{}.npy'.format(filename), allow_pickle=True)\n", | |
| "result_med = np.median(agent_exp_avg_reward, axis=0)\n", | |
| "\n", | |
| "answer_range = np.load('correct_npy/exp_avg_reward_answer_range.npy', allow_pickle=True)\n", | |
| "upper_bound = answer_range.item()['upper-bound']\n", | |
| "lower_bound = answer_range.item()['lower-bound']\n", | |
| "\n", | |
| "# check if result is within answer range\n", | |
| "all_correct = np.all(result_med <= upper_bound) and np.all(result_med >= lower_bound)\n", | |
| "\n", | |
| "if all_correct:\n", | |
| " print(\"Your experiment results are correct!\")\n", | |
| "else:\n", | |
| " print(\"Your experiment results does not match with ours. Please check if you have implemented all methods correctly.\")\n", | |
| " \n", | |
| " " | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "a7d8ad3d50bae004227329037368dabc", | |
| "grade": false, | |
| "grade_id": "cell-427b974ad2550ce7", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Section 3-2: Performance Metric and Meta-Parameter Sweeps\n", | |
| "\n", | |
| "\n", | |
| "### Performance Metric\n", | |
| "\n", | |
| "To evaluate performance, we plotted both the return and exponentially weighted average reward over time. \n", | |
| "\n", | |
| "In the first plot, the return is negative because the reward is negative at every state except when the pendulum is in the upright position. As the policy improves over time, the agent accumulates less negative reward, and thus the return decreases slowly. Towards the end the slope is almost flat indicating the policy has stabilized to a good policy. When using this plot however, it can be difficult to distinguish whether it has learned an optimal policy. The near-optimal policy in this Pendulum Swing-up Environment is to maintain the pendulum in the upright position indefinitely, getting near 0 reward at each time step. We would have to examine the slope of the curve but it can be hard to compare the slope of different curves.\n", | |
| "\n", | |
| "The second plot using exponential average reward gives a better visualization. We can see that towards the end the value is near 0, indicating it is getting near 0 reward at each time step. Here, the exponentially weighted average reward shouldn't be confused with the agent’s internal estimate of the average reward. To be more specific, we used an exponentially weighted average of the actual reward without initial bias (Refer to Exercise 2.7 from the textbook (p.35) to read more about removing the initial bias). If we used sample averages instead, later rewards would have decreasing impact on the average and would not be able to represent the agent's performance with respect to its current policy effectively.\n", | |
| "\n", | |
| "It is easier to see whether the agent has learned a good policy in the second plot than the first plot. If the learned policy is optimal, the exponential average reward would be close to 0.\n", | |
| "\n", | |
| "Furthermore, how did we pick the best meta-parameter from the sweeps? A common method would be to pick the meta-parameter that results in the largest Area Under the Curve (AUC). However, this is not always what we want. We want to find a set of meta-parameters that learns a good final policy. When using AUC as the criteria, we may pick meta-parameters that allows the agent to learn fast but converge to a worse policy. In our case, we selected the meta-parameter setting that obtained the most exponential average reward over the last 5000 time steps. \n", | |
| "\n", | |
| "\n", | |
| "### Parameter Sensitivity\n", | |
| "\n", | |
| "In addition to finding the best meta-parameters it is also equally important to plot **parameter sensitivity curves** to understand how our algorithm behaves.\n", | |
| "\n", | |
| "In our simulated Pendulum problem, we can extensively test our agent with different meta-parameter configurations but it would be quite expensive to do so in real life. Parameter sensitivity curves can provide us insight into how our algorithms might behave in general. It can help us identify a good range of each meta-parameters as well as how sensitive the performance is with respect to each meta-parameter.\n", | |
| "\n", | |
| "Here are the sensitivity curves for the three step-sizes we swept over:\n", | |
| "\n", | |
| "<img src=\"data/sensitivity_combined.png\" alt=\"Drawing\" style=\"width: 1000px;\"/>\n", | |
| "\n", | |
| "On the y-axis we use the performance measure, which is the average of the exponential average reward over the 5000 time steps, averaged over 50 different runs. On the x-axis is the meta-parameter we are testing. For the given meta-parameter, the remaining meta-parameters are chosen such that it obtains the best performance.\n", | |
| "\n", | |
| "The curves are quite rounded, indicating the agent performs well for these wide range of values. It indicates that the agent is not too sensitive to these meta-parameters. Furthermore, looking at the y-axis values we can observe that average reward step-size is particularly less sensitive than actor step-size and critic step-size.\n", | |
| "\n", | |
| "But how do we know that we have sufficiently covered a wide range of meta-parameters? It is important that the best value is not on the edge but in the middle of the meta-parameter sweep range in these sensitivity curves. Otherwise this may indicate that there could be better meta-parameter values that we did not sweep over." | |
| ] | |
| }, | |
| { | |
| "cell_type": "markdown", | |
| "metadata": { | |
| "deletable": false, | |
| "editable": false, | |
| "nbgrader": { | |
| "cell_type": "markdown", | |
| "checksum": "5297e29ae9abf6cd1d9f2aac5bf53df2", | |
| "grade": false, | |
| "grade_id": "cell-75e8b239dcff4058", | |
| "locked": true, | |
| "schema_version": 3, | |
| "solution": false, | |
| "task": false | |
| } | |
| }, | |
| "source": [ | |
| "## Wrapping up\n", | |
| "\n", | |
| "### **Congratulations!** You have successfully implemented Course 3 Programming Assignment 4.\n", | |
| "\n", | |
| "\n", | |
| "You have implemented your own **Average Reward Actor-Critic with Softmax Policy** agent in the Pendulum Swing-up Environment. You implemented the environment based on information about the state/action space and transition dynamics. Furthermore, you have learned how to implement an agent in a continuing task using the average reward formulation. We parameterized the policy using softmax of action-preferences over discrete action spaces, and used Actor-Critic to learn the policy.\n", | |
| "\n", | |
| "\n", | |
| "To summarize, you have learned how to:\n", | |
| " 1. Implement softmax actor-critic agent on a continuing task using the average reward formulation.\n", | |
| " 2. Understand how to parameterize the policy as a function to learn, in a discrete action environment.\n", | |
| " 3. Understand how to (approximately) sample the gradient of this objective to update the actor.\n", | |
| " 4. Understand how to update the critic using differential TD error." | |
| ] | |
| } | |
| ], | |
| "metadata": { | |
| "coursera": { | |
| "course_slug": "prediction-control-function-approximation", | |
| "graded_item_id": "bHUHt", | |
| "launcher_item_id": "Igqsy" | |
| }, | |
| "kernelspec": { | |
| "display_name": "Python 3", | |
| "language": "python", | |
| "name": "python3" | |
| }, | |
| "language_info": { | |
| "codemirror_mode": { | |
| "name": "ipython", | |
| "version": 3 | |
| }, | |
| "file_extension": ".py", | |
| "mimetype": "text/x-python", | |
| "name": "python", | |
| "nbconvert_exporter": "python", | |
| "pygments_lexer": "ipython3", | |
| "version": "3.7.6" | |
| } | |
| }, | |
| "nbformat": 4, | |
| "nbformat_minor": 2 | |
| } |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment