S45_logistics_planning.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "view-in-github",
    "tags": [
     "no-tex"
    ]
   },
   "source": [
    "<a href=\"https://colab.research.google.com/github/gtbook/robotics/blob/main/S45_logistics_planning.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "id": "JoW4C_OkOMhe",
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "%pip install -q -U gtbook\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "id": "10-snNDwOSuC",
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from numpy.random import default_rng\n",
    "rng = default_rng()\n",
    "import plotly.express as px\n",
    "try:\n",
    "    import google.colab\n",
    "except:\n",
    "    import plotly.io as pio\n",
    "    pio.renderers.default = \"png\"\n",
    "\n",
    "from gtbook import logistics\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {
    "id": "nAvx4-UCNzt2"
   },
   "source": [
    "# Planning for Logistics\n",
    "\n",
    "> Our warehouse robot needs to know its location in the warehouse with more precision than the vacuuming robot.\n",
    "\n",
    "<img src=\"Figures4/S45-Warehouse_robots-05.jpg\" alt=\"Splash image with warehouse robot thinking\" width=\"40%\" align=center style=\"vertical-align:middle;margin:10px 0px\">\n",
    "\n",
    "In Chapter 3, we modeled a robot system as an MDP, and saw how to compute both\n",
    "the optimal value function and the corresponding optimal policy.\n",
    "The state space in Chapter 3 was very simple, having only five states.\n",
    "For our vacuuming robot, it was sufficient to know the room in which the\n",
    "robot was located, but this level of detail is not sufficient for our warehouse\n",
    "robot.\n",
    "In order to position itself accurately with respect to the shelves that\n",
    "contain inventory, the warehouse robot needs a quantitative description\n",
    "of its location, namely, coordinates in a warehouse coordinate frame.\n",
    "Therefore, for our warehouse robot, we represent\n",
    "the state space by a discrete grid, whose coordinates\n",
    "define the location of the robot.\n",
    "This representation has significantly more states than for the vacuuming robot.\n",
    "In this section, we show how to perform value iteration on such a grid, and\n",
    "briefly discuss the implications of estimating the state using sensor data.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Value Iteration in 2D\n",
    "\n",
    "> It works, but can be slow."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recall that value iteration starts with an initial guess, $V^0$, and at each iteration we update\n",
    "our approximation of the value function by the update rule:\n",
    "\n",
    "$$\n",
    "V^{k+1}(x) \\leftarrow \\max_a \\left\\{ \\bar{R}(x,a) + \\gamma \\sum_{x'} P(x'|x, a) V^k(x')   \\right\\}\n",
    "= \\max_a Q(x, a; V^k)\n",
    "$$\n",
    "\n",
    "This can be *very* expensive if applied naively, when the number of states is large. Indeed, if we use the 5000-state finite element discretization of the warehouse, the conditional probability table (CPT) above contains $5k \\times 4 \\times 5k = 100M$ entries.\n",
    "\n",
    "There are ways to deal with this, computationally. Indeed, most transitions have zero probability, and hence we could store the CPT in a *sparse* multi-dimensional array instead. Alternatively, we can implement the Q value calculation as a *function*. This is what we will do below, and we will also immediately switch to using the 2D coordinates $(i,j)$ for the discretized cells:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "goal = 35, 50\n",
    "proximity = logistics.base_map + logistics.proximity_map_on\n",
    "\n",
    "def Q_value(x, a, V):\n",
    "    \"\"\"Given a state x=(i,j) action a, and value image, calculate Q value.\"\"\"\n",
    "    i, j = x\n",
    "    if x==goal: return 0 # only reward when *first* arriving at goal\n",
    "    if logistics.base_map[i,j]: return 0 # invalid state\n",
    "    if a == 0: next = (i,j-1) if j>0 else x # LEFT\n",
    "    if a == 1: next = (i,j+1) if j<99 else x # RIGHT\n",
    "    if a == 2: next = (i-1,j) if i>0 else x # UP\n",
    "    if a == 3: next = (i+1,j) if i<49 else x # DOWN\n",
    "    reward = 100 if next==goal else 0\n",
    "    r, c = next\n",
    "    if logistics.proximity_map_on[i,j]: reward -= 50 # in proximity is bad!\n",
    "    if logistics.proximity_map_on[r,c]: reward -= 50 # as is going in proximity.\n",
    "    return reward + 0.975 * V[r,c]\n",
    "\n",
    "def update_V(x, V):\n",
    "    \"\"\"Given a state x=(i,j) and value image, calculate updated value.\"\"\"\n",
    "    Q_x = [Q_value(x, a, V) for a in range(4)]\n",
    "    return max(Q_x)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note above we assumed actions were *deterministic*, but the function can be easily adapted to non-deterministic actions. We awarded 100 points upon reaching the goal, but make sure that happens only once, or otherwise the value of that state will be infinite. In addition, when the state is near an obstacle (we use the `proximity_map_on` likelihood image from Section 4.3), the agent gets punished by 100 points. Below, we do value iteration using a brute force loop, which is still remarkably fast:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "after 86 iterations, error = 0.0\n",
      "CPU times: user 1.44 s, sys: 13.6 ms, total: 1.45 s\n",
      "Wall time: 1.45 s\n"
     ]
    }
   ],
   "source": [
    "I, J = np.meshgrid(range(50), range(100), indexing='ij')\n",
    "states = np.dstack((I, J)).reshape(5000,2)\n",
    "k = 0\n",
    "V_k = np.full((50,100), 0.0)\n",
    "error = float('inf')\n",
    "while error>1e-5:\n",
    "    V_plus = np.empty((50,100), float)\n",
    "    for i,j in states:\n",
    "        V_plus[i,j] = update_V((i,j), V_k)\n",
    "    error = np.max(np.abs(V_plus-V_k))\n",
    "    V_k = V_plus\n",
    "    k += 1\n",
    "print(f\"after {k} iterations, error = {error}\")\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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"
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "#| caption: The converged value function.\n",
    "#| label: fig:converged-value-function\n",
    "px.imshow(V_k, color_continuous_scale='Turbo',origin=\"upper\", aspect='equal')\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the *gradient* of the value function determines the optimal policy: at any cell, we can just look around in all 4 directions and move to the cell with the largest value.\n",
    "\n",
    "### Thought Exercise\n",
    "\n",
    "Why might the algorithm terminate after 86 iterations?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Intuition behind Value Iteration\n",
    "\n",
    "> Costs and rewards propagate.\n",
    "\n",
    "It is instructive to look at an animation for how the value function evolves in successive iterations of the value iteration algorithm:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<figure id=\"fig:value\">\n",
    "<img src=\"https://github.com/gtbook/robotics/blob/main/Figures4/value.gif?raw=1\" style=\"width:14cm\" alt=\"\">\n",
    "<figcaption>The <b>value iteration</b> algorithm, animated.</figcaption>\n",
    "</figure>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The most prominent phenomenon that one can make out in the animation above is that the reward from reaching the goal state, in the middle of the warehouse, gradually propagates towards every location. It gradually decreases in value because of the discount factor. It also does not penetrate the obstacles in the map, because those states simply have a value of zero.\n",
    "\n",
    "There is a deep connection between value iteration and the all-source-shortest-path algorithm that you might have seen in an algorithms class.\n",
    "Deterministic actions set up a graph, and while in this case we have no penalty to moving in the the graph, the discount factor plays the same role in practice.\n",
    "In fact, if we set the discount factor to zero and give actions a cost, both algorithms will return identical results."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Closing the Loop\n",
    "\n",
    "> Adding a state estimator closes the sense-think-act loop.\n",
    "\n",
    "When the robot acts in the world, it senses, estimates its state, and executes a policy. We can take any of the algorithms from the last section and use them to estimate the robot's current state. The value function gives us a policy, which the robot can then execute. After that, repeat.\n",
    "\n",
    "To calculate the policy, we should take into account the uncertainty in actions. The policy we calculated above for the warehouse may not be optimal, because we assumed deterministic actions in the calculation of the Q values. In Section 3.5 we saw how to account for uncertain, Gaussian actions.\n",
    "We could do the same here to potentially obtain a better policy.\n",
    "In particular, the robot will be more cautious and stay even further away from obstacles,\n",
    "since the robot does not always perfectly execute commands.\n",
    "\n",
    "### Thought Exercise\n",
    "\n",
    "Estimating a single location for the robot is not always possible: posterior densities can be *multi-modal*, and so do not know any better than that we are in one of a number of possible locations. What should we do in that case?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Partially Observable MDPs\n",
    "\n",
    "> POMDPs facilitate planning to sense.\n",
    "\n",
    "To *really* calculate the optimal policy, we would need to know how future actions\n",
    "will affect sensing. Even when we take into account the uncertainty in the actions, there is something we have not taken into account: uncertain *sensing*. Indeed, when calculating the optimal policy we have assumed that we have perfect knowledge of the state. The probabilistic model that takes into account uncertain sensing is called a **partially observable Markov decision process**, or POMDP. \n",
    "\n",
    "While out of scope for this book, it is important to be aware of this limitation of the MDP framework. A POMDP policy could improve on this by planning to sense: for example, the robot could deliberately move closer to an RFID beacon on purpose, to re-localize the robot when it is not very certain about its location. \n",
    "\n",
    "POMDPs are computationally incredibly expensive, because the state is no longer simply *where* we are, but also *what we believe* the state is. Hence, POMDPs are about planning in the *belief space*, which is a very high-dimensional concept."
   ]
  }
 ],
 "metadata": {
  "colab": {
   "collapsed_sections": [],
   "include_colab_link": true,
   "name": "S45_logistics_planning.ipynb",
   "provenance": []
  },
  "interpreter": {
   "hash": "c6e4e9f98eb68ad3b7c296f83d20e6de614cb42e90992a65aa266555a3137d0d"
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.18"
  },
  "latex_metadata": {
   "affiliation": "Georgia Institute of Technology",
   "author": "Frank Dellaert and Seth Hutchinson",
   "title": "Introduction to Robotics"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}