{
"cells": [
{
"cell_type": "markdown",
"metadata": {
"id": "zmGMC19UJ5US"
},
"source": [
"# Q* Learning - FrozenLake\n",
"
\n",
"In this Notebook, we'll implement an agent that plays FrozenLake.\n",
"\n",
"\n",
"The goal of this game is to go from the starting state (S) to the goal state (G) by walking only on frozen tiles (F) and avoid holes (H).However, the ice is slippery, so you won't always move in the direction you intend (stochastic environment)\n",
"\n",
"\n",
"Reference: code adapted from \n",
"https://github.com/simoninithomas/Deep_reinforcement_learning_Course/blob/master/Q%20learning/FrozenLake/Q%20Learning%20with%20FrozenLake.ipynb"
]
},
{
"cell_type": "code",
"execution_count": 18,
"metadata": {},
"outputs": [],
"source": [
"#!pip install gym\n",
"#!pip install pygame\n",
"#!pip install gym[toy_text]"
]
},
{
"cell_type": "code",
"execution_count": 41,
"metadata": {
"id": "KX-Fw7v4J5UZ"
},
"outputs": [],
"source": [
"import numpy as np\n",
"import gymnasium as gym #to load the FrozenLake Environment\n",
"import random\n",
"import matplotlib.pyplot as plt\n",
"from tqdm import tqdm"
]
},
{
"cell_type": "code",
"execution_count": 42,
"metadata": {
"id": "X_h3ApK2J5Ub"
},
"outputs": [],
"source": [
"#env = gym.make(\"FrozenLake-v0\")\n",
"env = gym.make(\"FrozenLake-v1\",is_slippery=True, render_mode=\"rgb_array\")#creates the FrozenLake environment using the gym library of environments"
]
},
{
"cell_type": "code",
"execution_count": 43,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/"
},
"id": "tr-uf16VY3_u",
"outputId": "8e82ced5-cb5b-4212-ae51-0eb6b4837fca"
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"(0, 1) {'render_modes': ['human', 'ansi', 'rgb_array'], 'render_fps': 4} EnvSpec(id='FrozenLake-v1', entry_point='gymnasium.envs.toy_text.frozen_lake:FrozenLakeEnv', reward_threshold=0.7, nondeterministic=False, max_episode_steps=100, order_enforce=True, autoreset=False, disable_env_checker=False, apply_api_compatibility=False, kwargs={'map_name': '4x4', 'is_slippery': True, 'render_mode': 'rgb_array'}, namespace=None, name='FrozenLake', version=1, additional_wrappers=(), vector_entry_point=None) True\n"
]
}
],
"source": [
"print(env.reward_range,\n",
"env.metadata,\n",
"env.spec,\n",
"env.action_space.contains(2))\n",
"#env.desc"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "tI6jNGGGJ5Uc"
},
"source": [
"## Step 2: Create the Q-table and initialize it "
]
},
{
"cell_type": "code",
"execution_count": 56,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/"
},
"id": "D56Cx9qFJ5Ud",
"outputId": "fd3dcd5b-2c26-424a-a309-3f6510fecd5b"
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[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.]\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.]\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.]]\n"
]
}
],
"source": [
"action_size = env.action_space.n#how many actions there are\n",
"state_size = env.observation_space.n#how many states there are\n",
"qtable = np.zeros((state_size, action_size))\n",
"print(qtable)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "KLFrS3ZBJ5Ue"
},
"source": [
"## Set the hyperparameters"
]
},
{
"cell_type": "code",
"execution_count": 82,
"metadata": {
"id": "EZm2e-GgJ5Uf"
},
"outputs": [],
"source": [
"total_episodes = 100000 # Total episodes\n",
"learning_rate = 0.1 # Learning rate\n",
"max_steps = 99 # Max steps per episode\n",
"gamma_rate = 0.95 # Discounting rate\n",
"\n",
"# Exploration parameters\n",
"epsilon = 0.1 # Exploration rate\n",
"max_epsilon = 0.5 # Exploration probability at start\n",
"min_epsilon = 0.01 # Minimum exploration probability \n",
"decay_rate = 0.00 # Exponential decay rate for exploration prob"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "-lKJgdBrJ5Uf"
},
"source": [
"## Step 4: The Q learning algorithm\n",
"- Now we implement the Q learning algorithm:\n",
""
]
},