{ "metadata": { "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.4" }, "orig_nbformat": 2, "kernelspec": { "name": "python3", "display_name": "Python 3.7.4 64-bit ('base': conda)" }, "interpreter": { "hash": "c77bccf6af5544921fca6eddbefe5e7c44ddf71c61b63c74bd828ca1d0e389a0" } }, "nbformat": 4, "nbformat_minor": 2, "cells": [ { "source": [ "# Peter and the Wolf: Reinforcement Learning Primer\n", "\n", "In this tutorial, we will learn how to apply Reinforcement learning to a problem of path finding. The setting is inspired by [Peter and the Wolf](https://en.wikipedia.org/wiki/Peter_and_the_Wolf) musical fairy tale by Russian composer [Segei Prokofiev](https://en.wikipedia.org/wiki/Sergei_Prokofiev). It is a story about young pioneer Peter, who bravely goes out of his house to the forest clearing to chase the wolf. We will train machine learning algorithms that will help Peter to explore the surroinding area and build an optimal navigation map.\n", "\n", "First, let's import a bunch of userful libraries:" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "import matplotlib.pyplot as plt\n", "import numpy as np\n", "import random\n", "import math" ] }, { "source": [ "## Overview of Reinforcement Learning\n", "\n", "**Reinforcement Learning** (RL) is a learning technique that allows us to learn an optimal behaviour of an **agent** in some **environment** by running many experiments. An agent in this environment should have some **goal**, defined by a **reward function**.\n", "\n", "## The Environment\n", "\n", "For simplicity, let's consider Peter's world to be a square board of size `width` x `height`. Each cell in this board can either be:\n", "* **ground**, on which Peter and other creatures can walk\n", "* **water**, on which you obviously cannot walk\n", "* **a tree** or **grass** - a place where you cat take some rest\n", "* **an apple**, which represents something Peter would be glad to find in order to feed himself\n", "* **a wolf**, which is dangerous and should be avoided\n", "\n", "To work with the environment, we will define a class called `Board`. In order not to clutter this notebook too much, we have moved all code to work with the board into separate `rlboard` module, which we will now import. You may look inside this module to get more details about the internals of the implementation." ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "from rlboard import *" ] }, { "source": [ "Let's now create a random board and see how it looks:" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "output_type": "display_data", "data": { "text/plain": "
", "image/svg+xml": "\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n", "image/png": "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\n" }, "metadata": { "needs_background": "light" } } ], "source": [ "width, height = 8,8\n", "m = Board(width,height)\n", "m.randomize(seed=13)\n", "m.plot()" ] }, { "source": [ "## Actions and Policy\n", "\n", "In our example, Peter's goal would be to find an apple, while avoiding the wolf and other obstacles. To do this, he can essentially walk around until he finds and apple. Therefore, at any position he can chose between one of the following actions: up, down, left and right. We will define those actions as a dictionary, and map them to pairs of corresponding coordinate changes. For example, moving right (`R`) would correspond to a pair `(1,0)`." ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [], "source": [ "actions = { \"U\" : (0,-1), \"D\" : (0,1), \"L\" : (-1,0), \"R\" : (1,0) }\n", "action_idx = { a : i for i,a in enumerate(actions.keys()) }" ] }, { "source": [ "The strategy of our agent (Peter) is defined by so-called **policy**. A policy is a function that returns the action at any given state. In our case, the state of the problem is represented by the board, including the current position of the player. \n", "\n", "The goal of reinforcement learning is to eventually learn a good policy that will allow us to solve the problem efficiently. However, as a baseline, let's consider the simplest policy called **random walk**.\n", "\n", "## Random walk\n", "\n", "Let's first solve our problem by implementing a random walk strategy. With random walk, we will randomly chose the next action from allowed ones, until we reach the apple. " ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 5, "metadata": { "tags": [] }, "outputs": [ { "output_type": "execute_result", "data": { "text/plain": [ "18" ] }, "metadata": {}, "execution_count": 5 } ], "source": [ "def random_policy(m):\n", " return random.choice(list(actions))\n", "\n", "def walk(m,policy,start_position=None):\n", " n = 0 # number of steps\n", " # set initial position\n", " if start_position:\n", " m.human = start_position \n", " else:\n", " m.random_start()\n", " while True:\n", " if m.at() == Board.Cell.apple:\n", " return n # success!\n", " if m.at() in [Board.Cell.wolf, Board.Cell.water]:\n", " return -1 # eaten by wolf or drowned\n", " while True:\n", " a = actions[policy(m)]\n", " new_pos = m.move_pos(m.human,a)\n", " if m.is_valid(new_pos) and m.at(new_pos)!=Board.Cell.water:\n", " m.move(a) # do the actual move\n", " break\n", " n+=1\n", "\n", "walk(m,random_policy)" ] }, { "source": [ "Let's run random walk experiment several times and see the average number of steps taken:" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ "Average path length = 32.87096774193548, eaten by wolf: 7 times\n" ] } ], "source": [ "def print_statistics(policy):\n", " s,w,n = 0,0,0\n", " for _ in range(100):\n", " z = walk(m,policy)\n", " if z<0:\n", " w+=1\n", " else:\n", " s += z\n", " n += 1\n", " print(f\"Average path length = {s/n}, eaten by wolf: {w} times\")\n", "\n", "print_statistics(random_policy)" ] }, { "source": [ "## Reward Function\n", "\n", "To make out policy more intelligent, we need to understand which moves are \"better\" than others. To do this, we need to define our goal. The goal can be defined in terms of **reward function**, that will return some score value for each state. The higher the number - the better is the reward function\n", "\n" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [], "source": [ "move_reward = -0.1\n", "goal_reward = 10\n", "end_reward = -10\n", "\n", "def reward(m,pos=None):\n", " pos = pos or m.human\n", " if not m.is_valid(pos):\n", " return end_reward\n", " x = m.at(pos)\n", " if x==Board.Cell.water or x == Board.Cell.wolf:\n", " return end_reward\n", " if x==Board.Cell.apple:\n", " return goal_reward\n", " return move_reward" ] }, { "source": [ "Interesting thing about reward function is that in most of the cases *we are only given substantial reward at the end of the game*. It means that out algorithm should somehow remember \"good\" steps that lead to positive reward at the end, and increase their importance. Similarly, all moves that lead to bad results should be discouraged.\n", "\n", "## Q-Learning\n", "\n", "An algorithm that we will discuss here is called **Q-Learning**. In this algorithm, the policy is defined by a function (or a data structure) called **Q-Table**. It records the \"goodness\" of each of the actions in a given state, i.e. $Q : {S\\times A}\\to\\mathbb{R}$, where $S$ is a set of states, $A$ is the set of actions.\n", "\n", "It is called Q-Table because it is often convenient to represent it as a table, or multi-dimensional array. Since our board has dimentions `width` x `height`, we can represent Q-Table by a numpy array with shape `width` x `height` x `len(actions)`:" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [], "source": [ "Q = np.ones((width,height,len(actions)),dtype=np.float)*1.0/len(actions)" ] }, { "source": [ "Notice that we initially initialize all values of Q-Table with equal value, in our case - 0.25. That corresponds to the \"random walk\" policy, because all moves in each state are equally good. We can pass the Q-Table to the `plot` function in order to visualize the table on the board:" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "output_type": "display_data", "data": { "text/plain": "
", "image/svg+xml": "\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n", "image/png": "iVBORw0KGgoAAAANSUhEUgAAAW4AAAFpCAYAAAC8p8I3AAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4xLjAsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+17YcXAAAgAElEQVR4nOzdeXhU5f3+8fczk8m+BwIYBGQRZIkoiCKbCC6tuwVFZSkiqC1SXHAB259VYhUVqtWKKCIg7igoBa2CK/AFsWVTgQAJSAiBJGSZfeac5/dHJikICSgJZyZ8Xl5zJXMyM+cmydyePGd5lNYaIYQQkcNmdQAhhBC/jBS3EEJEGCluIYSIMFLcQggRYaS4hRAiwkhxCyFEhGmw4lZKXa6U2qqU2q6UerCh1iOEEKca1RDHcSul7MA24BJgD/AtcJPW+od6X5kQQpxiGmqLuxewXWu9U2vtB94CrmmgdQkhxCmloYo7C/jpkPt7QsuEEEKcoKgGel11lGWHjckopcYB4wAcDkeP7OzsBopy4nw+H5WVlTRp0sTqKLUqKyvD4XCQkJBgdZRaFRYWkpmZid1utzpKrXbv3k2rVq2sjlGrYDDIgQMHaNGihdVRauV0OgkGg6SmplodpVYHDhwgOTmZmJgYq6PU6vvvv8fj8RytS0FrXe83oDfwySH3HwIequ3xmZmZOpzl5ubqWbNmWR2jTh988IFetWqV1THq9Nhjj+nS0lKrY9TKNE09fvx4q2PUqaSkROfk5Fgdo07ffPONXrRokdUx6jRz5kydm5trdYw6hXrxqJ3ZUEMl3wIdlFJnKKWigWHAhw20LiGEOKU0yFCJ1jqolBoPfALYgVe11t83xLqEEOJU01Bj3GitlwJLG+r1hRDiVCVnTgohRISR4hZCiAgjxS2EEBFGilsIISKMFLcQQkQYKW4hhIgwUtxCCBFhpLiFECLCSHELIUSEkeIWQogII8UthBARRopbCCEiTKMt7ry8vOprgYclwzDYvXu31THq5HK5OHDggNUx6nTgwAFcLpfVMeq0e/duDMOwOkattNbk5eVZHaNOfr+fvXv3Wh2jTmVlZZSVlZ2UdTXY1QGtsnXrVr7++ms2bdpEt27d6N69Oz179rQ61mG++OILtm7dytatW+ncuTOXX345LVu2tDrWYd5++20KCgqoqKigZcuWjBgxIqxmC/H5fMyfP589e/aQlJREVlYWw4YNszrWYQoKCli2bBk//PADHTt25Mwzz2TgwIFWxzrMunXrWL9+PRs3biQ7O5u+ffvSqVMnq2MdZsmSJeTn51NQUEC7du0YMmRIWM2uo7Vm7ty5FBYWAtCiRQtGjRqFUkefvKY+NLot7q+//po1a9bwl7/8hZ07d/LBBx9YHekIs2fPxu12c//997Ns2TI2b95sdaQjPProo3Tp0oXrrruOv//977jdbqsjHcbj8TBjxgyuvfZaunbtyqOPPmp1pCN8//33LF26lEmTJuH1ennllVesjnSERYsWsXPnTh555BHWrl3L119/bXWkIzz11FNkZGQwZswY5s+fz759+6yOdBjTNJk6dSr9+/enX79+TJ06FdM0G3Sdjaq48/Ly2LRpEzExMVx99dU8+OCDxMbGsnLlSquj1Vi4cCG9e/fm448/5uGHH+aFF15gwYIFlJeXWx2txuTJk/nb3/7Ggw8+yKpVq1i0aBG33Xab1bEOc9tttzF58mRGjx5NamoqL7zwAg899JDVsWpUVFQwb948unbtyhVXXMGIESPo27cv7733ntXRaqxatYro6Gh27tzJqFGjeOKJJ9i8eTM7d+60OlqN5557jjvvvJNnn32WefPmMX/+fCZPnhxWQ0/jxo3j6aefZvz48ZSWlvLee+8xbty4Bl1noxoqadOmDd26dWPHjh0sW7aMefPm4fV6ufDCC62OVuP6669n1KhR3HrrrVx66aXcf//93HzzzSQnJ1sdrcbUqVPp3r07c+fOJS0tjRtvvJGlS8NrToyXX36ZSy+9lPfff5+Kigpuu+02NmzYYHWsGklJSYwcOZK3336bzz77jBUrVrBy5Urmz59vdbQavXv3ZunSpVx44YX8/ve/58knn6Rr166cccYZVkercddddzFw4ECeeOIJOnbsyLhx43jyySex2cJnm/Oll14iOzub999/H6h6j2/cuLFB19moilspRffu3cnLy+PZZ5/F6/Vy0UUXNehY0y+llOKqq65iw4YNbN26lczMTNq1axdWGW02GyNHjuSDDz7AZrMxePBg4uPjrY51mNjYWC699FLmzp2LaZqMHDkyrN7MSinatm1L8+bNef755/H7/Vx99dVh9XNWSjFgwAC++OILnn32WQC6d+8edhlvueUWPvvs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\n" }, "metadata": { "needs_background": "light" } } ], "source": [ "m.plot(Q)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] }, { "source": [ "In the center of each cell there is an \"arrow\" that indicates the preferred direction of movement. Since all directions are equal, a dot is displayed.\n", "\n", "Now we need to run the simulation, explore our environment, and learn better distribution of Q-Table values, which will allow us to find the path to the apple much faster.\n", "\n", "## Essence of Q-Learning: Bellman Equation\n", "\n", "Once we start moving, each action will have a corresponding reward, i.e. we can theoretically select the next action based on the highest immediate reward. However, in most of the states the move will not achieve our goal or reaching the apple, and thus we cannot immediately decide which direction is better.\n", "\n", "> It is not the immediate result that matters, but rather the final result, which we will obtain at the end of the simulation.\n", "\n", "In order to account for this delayed reward, we need to use the principles of **[dynamic programming](https://en.wikipedia.org/wiki/Dynamic_programming)**, which allows us to think about out problem recursively.\n", "\n", "Suppose we are now at the state $s$, and we want to move to the next state $s'$. By doing so, we will receive the immediate reward $r(s,a)$, defined by reward function, plus some future reward. If we suppose that our Q-Table correctly reflects the \"attractiveness\" of each action, then at state $s'$ we will chose an action $a'$ that corresponds to maximum value of $Q(s',a')$. Thus, the best possible future reward we could get at state $s'$ will be defined as $\\max_{a'}Q(s',a')$ (maximum here is computed over all possible actions $a'$ at state $s'$). \n", "\n", "This gives the **Bellman formula** for calculating the value of Q-Table at state $s$, given action $a$:\n", "\n", "$$Q(s,a) = r(s,a) + \\gamma \\max_{a'} Q(s',a')$$\n", "\n", "Here $\\gamma$ is so-called **discount factor** that determines to which extent you should prefer current reward over the future reward and vice versa.\n", "\n", "## Learning Algorithm\n", "\n", "Given the equation above, we can now write a pseudo-code for our leaning algorithm:\n", "\n", "* Initialize Q-Table Q with equal numbers for all states and actions\n", "* Set learning rate $\\alpha\\leftarrow 1$\n", "* Repeat simulation many times\n", " 1. Start at random position\n", " 1. Repeat\n", " 1. Select an action $a$ at state $s$\n", " 2. Exectute action by moving to a new state $s'$\n", " 3. If we encounter end-of-game condition, or total reward is too small - exit simulation \n", " 4. Compute reward $r$ at the new state\n", " 5. Update Q-Function according to Bellman equation: $Q(s,a)\\leftarrow (1-\\alpha)Q(s,a)+\\alpha(r+\\gamma\\max_{a'}Q(s',a'))$\n", " 6. $s\\leftarrow s'$\n", " 7. Update total reward and decrease $\\alpha$.\n", "\n", "## Exploit vs. Explore\n", "\n", "In the algorithm above, we did not specify how exactly we should chose an action at step 2.1. If we are choosing the action randomly, we will randomly **explore** the environment, and we are quite likely to die often, and also explore such areas where we would not normally go. An alternative approach would be to **exploit** the Q-Table values that we already know, and thus to chose the best action (with highers Q-Table value) at state $s$. This, however, will prevent us from exploring other states, and quite likely we might not find the optimal solution.\n", "\n", "Thus, the best approach is to balance between exploration and exploitation. This can be easily done by choosing the action at state $s$ with probabilities proportional to values in Q-Table. In the beginning, when Q-Table values are all the same, it would correspond to random selection, but as we learn more about our environment, we would be more likely to follow the optimal route, however, choosing the unexplored path once in a while.\n", "\n", "## Python Implementation\n", "\n", "Now we are ready to implement the learning algorithm. Before that, we also need some function that will convert arbitrary numbers in the Q-Table into a vector of probabilities for corresponding actions:" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [], "source": [ "def probs(v,eps=1e-4):\n", " v = v-v.min()+eps\n", " v = v/v.sum()\n", " return v" ] }, { "source": [ "We add small amount `eps` to the original vector in order to avoid division by 0 in the initial case, when all components of the vector are identical.\n", "\n", "The actual learning algorithm we will run for 5000 experiments, also called **epochs**: " ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ "" ] } ], "source": [ "\n", "from IPython.display import clear_output\n", "\n", "lpath = []\n", "\n", "for epoch in range(10000):\n", " clear_output(wait=True)\n", " print(f\"Epoch = {epoch}\",end='')\n", "\n", " # Pick initial point\n", " m.random_start()\n", " \n", " # Start travelling\n", " n=0\n", " cum_reward = 0\n", " while True:\n", " x,y = m.human\n", " v = probs(Q[x,y])\n", " a = random.choices(list(actions),weights=v)[0]\n", " dpos = actions[a]\n", " m.move(dpos,check_correctness=False) # we allow player to move outside the board, which terminates episode\n", " r = reward(m)\n", " cum_reward += r\n", " if r==end_reward or cum_reward < -1000:\n", " print(f\" {n} steps\",end='\\r')\n", " lpath.append(n)\n", " break\n", " alpha = np.exp(-n / 3000)\n", " gamma = 0.5\n", " ai = action_idx[a]\n", " Q[x,y,ai] = (1 - alpha) * Q[x,y,ai] + alpha * (r + gamma * Q[x+dpos[0], y+dpos[1]].max())\n", " n+=1" ] }, { "source": [ "After executing this algorithm, Q-Table should be updated with values that define the attractiveness of different actions at each step. We can try to visualize Q-Table by plotting a vector at each cell that will point in the desired direction of movement. For simplicity, we draw small circle instead of arrow head." ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "output_type": "display_data", "data": { "text/plain": "
", "image/svg+xml": "\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n", "image/png": "iVBORw0KGgoAAAANSUhEUgAAAW4AAAFpCAYAAAC8p8I3AAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4xLjAsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+17YcXAAAgAElEQVR4nOzdd3xUVd7H8c+Zmkx6IaFLL4oI0kVUQBRdFnRRVFR2UVFBLChYFkUFFdS1woMsggUXRVcXROwgSlMpihCUDkogCaRn+sy95/kjySysBJDM5E6S8+aVVzKTm3u/MyG/OXPuOecKKSWKoihK7WEyOoCiKIryx6jCrSiKUsuowq0oilLLqMKtKIpSy6jCrSiKUsuowq0oilLLRKxwCyEGCyF2CCF2CyEejNRxFEVR6hsRiXHcQggzsBMYBGQDG4DrpJQ/h/1giqIo9UykWtw9gd1Syr1SSj+wCBgWoWMpiqLUK5Eq3E2AA0fdzq64T1EURakmS4T2K45z3zF9MkKIW4FbAaxWa7fOnTtHKEr1+Xw+ysrKSE9PNzpKlYqLi7FarcTFxRkdpUo5OTlkZGRgNpuNjlKl3377jebNmxsdo0rBYJAjR47QqFEjo6NUyel0EgwGSU5ONjpKlY4cOUJiYiJ2u93oKFXatm0bHo/neLUUpJRh/wD6AJ8fdfsh4KGqts/IyJDRbNeuXXLu3LlGxzihxYsXy3Xr1hkd44SmTZsmCwsLjY5RJV3X5fjx442OcUIFBQXyySefNDrGCa1Zs0YuWbLE6BgnNGfOHLlr1y6jY5xQRV08bs2MVFfJBqCtEKKlEMIGXAssjdCxFEVR6pWIdJVIKYNCiPHA54AZeE1KuS0Sx1IURalvItXHjZTyE+CTSO1fURSlvlIzJxUlAnRdZ8OGDbz55pvoul55rkdRwkIVbkWJgM6dOzN37lwKCwtp1KgRZWVlRkc6hqZpHDp0yOgYymmKWFeJotRX33zzDYMGDWLSpEnk5+fj8/n47LPPGDFihNHRgPJ8u3fvJisri65du3LJJZfQsGFDo2Mpf0Cta3Hv3buX9957z+gYilKlYDCIxWIhKyuLDz/8EKvVSiAQMDpWyKxZs3A6ndx77728++677Nixw+hIyh9Uq1rcQ4cOJSYmhl69enH22WezcuXKqJ4Uo9RPAwcOZPz48SxZsgSXy0UgEGDPnj1GxwJg0aJFDBo0iCuvvJLJkyczd+5cJk2aRPfu3aN68tbRpJR4vV4WLlxIixYt6Nu3L7GxsUbHqlG1psW9d+9eYmJimDNnDsOHD+fSSy8lKyvL6FiKclxZWVnMnDmT2267jZycHBISEoyOBMCIESNYvnw5K1aswO/3M2XKFMaMGYPD4TA62inzeDw0bdoUn8/H559/TseOHY2OVONqTeHetGkTPXv2pLS0lNdff52GDRuyevVqdbZeiUpmsxmTyYTJZMJisSDE8Wcu1zSTycSQIUP44YcfsFqt7Nixg+bNm0dNvlPxzjvv8Pjjj9OjRw9uv/12br75ZhYvXmx0rBpVa7pKrr76as4++2xyc3Np1KgREydOJCcnp1b9h1Pqly5durB27Vq2bt3K2WefbXSckFGjRuH3+3nqqac444wzaN26tdGR/pCmTZvyyiuvkJuby/jx4zl48CCXXHKJ0bFqVK1pcQOsXLmSIUOG4HK5yM3N5fbbb6e4uNjoWIpyXBkZGei6Tn5+vtFRfsdms3HhhRcipcTv9xsd5w/p168fn332GcFgkClTpvDtt9/Sq1cvo2PVqFpVuNPT07nooot45JFHyMzM5I033uCRRx5h9+7dRkdTlFqnf//++Hw+vv32W6Oj/GE9evSgR48e3HLLLWzevNnoODWuVhXuSpXdI8nJydx999289dZb7N+/39hQiqLUiNmzZ3P77bczfPhwevbsWS+7S2tl4T5amzZtGD16NFOmTMHtdhsdRzkNy5Yto1+/flxyySUEAgE0TUPTNHXiuQaYTKZaNSV/+vTptGvXjpEjRxodxVC1vnADtGjRgjlz5jBq1ChycnIieqx9+/ZF9X/yYDDIgQMHTr5hFBk8eDCff/45b7/9Nn369KFHjx707NmTjRs3sn37drZv347H4zE6Zp308MMPM336dJxOp9FRTqqkpIRDhw7RqVOnetnKPlqtGVVyMg6Hg5kzZzJz5kxGjx5N27Ztw36MFStW8OGHH9K5c2d69OjBOeecE/ZjVNfbb7/Nli1b6NChA0OGDKkVU5ktFgsWiwWHw8HGjRuB8kkWEyZMCBWUs88+OzRBpH///rVuJES0stlsUTWrsyolJSXMnj2bESNG0KpVK8NybN26lYSEBFq0aHFK23/++eccOHCAFi1acPHFF4ctR50p3ACNGjVi9OjRzJ8/nwkTJpCZmRnW/ZtMJh577DGeeOIJjhw5Uq3C7fF4GDt2bFha761bt6by0m/Jycncc8893HbbbXTo0KFahfvnn3/m6aefrnY+KG9V/xFCCF588cXQ7WXLllFQUADAP//5T/Ly8gC48sorueKKK8KSUYleeXl5bN++nYceesiQ4wcCAW677TYaN26M1+vF6/Uyc+bMY1r+q1evZt68ecf83DnnnENaWlrYL9dXpwo3QNu2bZkwYQJjx47lrbfeCus03v79+3PJJZewZ88ePB5PtdZMiY2N5Y033gjLW76YmBg2bdoElA+VGjBgAIcOHeKmm26q1uPv1KkTU6ZMqXY+gJSUlGpN+x4yZEjo69zc3NBqe//+9795/PHHAbj44otDec1m8wlnA1a2Mq1W62lnOhWVL6Ldu3ePmtmT/2vBggVcd911LFu2zOgox6XrOnfffTdvvPGGYRnKysrYuXMnTzzxBC6Xi379+rF8+fJjptr379+fhx9++Jifa9y4cUSWEqhzhRsgMzOTt956i/HjxzNlyhRatmwZlv3+/PPPfPDBB8yePRtN03jwwQertT8hRNj66ioL9969e/nyyy+56667GDt2LH379q3Wfk2m6DsN0rBhw9A7iYceeij0e1ixYgV//vOfgfI/mNtvvx0oL869e/dGCIGUknXr1rFx40Z0XadHjx707ds3Yn2maWlpFBUVoet6RPYfDk2aNOHgwYNGx6jSli1byMzMDPs76D/igQce4MUXX2TNmjXMnj0bp9PJqFGjmDFjxjHb1dTfS50s3ABxcXFMmTKFN998kxtvvDEsfaKbN2/mgw8+wOv1cskll0RlUVu+fDk+n4+WLVvSvHnzqMwYTke/+A0aNIhBgwYBcPDgQWbPnh3a5quvvgLK+85nzZrFrFmzMJvNjBw5kn379kX1lefrs5UrV7Jy5Ur++c9/Gppj5syZdOjQgXnz5jF+/Hjuv/9+nn76acNOktbZwg3QsmVLbrzxRp599lmefvppkpKSqrW/kSNHsmbNmoi20KprwoQJbNmyhe7duxsdxVBNmjThySefBMDv97NixQoA7r//fsrKypg/f37o7ff999/Pc889Z2RcQwkhmDx5Mv/4xz+YOHGi0XFCpJR88cUXXHbZZdjtdkOzWK1W5syZw/r160lMTOTVV181NE+dLtxQ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G+nVqxf19fV88803hMNhzjvvPCZMmOAc061bN6655poMWtk8JBIJ/vd//5c5c+YwbNiwTJvT5igtLeXrr7/mtNNOy7Qpiixhzpw5lJSU4Pf7WbduHYzKtEV7TlYJ99ixY5k0aRK1tbUcdNBB1NbW8uKLL5Kbm+scU1paygknnNDofVdddRXjxo1r1CaEQAixL8zeIxKJBIsWLeLuu+/OtCltjksuuYR4PM6gQYO49957efXVVykuLs60WYq9QEqJlHKv+liwYAE33XQTgwcP5pFHHmkmyzJDVgk3wLJly/jss89YvXo1GzduJBAINBLgnZUQe+yxx3bwWh944AE6derkvHa73fTu3btljd8NNm3aRNeuXTNtRqvh+++/b3KtysWLF/Pss8/SuXNnNmzYwPr162nXrl1W/5C3RaSUlJSU7LXgQrJg9w033LBXfaxdu5aysjJOOeUU+vTps9c2ZZKsE+5AIMCoUaMYNWrn9zEul4u8vMa12CZPnszkyZMbtd18882NKjj7fD6OPvroRsccdNBBGRsQPP/88/nqq68ycu7WyJw5c1i/vml1Frds2cIDDzzAySefzDnnnMNLL73E8OHDW9hCxY+xLItp06ZhGMZe99WpU6e9jk2fcsopjB8/nhNOOIH7779fhUqykenTpzd6HYlEeOmllxq1ffjhhzz55JON2iZOnEj//v1b3D7F7nHnnXc2+dghQ4bQu3dvOnTowKWXXsqiRYuUt50B3G43Tz31VKbNcLjxxhtZt24djz76aLPcBWSSNivcPyYQCHDZZZc1aquurm7klQP85S9/YcWKFZxyyin85S9/aRFbpkyZwv3336/EpIV47bXX+O677/joo4/4xz/+QYcOHTJtkiILOPnkkzEMg23btvHWW29l2py9Yr8R7p1RWFhIYWFho7Znn30WKWWLimpZWRldu3ZVwt1C9OrVi549e3LKKaegaVmV8arIMB6Pp02MLe3Xwr0zWvqL/vXXX9OzZ88dfjAUzUu2ZxUpFHvDz6qUEMIvhPhCCPGNEGKlEOKuVPuzQoj1QoivU4/BqXYhhHhQCFEihFgmhBja0h+iNfHFF19w4IEHquntCoVij2mKxx0HRkopw0IID7BICPGP1L7JUsofLypyKtAv9fgF8FjqWQFceOGFmTZBoVC0cn5WuGVy+DW9YIgn9fipIdkzgb+l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\n" }, "metadata": { "needs_background": "light" } } ], "source": [ "m.plot(Q)" ] }, { "source": [ "## Checking the Policy\n", "\n", "Since Q-Table lists the \"attractiveness\" of each action at each state, it is quite easy to use it to define the efficient navigation in our world. In the simplest case, we can just select the action corresponding to the highest Q-Table value:" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "output_type": "execute_result", "data": { "text/plain": [ "2" ] }, "metadata": {}, "execution_count": 13 } ], "source": [ "def qpolicy_strict(m):\n", " x,y = m.human\n", " v = probs(Q[x,y])\n", " a = list(actions)[np.argmax(v)]\n", " return a\n", "\n", "walk(m,qpolicy_strict)" ] }, { "source": [ "If you try the code above several times, you may notice that sometimes it just \"hangs\", and you need to press STOP button in the notebook to interrupt it. This happens because there could be situations when two states \"point\" to each other in terms of optimal Q-Value, in which case the agents ends up moving between those states indefinitely.\n", "\n", "> **Task 1:** Modify the `walk` function to limit the maximum length of path by a certain number of steps (say, 100), and watch the code above return this value from time to time.\n", "\n", "> **Task 2:** Modify the `walk` function so that it does not go back to the places where is has already been previously. This will prevent `walk` from looping, however, the agent can still end up being \"trapped\" in a location from which it is unable to escape.\n", "\n", "Better navigation policy would be the one that we have used during training, which combines exploitation and exploration. In this policy, we will select each action with a certain probability, proportional to the values in Q-Table. This strategy may still result in the agent returning back to the position it has already explored, but, as you can see from the code below, it results in very short average path to the desired location (remember that `print_statistics` runs the simulation 100 times): " ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ "Average path length = 3.45, eaten by wolf: 0 times\n" ] } ], "source": [ "\n", "def qpolicy(m):\n", " x,y = m.human\n", " v = probs(Q[x,y])\n", " a = random.choices(list(actions),weights=v)[0]\n", " return a\n", "\n", "print_statistics(qpolicy)" ] }, { "source": [ "## Investigating Learning Process\n", "\n", "As we have mentioned, the learning process is a balance between exploration and exploration of gained knowledge about the structure of problem space. We have seen that the result of learning (the ability to help an agent to find short path to the goal) has improved, but it is also interesting to observe how the average path length behaves during the learning process: " ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "output_type": "execute_result", "data": { "text/plain": [ "[]" ] }, "metadata": {}, "execution_count": 15 }, { "output_type": "display_data", "data": { "text/plain": "
", "image/svg+xml": "\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n", "image/png": "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\n" }, "metadata": { "needs_background": "light" } } ], "source": [ "plt.plot(lpath)" ] }, { "source": [ "What we see here is that at first the average path length increased. This is probably due to the fact that when we know nothing about the environment - we are likely to get trapped into bad states, water or wolf. As we learn more and start using this knowledge, we can explore the environment for longer, but we still do not know well where apples are.\n", "\n", "Once we learn enough, it becomes easier for the agent to achieve the goal, and the path length starts to decrease. However, we are still open to exploration, so we often diverge away from the best path, and explore new options, making the path longer than optimal.\n", "\n", "What we also observe on this graph, is that at some point the length increased abruptly. This indicates stochastic nature of the process, and that we can at some point \"sploil\" the Q-Table coefficients, by overwriting them with new values. This ideally should be minimized by decreasing learning rate (i.e. towards the end of training we only adjust Q-Table values by a small value).\n", "\n", "Overall, it is important to remember that the success and quality of the learning process significantly depends on parameters, such as leaning rate, learning rate decay and discount factor. Those are often called **hyperparameters**, to distinguish them from **parameters** which we optimize during training (eg. Q-Table coefficients). The process of finding best hyperparameter values is called **hyperparameter optimization**, and it deserves a separate topic." ], "cell_type": "markdown", "metadata": {} }, { "source": [ "## Exercise\n", "#### More Realistic Peter and the Wolf World\n", "\n", "In our situation, Peter was able to move around almost without getting tired or hungry. In more realistic world, we has to sit down and rest from time to time, and also to feed himself. Let's make our world more realistic, by implementing the following rules:\n", "\n", "1. By moving from one place to another, Peter loses **energy** and gains some **fatigue**.\n", "2. Peter can gain more energy by eating apples.\n", "3. Peter can get rid of fatigue by resting under the tree or on the grass (i.e. walking into a board location with a tree or grass - green field)\n", "4. Peter needs to find and kill the wolf\n", "5. In order to kill the wolf, Peter needs to have certain levels of energy and fatigue, otherwise he loses the battle.\n", "\n", "Modify the reward function above according to the rules of the game, run the reinforcement learning algorithm to learn the best strategy for winning the game, and compare the results of random walk with your algorithm in terms of number of games won and lost.\n", "\n", "\n", "> **Note**: You may need to adjust hyperparameters to make it work, especially the number of epochs. Because the success of the game (fighting the wolf) is a rare event, you can expect much longer training time.\n", "\n" ], "cell_type": "markdown", "metadata": {} }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] } ] }