notebooks/q_learning_tiny_maze.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# A Simple Q-Learning example\n",
    "![tiny-maze](./assets/tiny-maze.jpg)\n",
    "\n",
    "Images credit: https://huggingface.co/learn/deep-rl-course\n",
    "\n",
    "### Environment:\n",
    "- 6 cell grid, and the mouse always starts in the same spot (upper left)\n",
    "- The goal is to eat the big pile of cheese at the bottom right-hand corner and avoid the poison\n",
    "- Mouse can move left, right, up, down\n",
    "- Can take a maximum of 5 steps per episode\n",
    "- Episode ends if mouse eats poison or big cheese or after taking five steps\n",
    "\n",
    "### Reward function:\n",
    "- +10 for eating big pile of cheese\n",
    "-  +1 for eating small cheese\n",
    "- -10 for eating poison\n",
    "-  +0 for going to a state with no cheese in it"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2D reward map:\n",
      "tensor([[  0.,   1.,   0.],\n",
      "        [  0., -10.,  10.]])\n",
      "\n",
      "Flattened reward map:\n",
      "tensor([[  0.],\n",
      "        [  1.],\n",
      "        [  0.],\n",
      "        [  0.],\n",
      "        [-10.],\n",
      "        [ 10.]])\n"
     ]
    }
   ],
   "source": [
    "import math\n",
    "\n",
    "import pandas as pd\n",
    "import torch\n",
    "from matplotlib import pyplot as plt\n",
    "from torch import Tensor\n",
    "\n",
    "# (x, y) actions\n",
    "ACTIONS = torch.tensor(\n",
    "    [\n",
    "        [-1, 0],  # left\n",
    "        [1, 0],  # right\n",
    "        [0, -1],  # up\n",
    "        [0, 1],  # down\n",
    "    ]\n",
    ")\n",
    "NUM_ACTIONS = ACTIONS.shape[0]\n",
    "REWARDS = torch.tensor([[0.0, 1.0, 0.0], [0.0, -10.0, 10.0]])\n",
    "NUM_STATES = math.prod(REWARDS.shape)\n",
    "\n",
    "print(\"2D reward map:\")\n",
    "print(REWARDS)\n",
    "\n",
    "print(\"\\nFlattened reward map:\")\n",
    "print(REWARDS.flatten()[:, None])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Define state transitions\n",
    "\n",
    "- Assume the 2x3 grid does not wrap around itself\n",
    "    - i.e. if you are at left edge and you choose to move left, you stay at the same spot\n",
    "- Assume the transition from one cell to the next is completely deterministic \n",
    "    - i.e. if you choose to move left (and are able), you go left 100% of the time\n",
    "    - this is in contrast to a stochastic environment (e.g. a slippery grid) where the\n",
    "    chosen action my not result in the intended effect 100% of the time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "State transitions:\n",
      "tensor([[0, 1, 0, 3],\n",
      "        [0, 2, 1, 4],\n",
      "        [1, 2, 2, 5],\n",
      "        [3, 4, 0, 3],\n",
      "        [3, 5, 1, 4],\n",
      "        [4, 5, 2, 5]])\n"
     ]
    }
   ],
   "source": [
    "def init_state_transitions(grid_shape: tuple[int, int], actions: Tensor) -> Tensor:\n",
    "    \"\"\"Initialize deterministic state transition matrix for a 2D grid world.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    grid_shape : tuple[int, int]\n",
    "        The shape of the grid world.\n",
    "    actions : Tensor[num_act, 2]\n",
    "        The set of (dx, dy) actions available to agent at each state.\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    next_states : Tensor[num_states, num_act]\n",
    "        The next state indices for each state-action pair.\n",
    "    \"\"\"\n",
    "    h, w = grid_shape\n",
    "\n",
    "    # Define 2D coordinates for each cell in the grid: (2, h, w)\n",
    "    xy_coords = torch.stack(\n",
    "        torch.meshgrid(torch.arange(w), torch.arange(h), indexing=\"xy\"), dim=0\n",
    "    )\n",
    "\n",
    "    # Apply each action to each state to get coordinates of the next state\n",
    "    # (num_act, 2, 1, 1) + (1, 2, h, w) -> (num_act, 2, h, w)\n",
    "    next_xy_coords = actions[..., None, None] + xy_coords[None, ...]\n",
    "\n",
    "    # Clip out-of-bounds coordinates\n",
    "    lb = torch.tensor([0, 0]).view(1, 2, 1, 1)\n",
    "    ub = torch.tensor([w - 1, h - 1]).view(1, 2, 1, 1)\n",
    "    next_xy_coords = next_xy_coords.clamp(lb, ub)\n",
    "\n",
    "    # Convert 2D coordinates to 1D state indices\n",
    "    # (num_act, 2, h, w) -> (num_act, h, w)\n",
    "    next_states = next_xy_coords[:, 1, ...] * w + next_xy_coords[:, 0, ...]\n",
    "\n",
    "    # Flatten the state indices\n",
    "    # (num_act, h, w) -> (num_act, num_states)\n",
    "    next_states = next_states.view(actions.size(0), -1)\n",
    "\n",
    "    # Transpose: (num_states, num_act)\n",
    "    return next_states.T\n",
    "\n",
    "\n",
    "next_states = init_state_transitions(REWARDS.shape, ACTIONS)\n",
    "\n",
    "print(\"\\nState transitions:\")\n",
    "print(next_states)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Define update for Q-table\n",
    "\n",
    "![update-formula](assets/q-table-update.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def update_q_table(\n",
    "    q_table: Tensor,\n",
    "    state_action: tuple[int, int],\n",
    "    reward: float,\n",
    "    next_state: int | None,\n",
    "    gamma: float,\n",
    "    learning_rate: float,\n",
    ") -> Tensor:\n",
    "    \"\"\"Update Q-table (state, action) pair.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    q_table: Tensor[num_states, num_act, dtype=float32]\n",
    "        The Q-table to update.\n",
    "    state_action: tuple[int, int]\n",
    "        State-action pair to update.\n",
    "    reward: float\n",
    "        The reward | action.\n",
    "    next_state: int | None\n",
    "        The next state | action.\n",
    "    gamma : float\n",
    "        Future value discount factor.\n",
    "    learning_rate : float\n",
    "        Learning rate.\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    updated_q_table: Tensor[num_states, num_act, dtype=float32]\n",
    "        The updated Q-table.\n",
    "    \"\"\"\n",
    "    # Compute the maximum Q-value for next state\n",
    "    max_q_value = 0.0\n",
    "    if next_state is not None:\n",
    "        max_q_value = q_table[next_state].max(dim=-1).values\n",
    "\n",
    "    # Compute the temporal difference target\n",
    "    td_target = reward + gamma * max_q_value\n",
    "\n",
    "    # Compute update for state-action pair\n",
    "    state, action = state_action\n",
    "    q_table[state, action] = (\n",
    "        q_table[state, action] * (1 - learning_rate) + learning_rate * td_target\n",
    "    )\n",
    "\n",
    "    return q_table"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. Initialize Q-table"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "tensor([[0., 0., 0., 0.],\n",
       "        [0., 0., 0., 0.],\n",
       "        [0., 0., 0., 0.],\n",
       "        [0., 0., 0., 0.],\n",
       "        [0., 0., 0., 0.],\n",
       "        [0., 0., 0., 0.]])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def init_q_table(num_states: int, num_actions: int) -> Tensor:\n",
    "    \"\"\"Initialize the Q-table with zeros for all (state, action) pairs.\"\"\"\n",
    "    return torch.zeros(num_states, num_actions)\n",
    "\n",
    "\n",
    "q_table = init_q_table(NUM_STATES, NUM_ACTIONS)\n",
    "q_table"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2. Define epsilon-greedy policy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_action(q_table: Tensor, state: int, epsilon: float) -> int:\n",
    "    \"\"\"Select an action using an epsilon-greedy strategy.\"\"\"\n",
    "    if torch.rand(()) < epsilon:\n",
    "        # Choose a random action\n",
    "        return torch.randint(q_table.shape[-1], ()).item()\n",
    "    else:\n",
    "        # Given the current state, choose the best action in the Q-table\n",
    "        return q_table[state].argmax().item()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3. Learning"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set hyperparameters\n",
    "LR = 0.1  # learning rate\n",
    "GAMMA = 0.99  # future reward discount rate\n",
    "\n",
    "# Initialize epsilon (exploration vs exploitation tradeoff) to 1.0 (full exploration)\n",
    "epsilon = 1.0\n",
    "\n",
    "# Initialize state to upper left\n",
    "state = 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Learn for one time step\n",
    "\n",
    "1. Starting from the upper left square, choose an action using Epsilon greedy strategy\n",
    "    - assume we sampled move right (`action=1`)\n",
    "2. Perform action, get reward and next state\n",
    "\n",
    "![state1](assets/tiny-maze-state1.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "state: 0, action: 1\n",
      "reward: 1.0, next_state: 1\n"
     ]
    }
   ],
   "source": [
    "# Choose an action using the Epsilon Greedy Strategy\n",
    "torch.manual_seed(6)\n",
    "action = get_action(q_table, state, epsilon)\n",
    "print(f\"state: {state}, action: {action}\")\n",
    "\n",
    "# Perform action At, get Rt+1 and St+1\n",
    "next_state = next_states[state, action].item()\n",
    "reward = REWARDS.flatten()[next_state].item()\n",
    "print(f\"reward: {reward}, next_state: {next_state}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " 3. Update `Q(St, At)`\n",
    "\n",
    " ![updated](assets/tiny-maze-update1.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Updated Q-table:\n",
      "   left  right   up  down\n",
      "0   0.0    0.1  0.0   0.0\n",
      "1   0.0    0.0  0.0   0.0\n",
      "2   0.0    0.0  0.0   0.0\n",
      "3   0.0    0.0  0.0   0.0\n",
      "4   0.0    0.0  0.0   0.0\n",
      "5   0.0    0.0  0.0   0.0\n"
     ]
    }
   ],
   "source": [
    "# Update q-table\n",
    "q_table = update_q_table(\n",
    "    q_table, (state, action), reward, next_state, gamma=GAMMA, learning_rate=LR\n",
    ")\n",
    "\n",
    "print(\"\\nUpdated Q-table:\")\n",
    "print(\n",
    "    pd.DataFrame(\n",
    "        data=q_table.numpy().round(2),\n",
    "        columns=[\"left\", \"right\", \"up\", \"down\"],\n",
    "    )\n",
    ")\n",
    "\n",
    "# Set state to next state\n",
    "state = next_state"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Learn for another time step\n",
    "\n",
    "1. choose next action using Epsilon greedy strategy\n",
    "    - assume we sampled move down (`action=3`)\n",
    "2. Perform action, get reward and next state\n",
    "\n",
    "![state1](assets/tiny-maze-state2.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "state: 1, action: 3\n",
      "reward: -10.0, next_state: 4\n",
      "\n",
      "Updated Q-table:\n",
      "   left  right   up  down\n",
      "0   0.0    0.1  0.0   0.0\n",
      "1   0.0    0.0  0.0  -1.0\n",
      "2   0.0    0.0  0.0   0.0\n",
      "3   0.0    0.0  0.0   0.0\n",
      "4   0.0    0.0  0.0   0.0\n",
      "5   0.0    0.0  0.0   0.0\n"
     ]
    }
   ],
   "source": [
    "state = next_state\n",
    "# Choose an action using the Epsilon Greedy Strategy\n",
    "torch.manual_seed(0)\n",
    "action = get_action(q_table, state, epsilon)\n",
    "print(f\"state: {state}, action: {action}\")\n",
    "\n",
    "# Perform action At, get Rt+1 and St+1\n",
    "next_state = next_states[state, action].item()\n",
    "reward = REWARDS.flatten()[next_state].item()\n",
    "print(f\"reward: {reward}, next_state: {next_state}\")\n",
    "\n",
    "# Update q-table\n",
    "q_table = update_q_table(\n",
    "    q_table,\n",
    "    (state, action),\n",
    "    reward,\n",
    "    None,  # episode terminated\n",
    "    gamma=GAMMA,\n",
    "    learning_rate=LR,\n",
    ")\n",
    "\n",
    "print(\"\\nUpdated Q-table:\")\n",
    "print(\n",
    "    pd.DataFrame(\n",
    "        data=q_table.numpy().round(2),\n",
    "        columns=[\"left\", \"right\", \"up\", \"down\"],\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Run for several episodes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Final Q-table:\n",
      "   left  right    up   down\n",
      "0  9.86  10.80  9.62   7.92\n",
      "1  9.81   9.90  7.48  -9.94\n",
      "2  7.39   9.22  9.06  10.00\n",
      "3  2.61  -7.71  9.37   3.25\n",
      "4  0.00   0.00  0.00   0.00\n",
      "5  0.00   0.00  0.00   0.00\n"
     ]
    },
    {
     "data": {
      "image/png": "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lmXZH374oW3btn3nnXfaAOy//e1vju1+/OMf2wDs++67L3Xb3nvvbQ8cONDevn27Y9tjjz3W7tChg71z587cTw4RKcPUBSKK3Isvvojq6mqcdNJJjtubRrpeeOEFoXbuuusu7L///qioqEBJSQlKS0vxwgsvYOnSpdJ9u+OOO1BaWoqysjLsueee+Mc//oH/+7//w6BBg1LbPPPMM+jXrx/2228/7NixI/XviCOOcFST6NWrF7p37465c+cCAObMmYP+/fvjrLPOwrJly/DJJ5+goaEBCxYswJgxY6Qf27hx41BaWpr6/bvvvsOiRYvwwx/+EBUVFanba2pqMHbsWKHn4bzzzsPChQvx4Ycfpm677777cMABB6Bfv34AgP322w9lZWX4yU9+ggceeCArlcBPr169sGjRoqx/TaP36c4880zH78OHD0e3bt1SaRpuDjjgAADAKaecgscffxxffPFF1jYvvvgi+vTpgx/84AeO288991zYtp0a/Z03bx5qamowbtw4x3aZedsff/wxPvjgg1R/0/8+jj76aKxatcrxnBKRXgx0iShya9asQV1dXVaZq3bt2qGkpARr1qzxbWPWrFmYMGEChgwZgieffBKvvvoqFi1ahCOPPBJbtmyR7tspp5yCRYsWYeHChbj77rtRU1OD0047DR999FFqm6+++grvvvsuSktLHf9qampg2za+/fbb1LajR49OBe5z587FYYcdhv79+6N9+/aYO3cu/v3vf6cui8s+tg4dOjh+X7duHRobG1FXV5e1rdttbs4880yUl5enymYtWbIEixYtwnnnnZfaplevXpg7dy7atWuHiy66CL169UKvXr1w++23Cx2joqICgwcPzvrXrVs3oX7X1dXl/Fs55JBD8Ne//hU7duzAOeecg86dO6Nfv36OcnFr1qzJev4AoGPHjqn7m/7bvn173341pYZcccUVWX8fEydOBADH3wcR6cUcXSKKXOvWrfHaa6/Btm1HsPv1119jx44daNOmjW8bDz30EEaOHIk777zTcfvGjRtD9a1t27YYPHgwgF1VF/bZZx+MGDECkydPxjPPPAMAaNOmDSorK/GnP/3JtY30/o8ePRr33nsvXn/9dbz22mu46qqrAACHHnoo5syZg+XLl6NZs2aOHOCgjy3zC0PLli1hWZbrRCmvyVOZWrZsieOOOw4PPvggrr/+etx3332oqKjA6aef7tju4IMPxsEHH4ydO3fijTfewP/+7/9i0qRJaN++PU477TShY4nweix77LFHzv2OO+44HHfccWhoaMCrr76KmTNn4owzzkD37t0xbNgwtG7dGqtWrcra78svvwSw+1y2bt0ar7/+um+/mrafMmUKfvjDH7r2aa+99srZZyJShyO6RBS50aNHY9OmTVkLQTz44IOp+5uUl5e7jmJalpVVQuvdd9/NquEb1sEHH4xzzjkHs2fPTrV97LHH4pNPPkHr1q1dRyTTZ/6PHj0almXh6quvRlFREQ455BAAwJgxYzBv3jzMmTMHhxxyiCP1IOxjq66uxg9+8AM89dRT2Lp1a+r2jRs3pio7iDjvvPPw5Zdf4tlnn8VDDz2EE044wXPiV3FxMYYMGYLf//73AHZVklAps97uwoULsXz5cuFJh+Xl5RgxYgRuuukmAMDbb78NYNf5WbJkSVZ/H3zwQViWhVGjRgEARo0ahY0bN+Lpp592bPfII484ft9rr73Qu3dvvPPOO65/G4MHD0ZNTY3w4yaicDiiS0SRO+ecc/D73/8e48ePx2effYb+/ftjwYIFuOGGG3D00Uc7LuP3798fL730Ev7+97+jQ4cOqKmpwV577YVjjz0W06dPx9SpUzFixAh8+OGHuO6669CjRw/XmfxhTJ8+HY899hiuvvpqzJ07F5MmTcKTTz6JQw45BJMnT8aAAQPQ2NiIFStW4Pnnn8fll1+OIUOGANiVjtGvXz88//zzGDVqVKoSwZgxY7B27VqsXbsWs2bNchxPxWObPn06jjzySBx22GG4/PLLsXPnTtx0002orq5OVXXwc/jhh6Nz586YOHEiVq9e7UhbAHblEb/44os45phj0LVrV2zdujU1yp2Zc+xmy5YtePXVV13vy6yv+8Ybb+CCCy7AySefjJUrV+JXv/oVOnXqlEoHcHPNNdfg888/x+jRo9G5c2esX78et99+O0pLSzFixAgAwOTJk/Hggw/imGOOwXXXXYdu3bph9uzZuOOOOzBhwgTsueeeAHb9zf7617/GOeecgxkzZqB379549tln8dxzz2Ud9+6778ZRRx2FI444Aueeey46deqEtWvXYunSpXjrrbccpeWISLOYJ8MRUQHIrLpg27a9Zs0a+8ILL7Q7dOhgl5SU2N26dbOnTJlib9261bHd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32g5pwx0Y1BWVoZBgwZhzpw5jtvnzJmD4cOHx9QramLbNi6++GI89dRTePHFF9GjRw/H/T169EBdXZ3j/G3btg3z589Pnb9BgwahtLTUsc2qVavwn//8h+c4AqNHj8Z7772HxYsXp/4NHjwYZ555JhYvXoyePXvyHBruwAMPzCrr99///hfdunUDwNdhEmzevBlFRc4wo7i4OFVejOcwWVSdr2HDhmHDhg14/fXXU9u89tpr2LBhg55zqnx6GwlpKi9277332kuWLLEnTZpkV1dX25999lncXSt4EyZMsGtra+2XXnrJXrVqVerf5s2bU9vceOONdm1trf3UU0/Z7733nn366ae7lljp3LmzPXfuXPutt96yDz30UJbEiVF61QXb5jk03euvv26XlJTYM2bMsD/66CP74YcftquqquyHHnootQ3PodnGjx9vd+rUKVVe7KmnnrLbtGlj/+IXv0htw3Nolo0bN9pvv/22/fbbb9sA7FmzZtlvv/12qvSpqvN15JFH2gMGDLBfeeUV+5VXXrH79+/P8mL56Pe//73drVs3u6yszN5///1T5asoXgBc/913332pbRobG+2pU6fadXV1dnl5uX3IIYfY7733nqOdLVu22BdffLHdqlUru7Ky0j722GPtFStWRPxoqElmoMtzaL6///3vdr9+/ezy8nJ77733tu+55x7H/TyHZquvr7cvvfRSu2vXrnZFRYXds2dP+1e/+pXd0NCQ2obn0Czz5s1z/fwbP368bdvqzteaNWvsM888066pqbFramrsM8880163bp2Wx2TZtm2rHycmIiIiIooXc3SJiIiIKC8x0CUiIiKivMRAl4iIiIjyEgNdIiIiIspLDHSJiIiIKC8x0CUiIiKivMRAl4iIiIjyEgNdIiIiIspLDHSJiBLss88+g2VZWLx4sbZjnHvuuTj++OO1tU9EpAsDXSKiGJ177rmwLCvr35FHHim0f5cuXbBq1Sr069dPc0+JiJKnJO4OEBEVuiOPPBL33Xef47by8nKhfYuLi1FXV6ejW0REiccRXSKimJWXl6Ours7xr2XLlgAAy7Jw55134qijjkJlZSV69OiBJ554IrVvZurCunXrcOaZZ6Jt27aorKxE7969HUH0e++9h0MPPRSVlZVo3bo1fvKTn2DTpk2p+3fu3InLLrsMLVq0QOvWrfGLX/wCtm07+mvbNm6++Wb07NkTlZWV2HffffHnP/9Z4zNERCSHgS4RkeGuvvpqnHjiiXjnnXdw1lln4fTTT8fSpUs9t12yZAn+8Y9/YOnSpbjzzjvRpk0bAMDmzZtx5JFHomXLlli0aBGeeOIJzJ07FxdffHFq/9tuuw1/+tOfcO+992LBggVYu3Yt/vKXvziOcdVVV+G+++7DnXfeiffffx+TJ0/GWWedhfnz5+t7EoiIZNhERBSb8ePH28XFxXZ1dbXj33XXXWfbtm0DsC+88ELHPkOGDLEnTJhg27ZtL1u2zAZgv/3227Zt2/bYsWPt8847z/VY99xzj92yZUt706ZNqdtmz55tFxUV2atXr7Zt27Y7dOhg33jjjan7t2/fbnfu3Nk+7rjjbNu27U2bNtkVFRX2woULHW3/6Ec/sk8//XT5J4KISAPm6BIRxWzUqFG48847Hbe1atUq9fOwYcMc9w0bNsyzysKECRNw4okn4q233sLhhx+O448/HsOHDwcALF26FPvuuy+qq6tT2x944IFobGzEhx9+iIqKCqxatcpxvJKSEgwePDiVvrBkyRJs3boVhx12mOO427Ztw8CBA4M/eCIijRjoEhHFrLq6GnvssUegfSzLcr39qKOOwvLlyzF79mzMnTsXo0ePxkUXXYRbb70Vtm177ud1e6bGxkYAwOzZs9GpUyfHfaIT6IiIosIcXSIiw7366qtZv++9996e27dt2xbnnnsuHnroIfzmN7/BPffcAwDo06cPFi9ejO+++y617b///W8UFRVhzz33RG1tLTp06OA43o4dO/Dmm2+mfu/Tpw/Ky8uxYsUK7LHHHo5/Xbp0UfWQiYiU4IguEVHMGhoasHr1asdtJSUlqUlkTzzxBAYPHoyDDjoIDz/8MF5//XXce++9rm1dc801GDRoEPr27YuGhgY888wz2GeffQAAZ555JqZOnYrx48dj2rRp+Oabb/Czn/0MZ599Ntq3bw8AuPTSS3HjjTeid+/e2GeffTBr1iysX78+1X5NTQ2uuOIKTJ48GY2NjTjooINQX1+PhQsXolmzZhg/fryGZ4iISA4DXSKimP3zn/9Ehw4dHLfttdde+OCDDwAA1157LR599FFMnDgRdXV1ePjhh9GnTx/XtsrKyjBlyhR89tlnqKysxMEHH4xHH30UAFBVVYXnnnsOl156KQ444ABUVVXhxBNPxKxZs1L7X3755Vi1ahXOPfdcFBUV4fzzz8cJJ5yADRs2pLaZPn062rVrh5kzZ+LTTz9FixYtsP/+++OXv/yl6qeGiCgUy7YzCiQSEZExLMvCX/7yFy7BS0QkgTm6RERERJSXGOgSERERUV5iji4RkcGYXUZEJI8jukRERESUlxjoEhEREVFeYqBLRERERHmJgS4RERER5SUGukRERESUlxjoEhEREVFeYqBLRERERHmJgS4RERER5aX/Dweg7zqCW2N3AAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 800x600 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "torch.manual_seed(1234)\n",
    "EPSILON_DECAY = 0.995\n",
    "\n",
    "# Re-initialize Q-table\n",
    "q_table = init_q_table(NUM_STATES, NUM_ACTIONS)\n",
    "epsilon = 1.0\n",
    "\n",
    "total_rewards = []\n",
    "for _ in range(1_000):\n",
    "    total_reward = 0.0\n",
    "    num_steps = 0\n",
    "    state = 0\n",
    "    small_cheese_available = True\n",
    "\n",
    "    while num_steps < 5:\n",
    "        num_steps += 1\n",
    "\n",
    "        # Choose an action using the Epsilon Greedy Strategy\n",
    "        action = get_action(q_table, state, epsilon)\n",
    "\n",
    "        # Perform action At, get Rt+1 and St+1\n",
    "        next_state = next_states[state, action].item()\n",
    "        reward = REWARDS.flatten()[next_state].item()\n",
    "\n",
    "        # Check if small cheese is available\n",
    "        if reward == 1.0:\n",
    "            if small_cheese_available:\n",
    "                small_cheese_available = False\n",
    "            else:\n",
    "                reward = 0.0\n",
    "\n",
    "        # Update total reward\n",
    "        total_reward += reward\n",
    "\n",
    "        # Check if terminal condition\n",
    "        if int(reward) in (-10, 10) or num_steps == 5:\n",
    "            next_state = None\n",
    "\n",
    "        # Update q-table\n",
    "        q_table = update_q_table(\n",
    "            q_table, (state, action), reward, next_state, gamma=GAMMA, learning_rate=LR\n",
    "        )\n",
    "\n",
    "        if next_state is None:\n",
    "            break\n",
    "\n",
    "        # Set state to next state\n",
    "        state = next_state\n",
    "\n",
    "    total_rewards.append(total_reward)\n",
    "\n",
    "    # Decay epsilon\n",
    "    epsilon *= EPSILON_DECAY\n",
    "\n",
    "print(\"\\nFinal Q-table:\")\n",
    "print(\n",
    "    pd.DataFrame(\n",
    "        data=q_table.numpy().round(2),\n",
    "        columns=[\"left\", \"right\", \"up\", \"down\"],\n",
    "    )\n",
    ")\n",
    "\n",
    "_, ax = plt.subplots(figsize=(8, 6))\n",
    "ax.plot(total_rewards)\n",
    "ax.set_xlabel(\"Episode\")\n",
    "ax.set_ylabel(\"Total Reward\")\n",
    "ax.set_title(\"Total Reward vs Episode\");"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "r2seedo_default_3.10",
   "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.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}