{ "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.0" }, "orig_nbformat": 2, "kernelspec": { "name": "python3", "display_name": "Python 3.7.0 64-bit ('3.7')" }, "interpreter": { "hash": "70b38d7a306a849643e446cd70466270a13445e5987dfa1344ef2b127438fa4d" } }, "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": "\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\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": "\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n", "image/png": "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1fB4PKxatYoRI0bw4YcfMn/+fDp27Mj69eutjlZjx44d2O12rrrqKv71r3+xcOFCCgoKOHDggNXRanz66acMGjSIDh064Ha7efHFF1m0aFFY/QX42muv8bvf/Q6n08mll17Kn/70J1577bVGXacUtzhC586d2b59O/369aNNmzZs2bKF7Oxsq2PVkp2dzY8//kj//v1JTU3l+++/p0uXLlbHqhEVFUXr1q1RStG/f38CgQCHDh2iVatWVkerkZaWhmmatGnThvPOO4+ioiKSkpKIj4+3OlqNdu3asWfPHs4//3zOPPNMtm/fTufOneudj/Fky87OJjc3l/79+9OiRQs2btzY6O8XKW5xhO7du1NQUMD8+fN57733eP/99znvvPOsjlXLeeedx5dffsn69eu55557yMvLo3v37lbHquFwOOjcuTNvvvkmLpeLoUOHopQiKyvL6mg1MjIySElJYebMmXi9XiZNmkRWVhaJiYlWR6vRsWNHXC4Xf/vb31i7di0vv/wy55xzTlgVd69evdi4cSPLly/nmWeeYc2aNY0+dBcms7yLcPPFF1/w3Xff8cMPP4TdmCJAcnIyubm5vPfee1x99dVhVdrV+vfvz9atW8nJyWHlypVhtSVb7b777uPee+9lypQpfP/991bHOaq3336bwsJClixZwrZt26yOcwSbzcaWLVv4/PPPUUoxY8aMRl+nFLeoU7du3ejWrZvVMeo1ZMgQqyMc09SpU62OUC+lFH/5y1+sjlGvVq1aceedd1odo14XX3zxSVuXDJUIIUSEkeIWQogII8UthBARRopbCCEijBS3EEJEGCluIYSIMMcsbqXU6Uqpz5RS3yulvlNK/SG0PF0p9YlSKjf0OS20XCmlnldK7VBKbVJKndvY/wghhDiVHM8WdxC4T2vdFbgA+L1SqivwELBCa90JWBH6GuBXQKfQx3jgxQZPLYQQp7BjFrfWulBr/Z/Q7UrgByALuA6YF3rYPOD60O3rgPm6yv8BqUqp8LlAgxBCRLifNcatlGoHnAOsBVporQtDd+0HWoRuZwE/Hva0vaFlP32t8Uqp9Uqp9YGA52fGFkKIU9dxF7dSKhFYBEzSWte6ar2uumr4z7pyuNZ6tta6t9a6t8MR93OeKoQQp7TjKm6llIOq0l6otX4/tLioeggk9Ln6Ir4FwOmHPb11aJkQQogG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1r+LXq+XioqKsM5Y3/tEhcObKD09Xd9///1Wx6iTy+Xi4MGDtGvXzuoodSosLCQmJob09HSro9Rp27ZttG/fPqyHUTZu3MjZZ59tdYw6BQIBvv56F4cONf7F+n+p2NhSzjnHR6tGmv2oIeTl5ZGZmdnoM9WciGeeeYbS0tKj7yTSWlv+kZmZqcNZbm6unj17ttUx6vXBBx/o1atXWx2jXo8//rguLS21OkadTNPUEyZMsDpGvUpKSnSvXjm66pJg4fnRsuXXevHixVZ/q+o1a9YsnZuba3WMeoV68aidKWPcQggRYaS4hRAiwkhxCyFEhJHiFkKICCPFLYQQEUaKWwghIowUtxBCRBgpbiGEiDBS3EIIEWGkuIUQIsJIcQshRISR4hZCiAgjxS2EEBFGilsIISKMFLcQQkQYKW4hhIgwTba4V69eHdZTZAWDQdatW2d1jHqVlJSQm5trdYx67dixg5KSEqtj1Oubb74hGAxaHSOiuVwuNm/ebHWMeu3du5eCgoKTsq4wmXOy4axfv54PPviA2NhY/vWvf3HxxRdz2WWXWR2rlnfffZeNGzcSHR3NkiVLGD16NGeeeabVsWp55plnqKiowGazEQgEeOSRR4iLi7M6Vg2Px8O0adNwOByYpklSUhKTJ0+2OlYtO3bsYO7cucTExLBkyRKys7MZNmyY1bEizssvv8zu3btxOBy89dZbTJo0iebNm1sdq4Zpmjz22GM1G4pKKf70pz9hszXednGT2uLWWrNhwwZM0+QPf/gDLVu25PPPPw+rLW+tNf/85z/p3r07d999N0VFRezatSvsMs6bN48bbriB3/72t3zyySe43W6rY9Xi9Xr597//zejRo7nxxhuZP39+2H0Pd+3axf79+5kwYQJnn302H374YVhljARaaxYuXMill17K+PHj2bhxI8XFxWH1fTRNk7fffpvhw4dz8803884772CaZqOus0kVd35+Pps2baKyspJf/epXjB49mtjYWFavXm11tBrvv/8+F1xwAXPnzmXy5MlMmzaNhQsXUlFRYXW0GlOnTiUnJ4fbbruN5cuX88YbbzB+/HirY9Uybtw4Jk2axI033ojP5+P5559nypQpVseqUVlZyfz588nKymLw4MEMHjyYiy66iEWLFlkdLaL87W9/48477+Shhx7ixRdf5B//+AdTp05t9GL8OcaP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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": [ "Epoch = 2" ] }, { "output_type": "error", "ename": "IndexError", "evalue": "index 8 is out of bounds for axis 0 with size 8", "traceback": [ "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", "\u001b[0;31mIndexError\u001b[0m Traceback (most recent call last)", "\u001b[0;32m\u001b[0m in \u001b[0;36m\u001b[0;34m\u001b[0m\n\u001b[1;32m 28\u001b[0m \u001b[0mgamma\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;36m0.5\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 29\u001b[0m \u001b[0mai\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0maction_idx\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0ma\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m---> 30\u001b[0;31m \u001b[0mQ\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0mx\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0my\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0mai\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m(\u001b[0m\u001b[0;36m1\u001b[0m \u001b[0;34m-\u001b[0m \u001b[0malpha\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m*\u001b[0m \u001b[0mQ\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0mx\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0my\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0mai\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0malpha\u001b[0m \u001b[0;34m*\u001b[0m \u001b[0;34m(\u001b[0m\u001b[0mr\u001b[0m \u001b[0;34m+\u001b[0m \u001b[0mgamma\u001b[0m \u001b[0;34m*\u001b[0m \u001b[0mQ\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0mx\u001b[0m\u001b[0;34m+\u001b[0m\u001b[0mdpos\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;36m0\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0my\u001b[0m\u001b[0;34m+\u001b[0m\u001b[0mdpos\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mmax\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m 31\u001b[0m \u001b[0mn\u001b[0m\u001b[0;34m+=\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", "\u001b[0;31mIndexError\u001b[0m: index 8 is out of bounds for axis 0 with size 8" ] } ], "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)\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": 43, "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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Tz9N/fr1mTRpEuecc47RkY4gpWTOnDmcd9553HHHHSxdupS8vLyIt6sKt6KcBCkl2dnZfPjhh8yaNYusrKyoK47BYJD9+/fz6KOPsnz5cnJzc42OdMqZPn069957L02bNmXKlCm8+eabjB8/Hl3XI9quKtyKcpK6dOlCVlYWVquVTp064ff7jY50hOzsbLp160b37t1ZuHAhV1111fG/SflbxowZw4wZM/jss8/YtGkTt956K5MnT474jShU4VaUkzBr1iwef/xxLr74Ylq3bs20adOYMWOG0bHKSSmZPXs2s2fPxuVyMWbMGAYNGsT8+fONjnbKGTVqFEVFRbjdbq699loyMjIi3qYq3LXEU089Rc+ePfH5fDXmRrCBQIDvvvuO9957j0AgEFVDEb1792bRokU0atSIzz//nOnTp9O7d2+jYx3h4osv5scff+Scc87h3nvvZcWKFVG9e2RNdcMNNzB48GDatWvH6NGjq2XjKlW4a4nx48fz2Wef0aNHD5544gl+/fVXgsGg0bEqJKWkZcuWfPfdd2RlZdGgQYOoGopo2bIlubm5TJw4EQCfz8fTTz/N/v37DU4WIoSgbdu2LFq0iIULF6LrOpmZmcyaNYuioiKj4ymVpAp3LVG2peovv/xC9+7dee2113j11Vf55ptvjI52VF9++SW33nord911Fw6HgyFDhvDpp58aHaucEIIff/yR22+/nauvvpoNGzYwbdo0XnvtNXbs2GF0PADq16/PunXrqF+/Pq+88grr16/niiuuYObMmZSWlhodT6kEVbhrocsuu4xXXnmFRo0a8ccffzBo0CB27txpdKwjxMfH43Q6sdlspKSk4HQ6mTp1qtGx/uLss8+mZ8+eADRu3JjBgwczc+ZM8vPzjQ12mAEDBtC4cehWsD179uTCCy/koYceiqqhJ+XvUQtwaikhBNdffz0ul4vrr7+ecePGsWPHDq655hruu+8+EhIS/nLT3urUo0cP7rzzTnRdp27duvznP//hnXfeoWPHjkyYMIHevXuTmJgYdYsxWrduzfjx4xk4cCDNmjXj5ZdfJjY21uhYR+jevTupqal06tSJ2267jREjRmCxqFJQGdX9c6h63LWcw+GgWbNmfPzxx6xfv55zzz2X/v37s3DhQtatW2dYLiEEW7dupX///rRt25asrCx69+7N+vXr2bJlCzff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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": 58, "metadata": {}, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ "Average path length = 5.31, 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": 57, "metadata": {}, "outputs": [ { "output_type": "execute_result", "data": { "text/plain": [ "[]" ] }, "metadata": {}, "execution_count": 57 }, { "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": [] } ] }