
{
"cell_type": "code",
"execution_count": 83,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/"
},
"id": "xkHnw4xRJ5Ug",
"outputId": "41edd8e0-b7bb-4b09-9f39-9962ba18b235"
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"100%|████████████████████████████████████████████████████████████████████████| 100000/100000 [00:33<00:00, 2953.68it/s]"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Score over time: 0.06593\n",
"[[0.20347961 0.19008793 0.18279287 0.16275031]\n",
" [0.12898313 0.12223314 0.0918051 0.16072054]\n",
" [0.16794211 0.12811276 0.13132457 0.12330826]\n",
" [0.09240822 0.10668145 0.08644751 0.11979974]\n",
" [0.23218042 0.13470434 0.16046652 0.09655688]\n",
" [0. 0. 0. 0. ]\n",
" [0.10072162 0.13757525 0.23422603 0.06172131]\n",
" [0. 0. 0. 0. ]\n",
" [0.16425028 0.17606014 0.1900038 0.28160554]\n",
" [0.26978022 0.35606627 0.3080447 0.26926482]\n",
" [0.45354802 0.34515262 0.27311533 0.23713359]\n",
" [0. 0. 0. 0. ]\n",
" [0. 0. 0. 0. ]\n",
" [0.21108571 0.33906931 0.52847699 0.38597214]\n",
" [0.49578442 0.83928041 0.66915172 0.62838965]\n",
" [0. 0. 0. 0. ]]\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"\n"
]
}
],
"source": [
"# List of rewards\n",
"rewards = []\n",
"\n",
"for episode in tqdm(range(total_episodes)):\n",
" # Reset the environment\n",
" state,_= env.reset()\n",
" step = 0\n",
" done = False\n",
" total_rewards = 0\n",
" \n",
" for step in range(max_steps):\n",
" # epsilon-greedy strategy\n",
" exploration_or_exploitation = random.uniform(0, 1)\n",
" \n",
" ## If this number > greater than epsilon --> exploitation (taking the biggest Q value for this state)\n",
" if exploration_or_exploitation > epsilon:\n",
" action = np.argmax(qtable[state,:])\n",
"\n",
" # Else doing a random choice --> exploration\n",
" else:\n",
" action = env.action_space.sample()\n",
"\n",
" # Take the action (a) and observe the outcome state(s') and reward (r)\n",
" new_state, reward, terminated, truncated, info = env.step(action)\n",
"\n",
" # Update Q(s,a):= Q(s,a) + lr [R(s,a) + gamma * max Q(s',a') - Q(s,a)]\n",
" # qtable[new_state,:] : all the actions we can take from new state\n",
" qtable[state, action] += learning_rate * (reward + gamma_rate * np.max(qtable[new_state, :]) - qtable[state, action])\n",
" \n",
" total_rewards += reward\n",
" \n",
" # Our new state is state\n",
" state = new_state\n",
" \n",
" # If done (if we're dead) : finish episode\n",
" if terminated|truncated: \n",
" break\n",
" \n",
" # Schedule to reduce epsilon\n",
" epsilon = min_epsilon + (max_epsilon - min_epsilon)*np.exp(-decay_rate*episode) \n",
" rewards.append(total_rewards)\n",
"\n",
"print (\"Score over time: \" + str(sum(rewards)/total_episodes))\n",
"print(qtable)"
]
},