From 2b09551997efc42a40537529343d51a00477b860 Mon Sep 17 00:00:00 2001
From: Antoine Lebtahi <antoine.lebtahi@ecl19.ec-lyon.fr>
Date: Wed, 15 Feb 2023 20:56:50 +0100
Subject: [PATCH] Final commit

---
 README.md                  | 160 ++++++-------------------------------
 a2c_sb3_cartpole.py        |  48 +++++++++++
 a2c_sb3_panda_reach.py     |  48 +++++++++++
 plots/reinforce_reward.png | Bin 0 -> 46520 bytes
 reinforce_cartpole.py      | 134 +++++++++++++++++++++++++++++++
 requirements.txt           | Bin 0 -> 278 bytes
 6 files changed, 253 insertions(+), 137 deletions(-)
 create mode 100644 a2c_sb3_cartpole.py
 create mode 100644 a2c_sb3_panda_reach.py
 create mode 100644 plots/reinforce_reward.png
 create mode 100644 reinforce_cartpole.py
 create mode 100644 requirements.txt

diff --git a/README.md b/README.md
index 3f71fbb..263a740 100644
--- a/README.md
+++ b/README.md
@@ -1,171 +1,57 @@
 # Hands-On Reinforcement Learning
 
-In this hands-on project, we will first implement a simple RL algorithm and apply it to solve the CartPole-v1 environment. Once we become familiar with the basic workflow, we will learn to use various tools for machine learning model training, monitoring, and sharing, by applying these tools to train a robotic arm.
+In this hands-on project, we will first implement a simple RL algorithm and apply it to solve the CartPole-v1 
+environment. Once we become familiar with the basic workflow, we will learn to use various tools for machine learning 
+model training, monitoring, and sharing, by applying these tools to train a robotic arm.
 
