diff --git a/unit3/unit3.ipynb b/unit3/unit3.ipynb
new file mode 100644
index 0000000..fa3be43
--- /dev/null
+++ b/unit3/unit3.ipynb
@@ -0,0 +1,732 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 0,
+ "metadata": {
+ "colab": {
+ "name": "Unit 3: Deep Q-Learning with Space Invaders.ipynb",
+ "provenance": [],
+ "private_outputs": true,
+ "collapsed_sections": [],
+ "authorship_tag": "ABX9TyPwiHKn+ccCskGi3ZMw9yH2",
+ "include_colab_link": true
+ },
+ "kernelspec": {
+ "name": "python3",
+ "display_name": "Python 3"
+ },
+ "language_info": {
+ "name": "python"
+ }
+ },
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "view-in-github",
+ "colab_type": "text"
+ },
+ "source": [
+ "![\"Open](\"https://colab.research.google.com/assets/colab-badge.svg\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "# Unit 3: Deep Q-Learning with Atari Games ๐พ using RL Baselines3 Zoo\n",
+ "\n",
+ "In this notebook, **you'll train a Deep Q-Learning agent** playing Space Invaders using [RL Baselines3 Zoo](https://github.com/DLR-RM/rl-baselines3-zoo), a training framework based on [Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/) that provides scripts for training, evaluating agents, tuning hyperparameters, plotting results and recording videos.\n",
+ "\n",
+ "โ If you have questions, please post them on #study-group-unit3 discord channel ๐ https://discord.gg/aYka4Yhff9\n",
+ "\n",
+ "๐ฎ Environments: \n",
+ "- SpacesInvadersNoFrameskip-v4\n",
+ "\n",
+ "๐ RL-Library: [Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/)\n",
+ " \n",
+ "โฌ๏ธ Here is an example of what **you will achieve** โฌ๏ธ"
+ ],
+ "metadata": {
+ "id": "k7xBVPzoXxOg"
+ }
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "J9S713biXntc"
+ },
+ "outputs": [],
+ "source": [
+ "%%html\n",
+ ""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Objectives of this notebook ๐\n",
+ "At the end of the notebook, you will:\n",
+ "- Be able to understand deeper **how RL Baselines3 Zoo works**.\n",
+ "- Be able to **push your trained agent and the code to the Hub** with a nice video replay and an evaluation score ๐ฅ.\n",
+ "\n",
+ "\n"
+ ],
+ "metadata": {
+ "id": "wciHGjrFYz9m"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## This notebook is from Deep Reinforcement Learning Class\n",
+ "\n",
+ "\n",
+ "\n",
+ ""
+ ],
+ "metadata": {
+ "id": "7Hac0z2QZdOm"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "In this free course, you will:\n",
+ "\n",
+ "- ๐ Study Deep Reinforcement Learning in **theory and practice**.\n",
+ "- ๐งโ๐ป Learn to **use famous Deep RL libraries** such as Stable Baselines3, RL Baselines3 Zoo, and RLlib.\n",
+ "- ๐ค Train **agents in unique environments** \n",
+ "\n",
+ "And more check ๐ the syllabus ๐ https://github.com/huggingface/deep-rl-class\n",
+ "\n",
+ "The best way to keep in touch is to join our discord server to exchange with the community and with us ๐๐ป https://discord.gg/aYka4Yhff9"
+ ],
+ "metadata": {
+ "id": "nw6fJHIAZd-J"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Prerequisites ๐๏ธ\n",
+ "Before diving into the notebook, you need to:\n",
+ "\n",
+ "๐ฒ ๐ [Read the Unit 3 Readme](https://github.com/huggingface/deep-rl-class/blob/main/unit3/README.md) that contains all the information.\n",
+ "\n",
+ "๐ฒ ๐ [Read **Deep Q-Learning**](https://huggingface.co/blog/deep-rl-dqn) \n",
+ "\n",
+ "๐ฒ ๐ข Sign up to [our Discord Server](https://discord.gg/aYka4Yhff9) if it's not already done and **introduce yourself to #introduce-yourself channel ๐ฅณ**\n",
+ "\n",
+ "๐ฒ ๐ Are you new to Discord? Check our **discord 101 to get the best practices** ๐ https://github.com/huggingface/deep-rl-class/blob/main/DISCORD.Md\n"
+ ],
+ "metadata": {
+ "id": "0vgANIBBZg1p"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "# Let's train a Deep Q-Learning agent playing Atari' Space Invaders ๐พ and upload it to the Hub."
+ ],
+ "metadata": {
+ "id": "QR0jZtYreSI5"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Step 0: Set the GPU ๐ช\n",
+ "- To **faster the agent's training, we'll use a GPU** to do that go to `Runtime > Change Runtime type`\n",
+ "\n"
+ ],
+ "metadata": {
+ "id": "ESJV9guAee3P"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "- `Hardware Accelerator > GPU`"
+ ],
+ "metadata": {
+ "id": "Zg8eWiQ1efcU"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ ""
+ ],
+ "metadata": {
+ "id": "eoey4CFpejM5"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Step 0+: Setup a Virtual Display ๐ป\n",
+ "\n",
+ "During the notebook, we'll need to generate a replay video. To do so, with colab, **we need to have a virtual screen to be able to render the environment** (and thus record the frames). \n",
+ "\n",
+ "Hence the following cell will install virtual screen libraries and create and run a virtual screen ๐ฅ"
+ ],
+ "metadata": {
+ "id": "P6XBkQ5qelOV"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "%%capture\n",
+ "!pip install pyglet==1.5.1 \n",
+ "!apt install python-opengl\n",
+ "!apt install ffmpeg\n",
+ "!apt install xvfb\n",
+ "!pip3 install pyvirtualdisplay\n",
+ "\n",
+ "# Additional dependencies for RL Baselines3 Zoo\n",
+ "!apt-get install swig cmake freeglut3-dev \n",
+ "\n",
+ "# Virtual display\n",
+ "from pyvirtualdisplay import Display\n",
+ "\n",
+ "virtual_display = Display(visible=0, size=(1400, 900))\n",
+ "virtual_display.start()"
+ ],
+ "metadata": {
+ "id": "jV6wjQ7Be7p5"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Step 1: Clone RL-Baselines3 Zoo Repo ๐"
+ ],
+ "metadata": {
+ "id": "mYIMvl5X9NAu"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "!git clone https://github.com/DLR-RM/rl-baselines3-zoo"
+ ],
+ "metadata": {
+ "id": "eu5ZDPZ09VNQ"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Step 2: Install dependencies ๐ฝ\n",
+ "The first step is to install the dependencies RL-Baselines3 Zoo needs (this can take 5min โฒ)\n",
+ "\n",
+ "But we'll also install:\n",
+ "- `huggingface_sb3`: Additional code for Stable-baselines3 to load and upload models from the Hugging Face ๐ค Hub."
+ ],
+ "metadata": {
+ "id": "HCIoSbvbfAQh"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "%cd /content/rl-baselines3-zoo/"
+ ],
+ "metadata": {
+ "id": "s2QsFAk29h-D"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "!pip install -r requirements.txt"
+ ],
+ "metadata": {
+ "id": "3QaOS7Xj9j1s"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "%%capture\n",
+ "!pip install huggingface_sb3"
+ ],
+ "metadata": {
+ "id": "RLRGKFR39l9s"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Step 3: Train our Deep Q-Learning Agent to Play Space Invaders ๐พ\n",
+ "\n",
+ "To train an agent with RL-Baselines3-Zoo, we just need to do two things:\n",
+ "1. We define the hyperparameters in `rl-baselines3-zoo/hyperparams/dqn.yml`\n",
+ "\n"
+ ],
+ "metadata": {
+ "id": "5iPgzluo9z-u"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ ""
+ ],
+ "metadata": {
+ "id": "oInM0jLkDPfL"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "Here we see that:\n",
+ "- We use the Atari Wrapper that preprocess the input (Frame reduction ,grayscale, stack 4 frames)\n",
+ "- We use `CnnPolicy`, since we use Convolutional layers to process the frames\n",
+ "- We train it for 1 million `n_timesteps` \n",
+ "- Memory (Experience Replay) size is 100000"
+ ],
+ "metadata": {
+ "id": "_VjblFSVDQOj"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "You can check the documentation to understand what each hyperparameters does: https://stable-baselines3.readthedocs.io/en/master/modules/dqn.html?highlight=deep%20q%20learning#parameters"
+ ],
+ "metadata": {
+ "id": "5qTkbWrkECOJ"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "2. We run `train.py` and save the models on `logs` folder ๐"
+ ],
+ "metadata": {
+ "id": "Hn8bRTHvERRL"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "!python train.py --algo ________ --env SpaceInvadersNoFrameskip-v4 -f _________"
+ ],
+ "metadata": {
+ "id": "Xr1TVW4xfbz3"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "#### Solution"
+ ],
+ "metadata": {
+ "id": "SeChoX-3SZfP"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "!python train.py --algo dqn --env SpaceInvadersNoFrameskip-v4 -f logs/"
+ ],
+ "metadata": {
+ "id": "PuocgdokSab9"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Step 4: Let's evaluate our agent ๐\n",
+ "- RL-Baselines3-Zoo provides `enjoy.py` to evaluate our agent.\n",
+ "- Let's evaluate it for 5000 timesteps ๐ฅ"
+ ],
+ "metadata": {
+ "id": "_dLomIiMKQaf"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "!python enjoy.py --algo dqn --env SpaceInvadersNoFrameskip-v4 --no-render --n-timesteps _________ --folder logs/"
+ ],
+ "metadata": {
+ "id": "co5um_KeKbBJ"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "#### Solution"
+ ],
+ "metadata": {
+ "id": "Q24K1tyWSj7t"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "!python enjoy.py --algo dqn --env SpaceInvadersNoFrameskip-v4 --no-render --n-timesteps 5000 --folder logs/"
+ ],
+ "metadata": {
+ "id": "P_uSmwGRSk0z"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Step 5: Publish our trained model on the Hub ๐\n",
+ "Now that we saw we got good results after the training, we can publish our trained model on the hub ๐ค with one line of code.\n"
+ ],
+ "metadata": {
+ "id": "liBeTltiHJtr"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ ""
+ ],
+ "metadata": {
+ "id": "O6L41QiMHYM2"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "By using `utils.push_to_hub.py` **you evaluate, record a replay, generate a model card of your agent and push it to the hub**.\n",
+ "\n",
+ "This way:\n",
+ "- You can **showcase our work** ๐ฅ\n",
+ "- You can **visualize your agent playing** ๐\n",
+ "- You can **share with the community an agent that others can use** ๐พ\n",
+ "- You can **access a leaderboard ๐ to see how well your agent is performing compared to your classmates** ๐ https://huggingface.co/spaces/chrisjay/Deep-Reinforcement-Learning-Leaderboard"
+ ],
+ "metadata": {
+ "id": "ezbHS1q3HYVV"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "To be able to share your model with the community there are three more steps to follow:\n",
+ "\n",
+ "1๏ธโฃ (If it's not already done) create an account to HF โก https://huggingface.co/join\n",
+ "\n",
+ "2๏ธโฃ Sign in and then, you need to store your authentication token from the Hugging Face website.\n",
+ "- Create a new token (https://huggingface.co/settings/tokens) **with write role**"
+ ],
+ "metadata": {
+ "id": "XMSeZRBiHk6X"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ ""
+ ],
+ "metadata": {
+ "id": "9ToyuaYwHmxG"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "- Copy the token \n",
+ "- Run the cell below and past the token"
+ ],
+ "metadata": {
+ "id": "9O6FI0F8HnzE"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "from huggingface_hub import notebook_login # To log to our Hugging Face account to be able to upload models to the Hub.\n",
+ "notebook_login()\n",
+ "!git config --global credential.helper store"
+ ],
+ "metadata": {
+ "id": "Ppu9yePwHrZX"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "If you don't want to use a Google Colab or a Jupyter Notebook, you need to use this command instead: `huggingface-cli login`"
+ ],
+ "metadata": {
+ "id": "2RVEdunPHs8B"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "3๏ธโฃ We're now ready to push our trained agent to the ๐ค Hub ๐ฅ"
+ ],
+ "metadata": {
+ "id": "dSLwdmvhHvjw"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "Let's run push_to_hub.py file to upload our trained agent to the Hub.\n",
+ "\n",
+ "`--repo-name `: The name of the repo\n",
+ "\n",
+ "`-orga`: Your Hugging Face username"
+ ],
+ "metadata": {
+ "id": "PW436XnhHw1H"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ ""
+ ],
+ "metadata": {
+ "id": "9YO_qZTWeRHl"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "!python -m utils.push_to_hub --algo dqn --env SpaceInvadersNoFrameskip-v4 --repo-name _____________________ -orga _____________________ -f logs/"
+ ],
+ "metadata": {
+ "id": "Ygk2sEktTDEw"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "#### Solution"
+ ],
+ "metadata": {
+ "id": "otgpa0rhS9wR"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "!python -m utils.push_to_hub --algo dqn --env SpaceInvadersNoFrameskip-v4 --repo-name dqn-SpaceInvadersNoFrameskip-v4 -orga ThomasSimonini -f logs/"
+ ],
+ "metadata": {
+ "id": "_HQNlAXuEhci"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "###."
+ ],
+ "metadata": {
+ "id": "0D4F5zsTTJ-L"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "Congrats ๐ฅณ you've just trained and uploaded your first Deep Q-Learning agent using RL-Baselines-3 Zoo. The script above should have displayed a link to a model repository such as https://huggingface.co/ThomasSimonini/dqn-SpaceInvadersNoFrameskip-v4. When you go to this link, you can:\n",
+ "* see a video preview of your agent at the right. \n",
+ "* click \"Files and versions\" to see all the files in the repository.\n",
+ "* click \"Use in stable-baselines3\" to get a code snippet that shows how to load the model.\n",
+ "* a model card (`README.md` file) which gives a description of the model and the hyperparameters you used.\n",
+ "\n",
+ "Under the hood, the Hub uses git-based repositories (don't worry if you don't know what git is), which means you can update the model with new versions as you experiment and improve your agent.\n",
+ "\n",
+ "Compare the results of your LunarLander-v2 with your classmates using the leaderboard ๐ ๐ https://huggingface.co/spaces/chrisjay/Deep-Reinforcement-Learning-Leaderboard"
+ ],
+ "metadata": {
+ "id": "ff89kd2HL1_s"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Step 6: Load a powerful trained model ๐ฅ\n",
+ "- The Stable-Baselines3 team uploaded **more than 150 trained Deep Reinforcement Learning agents on the Hub**.\n",
+ "\n",
+ "You can find them here: ๐ https://huggingface.co/sb3\n",
+ "\n",
+ "Some examples:\n",
+ "- Asteroids: https://huggingface.co/sb3/dqn-AsteroidsNoFrameskip-v4\n",
+ "- Beam Rider: https://huggingface.co/sb3/dqn-BeamRiderNoFrameskip-v4\n",
+ "- Breakout: https://huggingface.co/sb3/dqn-BreakoutNoFrameskip-v4\n",
+ "- Road Runner: https://huggingface.co/sb3/dqn-RoadRunnerNoFrameskip-v4\n",
+ "\n",
+ "Let's load an agent playing Beam Rider: https://huggingface.co/sb3/dqn-BeamRiderNoFrameskip-v4"
+ ],
+ "metadata": {
+ "id": "fyRKcCYY-dIo"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "%%html\n",
+ ""
+ ],
+ "metadata": {
+ "id": "B-9QVFIROI5Y"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "1. We download the model using `utils.load_from_hub`, and place it in a new folder that we can call `rl_trained`"
+ ],
+ "metadata": {
+ "id": "7ZQNY_r6NJtC"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "# Download model and save it into the logs/ folder\n",
+ "!python -m utils.load_from_hub --algo dqn --env BeamRiderNoFrameskip-v4 -orga sb3 -f rl_trained/"
+ ],
+ "metadata": {
+ "id": "OdBNZHy0NGTR"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "2. Let's evaluate if for 5000 timesteps"
+ ],
+ "metadata": {
+ "id": "LFt6hmWsNdBo"
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "!python enjoy.py --algo dqn --env BeamRiderNoFrameskip-v4 -n 5000 -f rl_trained/"
+ ],
+ "metadata": {
+ "id": "aOxs0rNuN0uS"
+ },
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "Why not trying to train your own **Deep Q-Learning Agent playing BeamRiderNoFrameskip-v4? ๐.**\n",
+ "\n",
+ "If you want to try, check https://huggingface.co/sb3/dqn-BeamRiderNoFrameskip-v4#hyperparameters **in the model card, you have the hyperparameters of the trained agent.**"
+ ],
+ "metadata": {
+ "id": "kxMDuDfPON57"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "We'll see in the next Unit, how we can **use Optuna for optimizing the Hyperparameters ๐ฅ.**\n"
+ ],
+ "metadata": {
+ "id": "xL_ZtUgpOuY6"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Some additional challenges ๐\n",
+ "The best way to learn **is to try things by your own**!\n",
+ "\n",
+ "In the [Leaderboard](https://huggingface.co/spaces/chrisjay/Deep-Reinforcement-Learning-Leaderboard) you will find your agents. Can you get to the top?\n",
+ "\n",
+ "Here's a list of environments you can try to train your agent with:\n",
+ "- BeamRiderNoFrameskip-v4\n",
+ "- BreakoutNoFrameskip-v4 \n",
+ "- EnduroNoFrameskip-v4\n",
+ "- PongNoFrameskip-v4\n",
+ "\n",
+ "\n"
+ ],
+ "metadata": {
+ "id": "-pqaco8W-huW"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ ""
+ ],
+ "metadata": {
+ "id": "JNeyXYt-PtCQ"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "________________________________________________________________________\n",
+ "Congrats on finishing this chapter!\n",
+ "\n",
+ "If youโre still feel confused with all these elements...it's totally normal! **This was the same for me and for all people who studied RL.**\n",
+ "\n",
+ "Take time to really **grasp the material before continuing and try the additional challenges**. Itโs important to master these elements and having a solid foundations.\n",
+ "\n"
+ ],
+ "metadata": {
+ "id": "paS-XKo4-kmu"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "\n",
+ "\n",
+ "### This is a course built with you ๐ท๐ฟโโ๏ธ\n",
+ "\n",
+ "Finally, we want to improve and update the course iteratively with your feedback. If you have some, please fill this form ๐ https://forms.gle/3HgA7bEHwAmmLfwh9\n"
+ ],
+ "metadata": {
+ "id": "5WRx7tO7-mvC"
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "### Keep Learning, Stay Awesome ๐ค"
+ ],
+ "metadata": {
+ "id": "fS3Xerx0fIMV"
+ }
+ }
+ ]
+}
\ No newline at end of file