
{
"cell_type": "code",
"execution_count": 88,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 297
},
"id": "_aE_ET6ofiq2",
"outputId": "6255e6de-5d2d-4426-82d1-e49d15109a4c"
},
"outputs": [
{
"data": {
"image/png": "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b9uLfrj3ZO3mCfH2+f6kb7OyshI/Pz92vQC+DhxrX7kPOj8IFRUV+Pr6Om7FLcipR/VNvHEmXp57+e/rk8jK6Y27WzVjR31N8mPJmEMb7w6oqbEN+rFaO7ByzaB6r5VYdHM0R5pw8xy8PPfx0qs3sWFjBO5uNYy+fCFP/+tlzF0bLx+X7fIld0v9G3DtKLJ1zRX94QZ2H76VyNPP3sHHaSPZlBtOz/ACxo35jkfuf6dldqgdmXBzGl6e+3jxtZvZsDESd7dqRl/+PU//86Umj115uV8Dx872R/yPNx9ctORM1vxq++Z+v6ojDnPbrV/h5bmPl1+5huzscNzda7jyyqU8OeUtuna1NNquvNyX3C31b562c6ctMTnc/VNd08n+msXSGYuls+N3QJyWU1dIpPVXSKRxrb1CIg1r7RUSaZwqJMZy2jEkIiIi0nY4dZeNiIhIm3CCT+htcn1tjCokIiIiYjglJCIiImI4ddmIiIgYTV02qpCIiIiI8ZSQiIiIiOGUkIiIiIjhNIZERETEaBpDogqJiIiIGE8JiYiIiBhOXTYiIiIGM5lskyPX19aoQiIiIiKGU0IiIiIihlNCIiIiIobTGBIRERGj6bJfJSQiIiKGU0KiLhsRERExnhISERERMZwSEhERETGcxpCIiIgYTWNIVCERERER4ykhEREREcOpy0ZERMRo6rJRhURERESMp4REREREDKeERERERAx33GNITAcOtGQc0kJKQy4zOgQ5Qd22v210CHICSgKuMDoEOUHeRm5cY0hUIRERERHjKSERERERw+myXxEREaOpy0YVEhERETGeEhIRERExnBISERERMZwSEhERETGcBrWKiIgYTYNaVSERERER4ykhEREREcMpIRERERHDKSERERExmqkFpmaaOXMmMTExeHh44O/vz7hx48jJyTlmuy1btnDLLbfQtWtXXF1dCQkJYdSoUVRUVDRr+xrUKiIi0s6lpqYyadIkACIiIrBYLKSlpbFkyRIyMzMxm80Nttu4cSNDhw7FYrHg6elJv379qKmpYcGCBezevRs/P7/jjkEVEhERkXasurqapKQkAOLj48nNzSUrKwsfHx9KSkpITk5utO19992HxWJh+PDhFBQUsHbtWrKysqioqCA0NLRZcSghERERaQ0M6q7JyMjAYrEAtoQEwGw2ExcXB8D8+fMbbFde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L2IRERFxuJkzZxITE4OHhwf+/v6MGzeOnJycY7Z7+eWXiY6Oxs3NjeDgYG699VZ27tzZ7O0rIRERETGY1WRy+NQcqampJCQksGbNGrp27UptbS1paWmcffbZFBYWNtouKSmJv//972RlZdGjRw+qqqp47733OP/889mzZ0+zYlBCIiIi0o5VV1eTlJQEQHx8PLm5uWRlZeHj40NJSQnJyckNttu5cyfPPfccAA899BAbN25k+fLlmEwmNm7cyPTp05sVhxISERERw3Vogen4ZGRkYLFYAFtCAmA2m4mLiwNg/vz5DbZbuHAhBw8erNfu9NNPp3fv3k22a8xxD2rtxjPNWrG0EmN13Noql7FGRyAnopvRAUibtLuyukXWV1lZWW+5m5sbbm5u9Zbl5+fb54ODg+3zISEhAOTl5TW4jaba5eTkNNquMbrKRkRExCCurq6EhoZyZliKw9ft7e1NWFhYvWVPPPEEU6ZMqbfMarU22P7wclMj41FOtF1jlJCIiIgYxN3dnS1btlBTU+PwdVut1qOSgj9XRwDCw8Pt80VFRfb54uJigKOSmsba9erV67jaNUYJiYiIiIHc3d1xd3c3bPuxsbEEBARgsVhIS0vjhhtuoKCggPT0dABGjhwJQFRUFAD33HMP99xzDyNGjKBjx44cPHiQ2bNnM3ToUDIzM9m0aVO9dsdLg1pFRETaMVdXV6ZOnQrAnDlziIyMJDo6mqqqKgIDA0lMTAQgOzub7OxsSktLAQgNDeXhhx8G4MUXX+SUU05h6NChWK1W+vTpw6RJk5oVhxISERGRdm7ixInMmDGDgQMHUlhYiMlkYuzYsSxbtgyz2dxou2eeeYaXXnqJqKgotm7dipeXFzfffDNLlizBy8urWTGYrI2NShERERE5SVQhEREREcMpIRERERHDKSERERERwykhEREREcMpIRERERHDKSERERERwykhEREREcMpIRERERHDKSERERERwykhEREREcMpIRERERHDKSERERERw/0/usbjVRl/1r8AAAAASUVORK5CYII=\n",
"text/plain": [
"