-## To be handed in
-
-This work must be done individually. The expected output is a repository named `hands-on-rl` on https://gitlab.ec-lyon.fr. It must contain a `README.md` file that explains **briefly** the successive steps of the project. Throughout the subject, you will find a ๐Ÿ›  symbol indicating that a specific production is expected.
-The last commit is due before 11:59 pm on Monday, February 13, 2023. Subsequent commits will not be considered.
-
-> โš ๏ธ **Warning**
-> Ensure that you only commit the files that are requested. For example, your directory should not contain the generated `.zip` files, nor the `runs` folder... At the end, your repository must contain one `README.md`, three python scripts, and optionally image files for the plots.
-
-## Before you start
-
-Make sure you know the basics of Reinforcement Learning. In case of need, you can refer to the [introduction of the Hugging Face RL course](https://huggingface.co/blog/deep-rl-intro).
-
-## Introduction to Gym
-
-Gym is a framework for developing and evaluating reinforcement learning environments. It offers various environments, including classic control and toy text scenarios, to test RL algorithms.
-
-### Installation
-
-```sh
-pip install gym==0.21
-```
-
-Install also pyglet for the rendering.
-
-```sh
-pip install pyglet==1.5.27
-```
-
-### Usage
-
-Here is an example of how to use Gym to solve the `CartPole-v1` environment:
-
-```python
-import gym
-
-# Create the environment
-env = gym.make("CartPole-v1")
-
-# Reset the environment and get the initial observation
-observation = env.reset()
-
-for _ in range(100):
-    # Select a random action from the action space
-    action = env.action_space.sample()
-    # Apply the action to the environment 
-    # Returns next observation, reward, done signal (indicating
-    # if the episode has ended), and an additional info dictionary
-    observation, reward, done, info = env.step(action)
-    # Render the environment to visualize the agent's behavior
-    env.render() 
-```
 
 ## REINFORCE
 
-The REINFORCE algorithm (also known as Vanilla Policy Gradient) is a policy gradient method that optimizes the policy directly using gradient descent. The following is the pseudocode of the REINFORCE algorithm:
-
-```txt
-Setup the CartPole environment
-Setup the agent as a simple neural network with:
-    - One fully connected layer with 128 units and ReLU activation followed by a dropout layer
-    - One fully connected layer followed by softmax activation
-Repeat 500 times:
-    Reset the environment
-    Reset the buffer
-    Repeat until the end of the episode:
-        Compute action probabilities 
-        Sample the action based on the probabilities and store its probability in the buffer 
-        Step the environment with the action
-        Compute and store in the buffer the return using gamma=0.99 
-    Normalize the return
-    Compute the policy loss as -sum(log(prob) * return)
-    Update the policy using an Adam optimizer and a learning rate of 5e-3
-```
-
-To learn more about REINFORCE, you can refer to [this unit](https://huggingface.co/blog/deep-rl-pg).
-
-> ๐Ÿ›  **To be handed in**
-> Use PyTorch to implement REINFORCE and solve the CartPole environement. Share the code in `reinforce_cartpole.py`, and share a plot showing the total reward accross episodes in the `README.md`.
+Here we implement a Reinforce algorithm using PyTorch (code here : [reinforce_cartpole.py](/reinforce_cartpole.py) ).
+Here is the plot showing the total reward accross episodes : 
 
-## Familiarization with a complete RL pipeline: Application to training a robotic arm
-
-In this section, you will use the Stable-Baselines3 package to train a robotic arm using RL. You'll get familiar with several widely-used tools for training, monitoring and sharing machine learning models.
-
-### Get familiar with Stable-Baselines3
-
-Stable-Baselines3 (SB3) is a high-level RL library that provides various algorithms and integrated tools to easily train and test reinforcement learning models.
-
-#### Installation
-
-```sh
-pip install stable-baselines3
-```
-
-#### Usage
-
-Use the [Stable-Baselines3 documentation](https://stable-baselines3.readthedocs.io/en/master/) to implement the code to solve the CartPole environment with the Advantage Actor-Critic (A2C) algorithm.
+![rewards by episodes](/plots/reinforce_reward.png)
 
 
-> ๐Ÿ›  **To be handed in**
-> Store the code in `a2c_sb3_cartpole.py`. Unless otherwise stated, you'll work upon this file for the next sections.
 
-### Get familiar with Hugging Face Hub
-
-Hugging Face Hub is a platform for easy sharing and versioning of trained machine learning models. With Hugging Face Hub, you can quickly and easily share your models with others and make them usable through the API. For example, see the trained A2C agent for CartPole: https://huggingface.co/sb3/a2c-CartPole-v1. Hugging Face Hub provides an API to download and upload SB3 models.
-
-#### Installation of `huggingface_sb3`
-
-```sh
-pip install huggingface_sb3
-```
-
-#### Upload the model on the Hub
+## Familiarization with a complete RL pipeline: Application to training a robotic arm
 
-Follow the [Hugging Face Hub documentation](https://huggingface.co/docs/hub/index) to upload the previously learned model to the Hub.
+In this section, we will use the Stable-Baselines3 package to train a robotic arm using RL. 
 
-> ๐Ÿ›  **To be handed in**
-> Link the trained model in the `README.md` file.
+Thus we use the 
+[Stable-Baselines3 documentation](https://stable-baselines3.readthedocs.io/en/master/) 
+to implement the python script [a2c_sb3_cartpole.py](/a2c_sb3_cartpole.py) to solve the CartPole 
+environment with the Advantage Actor-Critic (A2C) algorithm.
 
-> ๐Ÿ“ **Note**
->  [RL-Zoo3](https://stable-baselines3.readthedocs.io/en/master/guide/rl_zoo.html) provides more advanced features to save hyperparameters, generate renderings and metrics. Feel free to try them.
 
-### Get familiar with Weights & Biases
 
-Weights & Biases (W&B) is a tool for machine learning experiment management. With W&B, you can track and compare your experiments, visualize your model training and performance.
 
-#### Installation
+### Weights & Biases repository
 
-You'll need to install both `wand` and `tensorboar`.
+Here is the [link](https://wandb.ai/antoine-lebtahi/cartpole-sb3_a2c) of the Weights & Biases project where the training run can be found.
 
-```shell
-pip install wandb tensorboard
-```
 
-Use the documentation of Stable-Baselines3 and [Weights & Biases](https://docs.wandb.ai) to track the CartPole training. Make the run public.
+### Hugging Face Hub repository
 
-๐Ÿ›  Share the link of the wandb run in the `README.md` file.
+Trained model can also be found in this Hugging face repository : [link](https://huggingface.co/alebtahi/a2c_sb3)
 
-> โš ๏ธ **Warning**
-> Make sure to make the run public!
 
 ### Full workflow with panda-gym
 
-Panda-gym is a collection of environments for robotic simulation and control. It provides a range of challenges for training robotic agents in a simulated environment. In this section, you will get familiar with one of the environments provided by panda-gym, the `PandaReachJointsDense-v2`. The objective is to learn how to reach any point in 3D space by directly controlling the robot's articulations.
-
-#### Installation
-
-```shell
-pip install panda_gym==2.0.0
-```
-
-#### Train, track, and share
+In this section, we will get familiar with one of the environments provided by panda-gym, the 
+`PandaReachJointsDense-v2`. The objective is to learn how to reach any point in 3D space by directly controlling 
+the robot's articulations.
 
-Use the Stable-Baselines3 package to train A2C model on the `PandaReachJointsDense-v2` environment. 500k timesteps should be enough. Track the environment with Weights & Biases. Once the training is over, upload the trained model on the Hub.
+Resulting code is : [a2c_sb3_panda_reach.py](/a2c_sb3_panda_reach.py).
 
-> ๐Ÿ›  **To be handed in**
-> Share all the code in `a2c_sb3_panda_reach.py`. Share the link of the wandb run and the trained model in the `README.md` file.
+Run is stored in this Weight and Biases project : [panda_reach-sb3_a2c](https://wandb.ai/antoine-lebtahi/panda_reach-sb3_a2c)
 
-## Contribute
+Model can be found in the same Hugging Face project thant previously : [link](https://huggingface.co/alebtahi/a2c_sb3)
 
-This tutorial may contain errors, inaccuracies, typos or areas for improvement. Feel free to contribute to its improvement by opening an issue.
 
 ## Author
 
-Quentin Gallouรฉdec
+Antoine Lebtahi
 
 ## License
 
diff --git a/a2c_sb3_cartpole.py b/a2c_sb3_cartpole.py
new file mode 100644
index 0000000..5b506e3
--- /dev/null
+++ b/a2c_sb3_cartpole.py
@@ -0,0 +1,48 @@
+import gym
+import wandb
+
+from stable_baselines3 import A2C
+from stable_baselines3.common.monitor import Monitor
+from stable_baselines3.common.vec_env import DummyVecEnv
+from wandb.integration.sb3 import WandbCallback
+
+
+# Environment configuration :
+config = {
+    "policy_type": "MlpPolicy",
+    "total_timesteps": 25000,
+    "env_name": "CartPole-v1"}
+
+# WandB config :
+run = wandb.init(
+    project="cartpole-sb3_a2c",
+    config=config,
+    sync_tensorboard=True,
+    monitor_gym=True,
+    save_code=True,
+)
+
+
+# Environment definition :
+def make_env():
+    environment = gym.make(config["env_name"])
+    environment = Monitor(environment)  # record stats such as returns
+    return environment
+
+
+env = DummyVecEnv([make_env])
+
+# Model definition :
+model = A2C(config["policy_type"], env, verbose=1, tensorboard_log=f"./runs/{run.id}")
+
+# Model training :
+
+model.learn(
+    total_timesteps=config["total_timesteps"],
+    callback=WandbCallback(
+        gradient_save_freq=100,
+        model_save_path=f"./models/{run.id}",
+        verbose=2,
+    )
+)
+run.finish()
diff --git a/a2c_sb3_panda_reach.py b/a2c_sb3_panda_reach.py
new file mode 100644
index 0000000..58da3ee
--- /dev/null
+++ b/a2c_sb3_panda_reach.py
@@ -0,0 +1,48 @@
+import gym
+import panda_gym
+import wandb
+
+from stable_baselines3 import A2C
+from stable_baselines3.common.monitor import Monitor
+from stable_baselines3.common.vec_env import DummyVecEnv
+from wandb.integration.sb3 import WandbCallback
+
+
+# Environment configuration :
+config = {
+    "policy_type": "MultiInputPolicy",
+    "total_timesteps": 500000,
+    "env_name": "PandaReachJointsDense-v2"}
+
+# WandB config :
+run = wandb.init(
+
+    project="panda_reach-sb3_a2c",
+    config=config,
+    sync_tensorboard=True,
+    monitor_gym=True,
+    save_code=True,
+)
+
+
+# Environment definition :
+def make_env():
+    environment = gym.make(config["env_name"])
+    environment = Monitor(environment)  # record stats such as returns
+    return environment
+
+env = DummyVecEnv([make_env])
+
+# Model definition :
+model = A2C(config["policy_type"], env, verbose=1, tensorboard_log=f"./runsPanda/{run.id}")
+
+# Model training :
+model.learn(
+    total_timesteps=config["total_timesteps"],
+    callback=WandbCallback(
+        gradient_save_freq=1000,
+        model_save_path=f"./modelsPanda/{run.id}",
+        verbose=2,
+    )
+)
+run.finish
diff --git a/plots/reinforce_reward.png b/plots/reinforce_reward.png
new file mode 100644
index 0000000000000000000000000000000000000000..2e17450bc435b93011783e778a9c84040173451c
GIT binary patch
literal 46520
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
HoD!M<GxaRp

literal 0
HcmV?d00001

diff --git a/reinforce_cartpole.py b/reinforce_cartpole.py
new file mode 100644
index 0000000..e216ea1
--- /dev/null
+++ b/reinforce_cartpole.py
@@ -0,0 +1,134 @@
+import gym
+import matplotlib.pyplot as plt
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import torch.optim as optim
+
+from torch.distributions import Categorical
+from collections import deque
+
+
+class Policy(nn.Module):
+    def __init__(self, s_size, a_size, h_size):
+        super(Policy, self).__init__()
+        self.fc1 = nn.Linear(s_size, h_size)
+        self.fc2 = nn.Linear(h_size, a_size)
+        self.drop = nn.Dropout(0.3)
+
+    def forward(self, x):
+        x = F.relu(self.fc1(x))
+        x = self.drop(x)
+        x = self.fc2(x)
+        return F.softmax(x, dim=1)
+
+    def act(self, state):
+        device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
+        state = torch.from_numpy(state).float().unsqueeze(0).to(device)
+        probs = self.forward(state).cpu()
+        m = Categorical(probs)
+        action = m.sample()
+        return action.item(), m.log_prob(action)
+
+
+def reinforce(env, policy, optimizer, n_training_episodes, max_t, gamma, print_every):
+    # Help us to calculate the score during the training
+    scores_deque = deque(maxlen=100)
+    scores = []
+
+    for i_episode in range(1, n_training_episodes + 1):
+        saved_log_probs = []
+        # reset the environment
+        state = env.reset()
+        # reset the buffer
+        rewards = []
+
+        # repeat until the end of the episode of len = max_t
+        for t in range(max_t):
+            # compute action probabilities and sample action
+            action, log_prob = policy.act(state)
+            saved_log_probs.append(log_prob)
+            # Step the environment with the action
+            state, reward, done, _ = env.step(action)
+            # Store rewards in our buffers
+            rewards.append(reward)
+            if done:
+                break
+
+        # compute sum of the rewards
+        scores_deque.append(sum(rewards))
+        scores.append(sum(rewards))
+
+        # calculate the return
+        returns = deque(maxlen=max_t)
+        n_steps = len(rewards)
+
+        for t in range(n_steps)[::-1]:
+            disc_return_t = (returns[0] if len(returns) > 0 else 0)
+            returns.appendleft(gamma * disc_return_t + rewards[t])
+
+            # standardization of the returns is employed to make training more stable
+        eps = np.finfo(np.float32).eps.item()
+        # eps is the smallest representable float, which is
+        # added to the standard deviation of the returns to avoid numerical instabilities
+        returns = torch.tensor(returns)
+        returns = (returns - returns.mean()) / (returns.std() + eps)
+
+        # Compute the policy loss as -sum(log(prob) * return)
+        policy_loss = []
+        for log_prob, disc_return in zip(saved_log_probs, returns):
+            policy_loss.append(-log_prob * disc_return)
+        policy_loss = torch.cat(policy_loss).sum()
+
+        # Update the policy using an Adam optimizer:
+        optimizer.zero_grad()
+        policy_loss.backward()
+        optimizer.step()
+
+        if i_episode % print_every == 0:
+            print('Episode {}\tAverage Score: {:.2f}'.format(i_episode, np.mean(scores_deque)))
+
+    return scores
+
+
+if __name__ == "__main__":
+    device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
+
+    env = gym.make("CartPole-v1")
+    state_size = env.observation_space.shape[0]
+    action_size = env.action_space.n
+
+    cartpole_hyperparameters = {"h_size": 128,
+                                "n_training_episodes": 500,
+                                "n_evaluation_episodes": 10,
+                                "max_t": 1000,
+                                "gamma": 0.99,
+                                "lr": 5e-3,
+                                "state_space": state_size,
+                                "action_space": action_size,
+                                }
+
+    cartpole_policy = Policy(cartpole_hyperparameters["state_space"],
+                             cartpole_hyperparameters["action_space"],
+                             cartpole_hyperparameters["h_size"]
+                             ).to(device)
+
+    cartpole_optimizer = optim.Adam(cartpole_policy.parameters(),
+                                    lr=cartpole_hyperparameters["lr"]
+                                    )
+
+    scores = reinforce(env,
+                       cartpole_policy,
+                       cartpole_optimizer,
+                       cartpole_hyperparameters["n_training_episodes"],
+                       cartpole_hyperparameters["max_t"],
+                       cartpole_hyperparameters["gamma"],
+                       print_every=100
+                       )
+
+    plt.plot(scores)
+    plt.xlabel("Episodes")
+    plt.ylabel("Total Reward")
+    plt.savefig("./plots/reinforce_reward.png")
+    plt.show()
\ No newline at end of file
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000000000000000000000000000000000000..802d572ffa91f14bfc3c9f081b451d2c909389b4
GIT binary patch
literal 278
zcmezWFP)*1A(z3H!Ir^*L65<R!H|KMfr|kms>_hakk3%UkjaqDkjhXDR|QgO0alm6
zP|A?bkj{|FkjIeDkj9V*RvFJw%#g%j3|5iLkjPNNP{5D_HYtZ8lOYK#p2twikjqfO
zPzg5G5Nx*zm;~8hz>vt0$B@F1$e;^#3&@2=40>Q!8h}kGW+-7uWJqGjVMt}rWk_O3
zWGH4xWdPZb2X-yQ{t||Kh9ZV!h77Qta;UjU3<_X=2}3GF9z!u$O%g*sLn1>FLka@`
DRlzNX

literal 0
HcmV?d00001

-- 
GitLab