From d17f29c8ade6579381cbd83c63c1ba04d0f58643 Mon Sep 17 00:00:00 2001 From: Antonin RAFFIN Date: Thu, 7 May 2020 10:10:51 +0200 Subject: [PATCH] Add base doc --- README.md | 27 ++- docs/README.md | 2 +- docs/_static/img/mistake.png | Bin 0 -> 148639 bytes docs/common/distributions.rst | 26 +++ docs/common/env_checker.rst | 7 + docs/common/evaluation.rst | 7 + docs/conf.py | 4 +- docs/guide/callbacks.rst | 296 ++++++++++++++++++++++++++++++ docs/guide/checking_nan.rst | 164 +++++++++++++++++ docs/guide/custom_env.rst | 82 +++++++++ docs/guide/install.rst | 152 +++++++++++++++ docs/guide/migration.rst | 12 ++ docs/guide/quickstart.rst | 21 ++- docs/guide/rl.rst | 17 ++ docs/guide/rl_tips.rst | 251 +++++++++++++++++++++++++ docs/guide/vec_envs.rst | 33 +++- docs/index.rst | 34 +++- docs/misc/changelog.rst | 1 + docs/misc/projects.rst | 26 +++ docs/modules/a2c.rst | 6 +- docs/modules/base.rst | 9 + docs/modules/ppo.rst | 36 ++-- docs/modules/sac.rst | 17 +- docs/modules/td3.rst | 10 +- setup.py | 4 +- stable_baselines3/a2c/__init__.py | 2 +- stable_baselines3/ppo/__init__.py | 2 +- stable_baselines3/sac/__init__.py | 2 +- stable_baselines3/td3/__init__.py | 2 +- 29 files changed, 1194 insertions(+), 58 deletions(-) create mode 100644 docs/_static/img/mistake.png create mode 100644 docs/common/distributions.rst create mode 100644 docs/common/env_checker.rst create mode 100644 docs/common/evaluation.rst create mode 100644 docs/guide/callbacks.rst create mode 100644 docs/guide/checking_nan.rst create mode 100644 docs/guide/custom_env.rst create mode 100644 docs/guide/install.rst create mode 100644 docs/guide/migration.rst create mode 100644 docs/guide/rl.rst create mode 100644 docs/guide/rl_tips.rst create mode 100644 docs/misc/projects.rst diff --git a/README.md b/README.md index 644edbc..d8ee719 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,29 @@ These algorithms will make it easier for the research community and industry to +### Roadmap to V1.0 + +Please look at the issue for more details. +Planned features: + +- [ ] DQN (almost ready, currently in testing phase) +- [ ] DDPG (you can use its successor TD3 for now) +- [ ] HER +- [ ] Support for MultiDiscrete and MultiBinary action spaces + +### Planned features (v1.1+) + +- [ ] Full Tensorboard support +- [ ] DQN extensions (prioritized replay, double q-learning, ...) +- [ ] Support for `Tuple` and `Dict` observation spaces +- [ ] Recurrent Policies +- [ ] TRPO + + +## Migration guide + +**TODO: migration guide from Stable-Baselines in the documentation** + ## Documentation Documentation is available online: [https://stable-baselines.readthedocs.io/](https://stable-baselines.readthedocs.io/) @@ -102,8 +125,10 @@ model.learn(total_timesteps=10000) obs = env.reset() for i in range(1000): action, _states = model.predict(obs, deterministic=True) - obs, rewards, dones, info = env.step(action) + obs, reward, done, info = env.step(action) env.render() + if done: + obs = env.reset() env.close() ``` diff --git a/docs/README.md b/docs/README.md index ffb3753..1427a79 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -## Stable Baselines Documentation +## Stable Baselines3 Documentation This folder contains documentation for the RL baselines. diff --git a/docs/_static/img/mistake.png b/docs/_static/img/mistake.png new file mode 100644 index 0000000000000000000000000000000000000000..8fae18b5994425c7f87e432ee2821e9235088af6 GIT binary patch literal 148639 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

Jy}93c{GGY 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 Discrete +- ``DiagGaussianDistribution`` -> Box (continuous actions) +- ``StateDependentNoiseDistribution`` -> Box (continuous actions) when ``use_sde=True`` + +.. - ``MultiCategoricalDistribution`` -> MultiDiscrete +.. - ``BernoulliDistribution`` -> MultiBinary + +The policy networks output parameters for the distributions (named ``flat`` in the methods). +Actions are then sampled from those distributions. + +For instance, in the case of discrete actions. The policy network outputs probability +of taking each action. The ``CategoricalDistribution`` allows to sample from it, +computes the entropy, the log probability (``log_prob``) and backpropagate the gradient. + +In the case of continuous actions, a Gaussian distribution is used. The policy network outputs +mean and (log) std of the distribution (assumed to be a ``DiagGaussianDistribution``). + +.. automodule:: stable_baselines3.common.distributions + :members: diff --git a/docs/common/env_checker.rst b/docs/common/env_checker.rst new file mode 100644 index 0000000..a5c69bf --- /dev/null +++ b/docs/common/env_checker.rst @@ -0,0 +1,7 @@ +.. _env_checker: + +Gym Environment Checker +======================== + +.. automodule:: stable_baselines3.common.env_checker + :members: diff --git a/docs/common/evaluation.rst b/docs/common/evaluation.rst new file mode 100644 index 0000000..c82fad9 --- /dev/null +++ b/docs/common/evaluation.rst @@ -0,0 +1,7 @@ +.. _eval: + +Evaluation Helper +================= + +.. automodule:: stable_baselines3.common.evaluation + :members: diff --git a/docs/conf.py b/docs/conf.py index ab0e388..5ddbbb7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -216,5 +216,5 @@ texinfo_documents = [ # } # kornia's hack to get rtd builder to install latest pytorch -# if 'READTHEDOCS' in os.environ: -# os.system('pip install torch==1.5.0+cpu torchvision==0.6.0+cpu -f https://download.pytorch.org/whl/torch_stable.html') +if on_rtd: + os.system('pip install torch==1.5.0+cpu torchvision==0.6.0+cpu -f https://download.pytorch.org/whl/torch_stable.html') diff --git a/docs/guide/callbacks.rst b/docs/guide/callbacks.rst new file mode 100644 index 0000000..4a4773e --- /dev/null +++ b/docs/guide/callbacks.rst @@ -0,0 +1,296 @@ +.. _callbacks: + +Callbacks +========= + +A callback is a set of functions that will be called at given stages of the training procedure. +You can use callbacks to access internal state of the RL model during training. +It allows one to do monitoring, auto saving, model manipulation, progress bars, ... + + +Custom Callback +--------------- + +To build a custom callback, you need to create a class that derives from ``BaseCallback``. +This will give you access to events (``_on_training_start``, ``_on_step``) and useful variables (like `self.model` for the RL model). + + +.. You can find two examples of custom callbacks in the documentation: one for saving the best model according to the training reward (see :ref:`Examples `), and one for logging additional values with Tensorboard (see :ref:`Tensorboard section `). + + +.. code-block:: python + + from stable_baselines3.common.callbacks import BaseCallback + + + class CustomCallback(BaseCallback): + """ + A custom callback that derives from ``BaseCallback``. + + :param verbose: (int) Verbosity level 0: not output 1: info 2: debug + """ + def __init__(self, verbose=0): + super(CustomCallback, self).__init__(verbose) + # Those variables will be accessible in the callback + # (they are defined in the base class) + # The RL model + # self.model = None # type: BaseRLModel + # An alias for self.model.get_env(), the environment used for training + # self.training_env = None # type: Union[gym.Env, VecEnv, None] + # Number of time the callback was called + # self.n_calls = 0 # type: int + # self.num_timesteps = 0 # type: int + # local and global variables + # self.locals = None # type: Dict[str, Any] + # self.globals = None # type: Dict[str, Any] + # The logger object, used to report things in the terminal + # self.logger = None # type: logger.Logger + # # Sometimes, for event callback, it is useful + # # to have access to the parent object + # self.parent = None # type: Optional[BaseCallback] + + def _on_training_start(self) -> None: + """ + This method is called before the first rollout starts. + """ + pass + + def _on_rollout_start(self) -> None: + """ + A rollout is the collection of environment interaction + using the current policy. + This event is triggered before collecting new samples. + """ + pass + + def _on_step(self) -> bool: + """ + This method will be called by the model after each call to `env.step()`. + + For child callback (of an `EventCallback`), this will be called + when the event is triggered. + + :return: (bool) If the callback returns False, training is aborted early. + """ + return True + + def _on_rollout_end(self) -> None: + """ + This event is triggered before updating the policy. + """ + pass + + def _on_training_end(self) -> None: + """ + This event is triggered before exiting the `learn()` method. + """ + pass + + +.. note:: + ``self.num_timesteps`` corresponds to the total number of steps taken in the environment, i.e., it is the number of environments multiplied by the number of time ``env.step()`` was called + + For the other algorithms, ``self.num_timesteps`` is incremented by ``n_envs`` (number of environments) after each call to ``env.step()`` + + +.. note:: + + For off-policy algorithms like SAC, DDPG, TD3 or DQN, the notion of ``rollout`` corresponds to the steps taken in the environment between two updates. + + +.. _EventCallback: + +Event Callback +-------------- + +Compared to Keras, Stable Baselines provides a second type of ``BaseCallback``, named ``EventCallback`` that is meant to trigger events. When an event is triggered, then a child callback is called. + +As an example, :ref:`EvalCallback` is an ``EventCallback`` that will trigger its child callback when there is a new best model. +A child callback is for instance :ref:`StopTrainingOnRewardThreshold ` that stops the training if the mean reward achieved by the RL model is above a threshold. + +.. note:: + + We recommend to take a look at the source code of :ref:`EvalCallback` and :ref:`StopTrainingOnRewardThreshold ` to have a better overview of what can be achieved with this kind of callbacks. + + +.. code-block:: python + + class EventCallback(BaseCallback): + """ + Base class for triggering callback on event. + + :param callback: (Optional[BaseCallback]) Callback that will be called + when an event is triggered. + :param verbose: (int) + """ + def __init__(self, callback: Optional[BaseCallback] = None, verbose: int = 0): + super(EventCallback, self).__init__(verbose=verbose) + self.callback = callback + # Give access to the parent + if callback is not None: + self.callback.parent = self + ... + + def _on_event(self) -> bool: + if self.callback is not None: + return self.callback() + return True + + + +Callback Collection +------------------- + +Stable Baselines provides you with a set of common callbacks for: + +- saving the model periodically (:ref:`CheckpointCallback`) +- evaluating the model periodically and saving the best one (:ref:`EvalCallback`) +- chaining callbacks (:ref:`CallbackList`) +- triggering callback on events (:ref:`EventCallback`, :ref:`EveryNTimesteps`) +- stopping the training early based on a reward threshold (:ref:`StopTrainingOnRewardThreshold `) + + +.. _CheckpointCallback: + +CheckpointCallback +^^^^^^^^^^^^^^^^^^ + +Callback for saving a model every ``save_freq`` steps, you must specify a log folder (``save_path``) +and optionally a prefix for the checkpoints (``rl_model`` by default). + + +.. code-block:: python + + from stable_baselines3 import SAC + from stable_baselines3.common.callbacks import CheckpointCallback + # Save a checkpoint every 1000 steps + checkpoint_callback = CheckpointCallback(save_freq=1000, save_path='./logs/', + name_prefix='rl_model') + + model = SAC('MlpPolicy', 'Pendulum-v0') + model.learn(2000, callback=checkpoint_callback) + + +.. _EvalCallback: + +EvalCallback +^^^^^^^^^^^^ + +Evaluate periodically the performance of an agent, using a separate test environment. +It will save the best model if ``best_model_save_path`` folder is specified and save the evaluations results in a numpy archive (`evaluations.npz`) if ``log_path`` folder is specified. + + +.. note:: + + You can pass a child callback via the ``callback_on_new_best`` argument. It will be triggered each time there is a new best model. + + + +.. code-block:: python + + import gym + + from stable_baselines3 import SAC + from stable_baselines3.common.callbacks import EvalCallback + + # Separate evaluation env + eval_env = gym.make('Pendulum-v0') + # Use deterministic actions for evaluation + eval_callback = EvalCallback(eval_env, best_model_save_path='./logs/', + log_path='./logs/', eval_freq=500, + deterministic=True, render=False) + + model = SAC('MlpPolicy', 'Pendulum-v0') + model.learn(5000, callback=eval_callback) + + +.. _Callbacklist: + +CallbackList +^^^^^^^^^^^^ + +Class for chaining callbacks, they will be called sequentially. +Alternatively, you can pass directly a list of callbacks to the `learn()` method, it will be converted automatically to a ``CallbackList``. + + +.. code-block:: python + + import gym + + from stable_baselines3 import SAC + from stable_baselines3.common.callbacks import CallbackList, CheckpointCallback, EvalCallback + + checkpoint_callback = CheckpointCallback(save_freq=1000, save_path='./logs/') + # Separate evaluation env + eval_env = gym.make('Pendulum-v0') + eval_callback = EvalCallback(eval_env, best_model_save_path='./logs/best_model', + log_path='./logs/results', eval_freq=500) + # Create the callback list + callback = CallbackList([checkpoint_callback, eval_callback]) + + model = SAC('MlpPolicy', 'Pendulum-v0') + # Equivalent to: + # model.learn(5000, callback=[checkpoint_callback, eval_callback]) + model.learn(5000, callback=callback) + + +.. _StopTrainingCallback: + +StopTrainingOnRewardThreshold +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Stop the training once a threshold in episodic reward (mean episode reward over the evaluations) has been reached (i.e., when the model is good enough). +It must be used with the :ref:`EvalCallback` and use the event triggered by a new best model. + + +.. code-block:: python + + import gym + + from stable_baselines3 import SAC + from stable_baselines3.common.callbacks import EvalCallback, StopTrainingOnRewardThreshold + + # Separate evaluation env + eval_env = gym.make('Pendulum-v0') + # Stop training when the model reaches the reward threshold + callback_on_best = StopTrainingOnRewardThreshold(reward_threshold=-200, verbose=1) + eval_callback = EvalCallback(eval_env, callback_on_new_best=callback_on_best, verbose=1) + + model = SAC('MlpPolicy', 'Pendulum-v0', verbose=1) + # Almost infinite number of timesteps, but the training will stop + # early as soon as the reward threshold is reached + model.learn(int(1e10), callback=eval_callback) + + +.. _EveryNTimesteps: + +EveryNTimesteps +^^^^^^^^^^^^^^^ + +An :ref:`EventCallback` that will trigger its child callback every ``n_steps`` timesteps. + + +.. note:: + + Because of the way ``PPO1`` and ``TRPO`` work (they rely on MPI), ``n_steps`` is a lower bound between two events. + + +.. code-block:: python + + import gym + + from stable_baselines3 import PPO + from stable_baselines3.common.callbacks import CheckpointCallback, EveryNTimesteps + + # this is equivalent to defining CheckpointCallback(save_freq=500) + # checkpoint_callback will be triggered every 500 steps + checkpoint_on_event = CheckpointCallback(save_freq=1, save_path='./logs/') + event_callback = EveryNTimesteps(n_steps=500, callback=checkpoint_on_event) + + model = PPO('MlpPolicy', 'Pendulum-v0', verbose=1) + + model.learn(int(2e4), callback=event_callback) + + +.. automodule:: stable_baselines3.common.callbacks + :members: diff --git a/docs/guide/checking_nan.rst b/docs/guide/checking_nan.rst new file mode 100644 index 0000000..92f8093 --- /dev/null +++ b/docs/guide/checking_nan.rst @@ -0,0 +1,164 @@ +Dealing with NaNs and infs +========================== + +During the training of a model on a given environment, it is possible that the RL model becomes completely +corrupted when a NaN or an inf is given or returned from the RL model. + +How and why? +------------ + +The issue arises then NaNs or infs do not crash, but simply get propagated through the training, +until all the floating point number converge to NaN or inf. This is in line with the +`IEEE Standard for Floating-Point Arithmetic (IEEE 754) `_ standard, as it says: + +.. note:: + Five possible exceptions can occur: + - Invalid operation (:math:`\sqrt{-1}`, :math:`\inf \times 1`, :math:`\text{NaN}\ \mathrm{mod}\ 1`, ...) return NaN + - Division by zero: + - if the operand is not zero (:math:`1/0`, :math:`-2/0`, ...) returns :math:`\pm\inf` + - if the operand is zero (:math:`0/0`) returns signaling NaN + - Overflow (exponent too high to represent) returns :math:`\pm\inf` + - Underflow (exponent too low to represent) returns :math:`0` + - Inexact (not representable exactly in base 2, eg: :math:`1/5`) returns the rounded value (ex: :code:`assert (1/5) * 3 == 0.6000000000000001`) + +And of these, only ``Division by zero`` will signal an exception, the rest will propagate invalid values quietly. + +In python, dividing by zero will indeed raise the exception: ``ZeroDivisionError: float division by zero``, +but ignores the rest. + +The default in numpy, will warn: ``RuntimeWarning: invalid value encountered`` +but will not halt the code. + + +Anomaly detection with PyTorch +------------------------------ + +To enable NaN detection in PyTorch you can do + +.. code-block:: python + + import torch as th + th.autograd.set_detect_anomaly(True) + + +Numpy parameters +---------------- + +Numpy has a convenient way of dealing with invalid value: `numpy.seterr `_, +which defines for the python process, how it should handle floating point error. + +.. code-block:: python + + import numpy as np + + np.seterr(all='raise') # define before your code. + + print("numpy test:") + + a = np.float64(1.0) + b = np.float64(0.0) + val = a / b # this will now raise an exception instead of a warning. + print(val) + +but this will also avoid overflow issues on floating point numbers: + +.. code-block:: python + + import numpy as np + + np.seterr(all='raise') # define before your code. + + print("numpy overflow test:") + + a = np.float64(10) + b = np.float64(1000) + val = a ** b # this will now raise an exception + print(val) + +but will not avoid the propagation issues: + +.. code-block:: python + + import numpy as np + + np.seterr(all='raise') # define before your code. + + print("numpy propagation test:") + + a = np.float64('NaN') + b = np.float64(1.0) + val = a + b # this will neither warn nor raise anything + print(val) + + +VecCheckNan Wrapper +------------------- + +In order to find when and from where the invalid value originated from, stable-baselines3 comes with a ``VecCheckNan`` wrapper. + +It will monitor the actions, observations, and rewards, indicating what action or observation caused it and from what. + +.. code-block:: python + + import gym + from gym import spaces + import numpy as np + + from stable_baselines3 import PPO + from stable_baselines3.common.vec_env import DummyVecEnv, VecCheckNan + + class NanAndInfEnv(gym.Env): + """Custom Environment that raised NaNs and Infs""" + metadata = {'render.modes': ['human']} + + def __init__(self): + super(NanAndInfEnv, self).__init__() + self.action_space = spaces.Box(low=-np.inf, high=np.inf, shape=(1,), dtype=np.float64) + self.observation_space = spaces.Box(low=-np.inf, high=np.inf, shape=(1,), dtype=np.float64) + + def step(self, _action): + randf = np.random.rand() + if randf > 0.99: + obs = float('NaN') + elif randf > 0.98: + obs = float('inf') + else: + obs = randf + return [obs], 0.0, False, {} + + def reset(self): + return [0.0] + + def render(self, mode='human', close=False): + pass + + # Create environment + env = DummyVecEnv([lambda: NanAndInfEnv()]) + env = VecCheckNan(env, raise_exception=True) + + # Instantiate the agent + model = PPO('MlpPolicy', env) + + # Train the agent + model.learn(total_timesteps=int(2e5)) # this will crash explaining that the invalid value originated from the environment. + +RL Model hyperparameters +------------------------ + +Depending on your hyperparameters, NaN can occurs much more often. +A great example of this: https://github.com/hill-a/stable-baselines/issues/340 + +Be aware, the hyperparameters given by default seem to work in most cases, +however your environment might not play nice with them. +If this is the case, try to read up on the effect each hyperparameters has on the model, +so that you can try and tune them to get a stable model. Alternatively, you can try automatic hyperparameter tuning (included in the rl zoo). + +Missing values from datasets +---------------------------- + +If your environment is generated from an external dataset, do not forget to make sure your dataset does not contain NaNs. +As some datasets will sometimes fill missing values with NaNs as a surrogate value. + +Here is some reading material about finding NaNs: https://pandas.pydata.org/pandas-docs/stable/user_guide/missing_data.html + +And filling the missing values with something else (imputation): https://towardsdatascience.com/how-to-handle-missing-data-8646b18db0d4 diff --git a/docs/guide/custom_env.rst b/docs/guide/custom_env.rst new file mode 100644 index 0000000..62ea72a --- /dev/null +++ b/docs/guide/custom_env.rst @@ -0,0 +1,82 @@ +.. _custom_env: + +Using Custom Environments +========================== + +To use the rl baselines with custom environments, they just need to follow the *gym* interface. +That is to say, your environment must implement the following methods (and inherits from OpenAI Gym Class): + + +.. note:: + If you are using images as input, the input values must be in [0, 255] as the observation + is normalized (dividing by 255 to have values in [0, 1]) when using CNN policies. + + + +.. code-block:: python + + import gym + from gym import spaces + + class CustomEnv(gym.Env): + """Custom Environment that follows gym interface""" + metadata = {'render.modes': ['human']} + + def __init__(self, arg1, arg2, ...): + super(CustomEnv, self).__init__() + # Define action and observation space + # They must be gym.spaces objects + # Example when using discrete actions: + self.action_space = spaces.Discrete(N_DISCRETE_ACTIONS) + # Example for using image as input: + self.observation_space = spaces.Box(low=0, high=255, + shape=(HEIGHT, WIDTH, N_CHANNELS), dtype=np.uint8) + + def step(self, action): + ... + return observation, reward, done, info + def reset(self): + ... + return observation # reward, done, info can't be included + def render(self, mode='human'): + ... + def close (self): + ... + + +Then you can define and train a RL agent with: + +.. code-block:: python + + # Instantiate the env + env = CustomEnv(arg1, ...) + # Define and Train the agent + model = A2C('CnnPolicy', env).learn(total_timesteps=1000) + + +To check that your environment follows the gym interface, please use: + +.. code-block:: python + + from stable_baselines3.common.env_checker import check_env + + env = CustomEnv(arg1, ...) + # It will check your custom environment and output additional warnings if needed + check_env(env) + + + +We have created a `colab notebook `_ for +a concrete example of creating a custom environment. + +You can also find a `complete guide online `_ +on creating a custom Gym environment. + + +Optionally, you can also register the environment with gym, +that will allow you to create the RL agent in one line (and use ``gym.make()`` to instantiate the env). + + +In the project, for testing purposes, we use a custom environment named ``IdentityEnv`` +defined `in this file `_. +An example of how to use it can be found `here `_. diff --git a/docs/guide/install.rst b/docs/guide/install.rst new file mode 100644 index 0000000..0dffd75 --- /dev/null +++ b/docs/guide/install.rst @@ -0,0 +1,152 @@ +.. _install: + +Installation +============ + +Prerequisites +------------- + +Stable-Baselines3 requires python 3.6+. + +Windows 10 +~~~~~~~~~~ + +We recommend using `Anaconda `_ for Windows users for easier installation of Python packages and required libraries. You need an environment with Python version 3.6 or above. + +For a quick start you can move straight to installing Stable-Baselines3 in the next step. + +.. note:: + + Trying to create Atari environments may result to vague errors related to missing DLL files and modules. This is an + issue with atari-py package. `See this discussion for more information `_. + + +Stable Release +~~~~~~~~~~~~~~ +To install Stable Baselines3 with pip, execute: + +.. code-block:: bash + + pip install stable-baselines3[extra] + +This includes an optional dependency OpenCV to display the environments when using ``SubprocVecEnv``. If you do not need it, you can install without OpenCV: + + +.. code-block:: bash + + pip install stable-baselines3 + + +Bleeding-edge version +--------------------- + +.. code-block:: bash + + pip install git+https://github.com/DLR-RM/stable-baselines3 + + +Development verion +------------------ + +To contribute to Stable-Baselines3, with support for running tests and building the documentation. + +.. code-block:: bash + + git clone https://github.com/DLR-RM/stable-baselines3 && cd stable-baselines3 + pip install -e .[docs,tests,extra] + + +.. Using Docker Images +.. ------------------- +.. +.. If you are looking for docker images with stable-baselines already installed in it, +.. we recommend using images from `RL Baselines3 Zoo `_. +.. +.. Otherwise, the following images contained all the dependencies for stable-baselines3 but not the stable-baselines3 package itself. +.. They are made for development. +.. +.. Use Built Images +.. ~~~~~~~~~~~~~~~~ +.. +.. GPU image (requires `nvidia-docker`_): +.. +.. .. code-block:: bash +.. +.. docker pull stablebaselines/stable-baselines3 +.. +.. CPU only: +.. +.. .. code-block:: bash +.. +.. docker pull stablebaselines/stable-baselines3-cpu +.. +.. Build the Docker Images +.. ~~~~~~~~~~~~~~~~~~~~~~~~ +.. +.. Build GPU image (with nvidia-docker): +.. +.. .. code-block:: bash +.. +.. make docker-gpu +.. +.. Build CPU image: +.. +.. .. code-block:: bash +.. +.. make docker-cpu +.. +.. Note: if you are using a proxy, you need to pass extra params during +.. build and do some `tweaks`_: +.. +.. .. code-block:: bash +.. +.. --network=host --build-arg HTTP_PROXY=http://your.proxy.fr:8080/ --build-arg http_proxy=http://your.proxy.fr:8080/ --build-arg HTTPS_PROXY=https://your.proxy.fr:8080/ --build-arg https_proxy=https://your.proxy.fr:8080/ +.. +.. Run the images (CPU/GPU) +.. ~~~~~~~~~~~~~~~~~~~~~~~~ +.. +.. Run the nvidia-docker GPU image +.. +.. .. code-block:: bash +.. +.. docker run -it --runtime=nvidia --rm --network host --ipc=host --name test --mount src="$(pwd)",target=/root/code/stable-baselines,type=bind stablebaselines/stable-baselines bash -c 'cd /root/code/stable-baselines/ && pytest tests/' +.. +.. Or, with the shell file: +.. +.. .. code-block:: bash +.. +.. ./scripts/run_docker_gpu.sh pytest tests/ +.. +.. Run the docker CPU image +.. +.. .. code-block:: bash +.. +.. docker run -it --rm --network host --ipc=host --name test --mount src="$(pwd)",target=/root/code/stable-baselines,type=bind stablebaselines/stable-baselines-cpu bash -c 'cd /root/code/stable-baselines/ && pytest tests/' +.. +.. Or, with the shell file: +.. +.. .. code-block:: bash +.. +.. ./scripts/run_docker_cpu.sh pytest tests/ +.. +.. Explanation of the docker command: +.. +.. - ``docker run -it`` create an instance of an image (=container), and +.. run it interactively (so ctrl+c will work) +.. - ``--rm`` option means to remove the container once it exits/stops +.. (otherwise, you will have to use ``docker rm``) +.. - ``--network host`` don't use network isolation, this allow to use +.. tensorboard/visdom on host machine +.. - ``--ipc=host`` Use the host system’s IPC namespace. IPC (POSIX/SysV IPC) namespace provides +.. separation of named shared memory segments, semaphores and message +.. queues. +.. - ``--name test`` give explicitly the name ``test`` to the container, +.. otherwise it will be assigned a random name +.. - ``--mount src=...`` give access of the local directory (``pwd`` +.. command) to the container (it will be map to ``/root/code/stable-baselines``), so +.. all the logs created in the container in this folder will be kept +.. - ``bash -c '...'`` Run command inside the docker image, here run the tests +.. (``pytest tests/``) +.. +.. .. _nvidia-docker: https://github.com/NVIDIA/nvidia-docker +.. .. _tweaks: https://stackoverflow.com/questions/23111631/cannot-download-docker-images-behind-a-proxy diff --git a/docs/guide/migration.rst b/docs/guide/migration.rst new file mode 100644 index 0000000..263c939 --- /dev/null +++ b/docs/guide/migration.rst @@ -0,0 +1,12 @@ +.. _migration: + +================================ +Migrating from Stable-Baselines +================================ + + +This is a guide to migrate from Stable-Baselines to Stable-Baselines3. + +It also references the main changes. + +**TODO** diff --git a/docs/guide/quickstart.rst b/docs/guide/quickstart.rst index e20f36a..54a967c 100644 --- a/docs/guide/quickstart.rst +++ b/docs/guide/quickstart.rst @@ -6,26 +6,27 @@ Getting Started Most of the library tries to follow a sklearn-like syntax for the Reinforcement Learning algorithms. -Here is a quick example of how to train and run SAC on a Pendulum environment: +Here is a quick example of how to train and run A2C on a CartPole environment: .. code-block:: python import gym - from stable_baselines3.sac.policies import MlpPolicy - from stable_baselines3.common.vec_env import DummyVecEnv - from stable_baselines3 import SAC + from stable_baselines3 import A2C + from stable_baselines3.a2c import MlpPolicy - env = gym.make('Pendulum-v0') + env = gym.make('CartPole-v1') - model = SAC(MlpPolicy, env, verbose=1) + model = A2C(MlpPolicy, env, verbose=1) model.learn(total_timesteps=10000) obs = env.reset() for i in range(1000): - action = model.predict(obs) - obs, rewards, dones, info = env.step(action) + action, _state = model.predict(obs, deterministic=True) + obs, reward, done, info = env.step(action) env.render() + if done: + obs = env.reset() Or just train a model with a one liner if @@ -34,6 +35,6 @@ the policy is registered: .. code-block:: python - from stable_baselines3 import SAC + from stable_baselines3 import A2C - model = SAC('MlpPolicy', 'Pendulum-v0').learn(10000) + model = A2C('MlpPolicy', 'CartPole-v1').learn(10000) diff --git a/docs/guide/rl.rst b/docs/guide/rl.rst new file mode 100644 index 0000000..49d9996 --- /dev/null +++ b/docs/guide/rl.rst @@ -0,0 +1,17 @@ +.. _rl: + +================================ +Reinforcement Learning Resources +================================ + + +Stable-Baselines3 assumes that you already understand the basic concepts of Reinforcement Learning (RL). + +However, if you want to learn about RL, there are several good resources to get started: + +- `OpenAI Spinning Up `_ +- `David Silver's course `_ +- `Lilian Weng's blog `_ +- `Berkeley's Deep RL Bootcamp `_ +- `Berkeley's Deep Reinforcement Learning course `_ +- `More resources `_ diff --git a/docs/guide/rl_tips.rst b/docs/guide/rl_tips.rst new file mode 100644 index 0000000..1992a90 --- /dev/null +++ b/docs/guide/rl_tips.rst @@ -0,0 +1,251 @@ +.. _rl_tips: + +====================================== +Reinforcement Learning Tips and Tricks +====================================== + +The aim of this section is to help you doing reinforcement learning experiments. +It covers general advice about RL (where to start, which algorithm to choose, how to evaluate an algorithm, ...), +as well as tips and tricks when using a custom environment or implementing an RL algorithm. + + +General advice when using Reinforcement Learning +================================================ + +TL;DR +----- + +1. Read about RL and Stable Baselines +2. Do quantitative experiments and hyperparameter tuning if needed +3. Evaluate the performance using a separate test environment +4. For better performance, increase the training budget + + +Like any other subject, if you want to work with RL, you should first read about it (we have a dedicated `resource page `_ to get you started) +to understand what you are using. We also recommend you read Stable Baselines (SB) documentation and do the `tutorial `_. +It covers basic usage and guide you towards more advanced concepts of the library (e.g. callbacks and wrappers). + +Reinforcement Learning differs from other machine learning methods in several ways. The data used to train the agent is collected +through interactions with the environment by the agent itself (compared to supervised learning where you have a fixed dataset for instance). +This dependence can lead to vicious circle: if the agent collects poor quality data (e.g., trajectories with no rewards), then it will not improve and continue to amass +bad trajectories. + +This factor, among others, explains that results in RL may vary from one run to another (i.e., when only the seed of the pseudo-random generator changes). +For this reason, you should always do several runs to have quantitative results. + +Good results in RL are generally dependent on finding appropriate hyperparameters. Recent algorithms (PPO, SAC, TD3) normally require little hyperparameter tuning, +however, *don't expect the default ones to work* on any environment. + +Therefore, we *highly recommend you* to take a look at the `RL zoo `_ (or the original papers) for tuned hyperparameters. +A best practice when you apply RL to a new problem is to do automatic hyperparameter optimization. Again, this is included in the `RL zoo `_. + +When applying RL to a custom problem, you should always normalize the input to the agent (e.g. using VecNormalize for PPO2/A2C) +and look at common preprocessing done on other environments (e.g. for `Atari `_, frame-stack, ...). +Please refer to *Tips and Tricks when creating a custom environment* paragraph below for more advice related to custom environments. + + +Current Limitations of RL +------------------------- + +You have to be aware of the current `limitations `_ of reinforcement learning. + + +Model-free RL algorithms (i.e. all the algorithms implemented in SB) are usually *sample inefficient*. They require a lot of samples (sometimes millions of interactions) to learn something useful. +That's why most of the successes in RL were achieved on games or in simulation only. For instance, in this `work `_ by ETH Zurich, the ANYmal robot was trained in simulation only, and then tested in the real world. + +As a general advice, to obtain better performances, you should augment the budget of the agent (number of training timesteps). + + +In order to achieve the desired behavior, expert knowledge is often required to design an adequate reward function. +This *reward engineering* (or *RewArt* as coined by `Freek Stulp `_), necessitates several iterations. As a good example of reward shaping, +you can take a look at `Deep Mimic paper `_ which combines imitation learning and reinforcement learning to do acrobatic moves. + +One last limitation of RL is the instability of training. That is to say, you can observe during training a huge drop in performance. +This behavior is particularly present in ``DDPG``, that's why its extension ``TD3`` tries to tackle that issue. +Other method, like ``TRPO`` or ``PPO`` make use of a *trust region* to minimize that problem by avoiding too large update. + + +How to evaluate an RL algorithm? +-------------------------------- + +Because most algorithms use exploration noise during training, you need a separate test environment to evaluate the performance +of your agent at a given time. It is recommended to periodically evaluate your agent for ``n`` test episodes (``n`` is usually between 5 and 20) +and average the reward per episode to have a good estimate. + +As some policy are stochastic by default (e.g. A2C or PPO), you should also try to set `deterministic=True` when calling the `.predict()` method, +this frequently leads to better performance. +Looking at the training curve (episode reward function of the timesteps) is a good proxy but underestimates the agent true performance. + + +.. note:: + + We provide an ``EvalCallback`` for doing such evaluation. You can read more about it in the :ref:`Callbacks ` section. + + + +We suggest you reading `Deep Reinforcement Learning that Matters `_ for a good discussion about RL evaluation. + +You can also take a look at this `blog post `_ +and this `issue `_ by Cédric Colas. + + +Which algorithm should I use? +============================= + +There is no silver bullet in RL, depending on your needs and problem, you may choose one or the other. +The first distinction comes from your action space, i.e., do you have discrete (e.g. LEFT, RIGHT, ...) +or continuous actions (ex: go to a certain speed)? + +Some algorithms are only tailored for one or the other domain: ``DQN`` only supports discrete actions, where ``SAC`` is restricted to continuous actions. + +The second difference that will help you choose is whether you can parallelize your training or not. +If what matters is the wall clock training time, then you should lean towards ``A2C`` and its derivatives (PPO, ...). +Take a look at the `Vectorized Environments `_ to learn more about training with multiple workers. + +To sum it up: + +Discrete Actions +---------------- + +.. note:: + + This covers ``Discrete``, ``MultiDiscrete``, ``Binary`` and ``MultiBinary`` spaces + + +Discrete Actions - Single Process +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +DQN with extensions (double DQN, prioritized replay, ...) are the recommended algorithms. +DQN is usually slower to train (regarding wall clock time) but is the most sample efficient (because of its replay buffer). + +Discrete Actions - Multiprocessed +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You should give a try to PPO or A2C. + + +Continuous Actions +------------------ + +Continuous Actions - Single Process +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Current State Of The Art (SOTA) algorithms are ``SAC`` and ``TD3``. +Please use the hyperparameters in the `RL zoo `_ for best results. + + +Continuous Actions - Multiprocessed +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Take a look at PPO2, TRPO or A2C. Again, don't forget to take the hyperparameters from the `RL zoo `_ +for continuous actions problems (cf *Bullet* envs). + +.. note:: + + Normalization is critical for those algorithms + + + +.. Goal Environment +.. ----------------- +.. +.. If your environment follows the ``GoalEnv`` interface (cf `HER <../modules/her.html>`_), then you should use +.. HER + (SAC/TD3/DDPG/DQN) depending on the action space. +.. +.. +.. .. note:: +.. +.. The number of workers is an important hyperparameters for experiments with HER +.. + + +Tips and Tricks when creating a custom environment +================================================== + +If you want to learn about how to create a custom environment, we recommend you read this `page `_. +We also provide a `colab notebook `_ for +a concrete example of creating a custom gym environment. + +Some basic advice: + +- always normalize your observation space when you can, i.e., when you know the boundaries +- normalize your action space and make it symmetric when continuous (cf potential issue below) A good practice is to rescale your actions to lie in [-1, 1]. This does not limit you as you can easily rescale the action inside the environment +- start with shaped reward (i.e. informative reward) and simplified version of your problem +- debug with random actions to check that your environment works and follows the gym interface: + + +We provide a helper to check that your environment runs without error: + +.. code-block:: python + + from stable_baselines3.common.env_checker import check_env + + env = CustomEnv(arg1, ...) + # It will check your custom environment and output additional warnings if needed + check_env(env) + + +If you want to quickly try a random agent on your environment, you can also do: + +.. code-block:: python + + env = YourEnv() + obs = env.reset() + n_steps = 10 + for _ in range(n_steps): + # Random action + action = env.action_space.sample() + obs, reward, done, info = env.step(action) + if done: + obs = env.reset() + + +**Why should I normalize the action space?** + + +Most reinforcement learning algorithms rely on a Gaussian distribution (initially centered at 0 with std 1) for continuous actions. +So, if you forget to normalize the action space when using a custom environment, +this can harm learning and be difficult to debug (cf attached image and `issue #473 `_). + +.. figure:: ../_static/img/mistake.png + + +Another consequence of using a Gaussian is that the action range is not bounded. +That's why clipping is usually used as a bandage to stay in a valid interval. +A better solution would be to use a squashing function (cf ``SAC``) or a Beta distribution (cf `issue #112 `_). + +.. note:: + + This statement is not true for ``DDPG`` or ``TD3`` because they don't rely on any probability distribution. + + + +Tips and Tricks when implementing an RL algorithm +================================================= + +When you try to reproduce a RL paper by implementing the algorithm, the `nuts and bolts of RL research `_ +by John Schulman are quite useful (`video `_). + +We *recommend following those steps to have a working RL algorithm*: + +1. Read the original paper several times +2. Read existing implementations (if available) +3. Try to have some "sign of life" on toy problems +4. Validate the implementation by making it run on harder and harder envs (you can compare results against the RL zoo) + You usually need to run hyperparameter optimization for that step. + +You need to be particularly careful on the shape of the different objects you are manipulating (a broadcast mistake will fail silently cf `issue #75 `_) +and when to stop the gradient propagation. + +A personal pick (by @araffin) for environments with gradual difficulty in RL with continuous actions: + +1. Pendulum (easy to solve) +2. HalfCheetahBullet (medium difficulty with local minima and shaped reward) +3. BipedalWalkerHardcore (if it works on that one, then you can have a cookie) + +in RL with discrete actions: + +1. CartPole-v1 (easy to be better than random agent, harder to achieve maximal performance) +2. LunarLander +3. Pong (one of the easiest Atari game) +4. other Atari games (e.g. Breakout) diff --git a/docs/guide/vec_envs.rst b/docs/guide/vec_envs.rst index 2bce8d1..7a52a27 100644 --- a/docs/guide/vec_envs.rst +++ b/docs/guide/vec_envs.rst @@ -6,11 +6,11 @@ Vectorized Environments ======================= Vectorized Environments are a method for stacking multiple independent environments into a single environment. -Instead of training an RL agent on 1 environment per step, it allows us to train it on `n` environments per step. -Because of this, `actions` passed to the environment are now a vector (of dimension `n`). -It is the same for `observations`, `rewards` and end of episode signals (`dones`). -In the case of non-array observation spaces such as `Dict` or `Tuple`, where different sub-spaces -may have different shapes, the sub-observations are vectors (of dimension `n`). +Instead of training an RL agent on 1 environment per step, it allows us to train it on ``n`` environments per step. +Because of this, ``actions`` passed to the environment are now a vector (of dimension ``n``). +It is the same for ``observations``, ``rewards`` and end of episode signals (``dones``). +In the case of non-array observation spaces such as ``Dict`` or ``Tuple``, where different sub-spaces +may have different shapes, the sub-observations are vectors (of dimension ``n``). ============= ======= ============ ======== ========= ================ Name ``Box`` ``Discrete`` ``Dict`` ``Tuple`` Multi Processing @@ -27,7 +27,7 @@ SubprocVecEnv ✔️ ✔️ ✔️ ✔️ ✔️ When using vectorized environments, the environments are automatically reset at the end of each episode. Thus, the observation returned for the i-th environment when ``done[i]`` is true will in fact be the first observation of the next episode, not the last observation of the episode that has just terminated. - You can access the "real" final observation of the terminated episode—that is, the one that accompanied the ``done`` event provided by the underlying environment—using the ``terminal_observation`` keys in the info dicts returned by the `VecEnv`. + You can access the "real" final observation of the terminated episode—that is, the one that accompanied the ``done`` event provided by the underlying environment—using the ``terminal_observation`` keys in the info dicts returned by the vecenv. .. warning:: @@ -69,3 +69,24 @@ VecNormalize .. autoclass:: VecNormalize :members: + + +VecVideoRecorder +~~~~~~~~~~~~~~~~ + +.. autoclass:: VecVideoRecorder + :members: + + +VecCheckNan +~~~~~~~~~~~~~~~~ + +.. autoclass:: VecCheckNan + :members: + + +VecTransposeImage +~~~~~~~~~~~~~~~~~ + +.. autoclass:: VecTransposeImage + :members: diff --git a/docs/index.rst b/docs/index.rst index 9cffb4d..149ddb1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -.. Stable Baselines documentation master file, created by +.. Stable Baselines3 documentation master file, created by sphinx-quickstart on Thu Sep 26 11:06:54 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. @@ -6,21 +6,41 @@ Welcome to Stable Baselines3 docs! ================================== -`Stable Baselines3 `_ is the next major version (PyTorch edition) of `Stable Baselines `_, -a set of improved implementations of reinforcement learning algorithms. +`Stable Baselines3 `_ is a set of improved implementations of reinforcement learning algorithms in PyTorch. +It is the next major version (PyTorch edition) of `Stable Baselines `_. + + +Github repository: https://github.com/DLR-RM/stable-baselines3 RL Baselines3 Zoo (collection of pre-trained agents): https://github.com/DLR-RM/rl-baselines3-zoo RL Baselines3 Zoo also offers a simple interface to train, evaluate agents and do hyperparameter tuning. +Main Features +-------------- + +- Unified structure for all algorithms +- PEP8 compliant (unified code style) +- Documented functions and classes +- Tests, high code coverage and type hints +- Clean code + + .. toctree:: :maxdepth: 2 :caption: User Guide + guide/install guide/quickstart + guide/rl_tips + guide/rl guide/vec_envs + guide/custom_env + guide/callbacks + guide/migration + guide/checking_nan .. toctree:: @@ -33,12 +53,20 @@ RL Baselines3 Zoo also offers a simple interface to train, evaluate agents and d modules/sac modules/td3 +.. toctree:: + :maxdepth: 1 + :caption: Common + + common/distributions + common/evaluation + common/env_checker .. toctree:: :maxdepth: 1 :caption: Misc misc/changelog + misc/projects Citing Stable Baselines3 diff --git a/docs/misc/changelog.rst b/docs/misc/changelog.rst index 401a64a..c1c831f 100644 --- a/docs/misc/changelog.rst +++ b/docs/misc/changelog.rst @@ -29,6 +29,7 @@ Others: Documentation: ^^^^^^^^^^^^^^ +- Added most documentation (adapted from Stable-Baselines) Pre-Release 0.5.0 (2020-05-05) diff --git a/docs/misc/projects.rst b/docs/misc/projects.rst new file mode 100644 index 0000000..58b24bc --- /dev/null +++ b/docs/misc/projects.rst @@ -0,0 +1,26 @@ +.. _projects: + +Projects +========= + +This is a list of projects using stable-baselines3. +Please tell us, if you want your project to appear on this page ;) + + +.. RL Racing Robot +.. -------------------------- +.. Implementation of reinforcement learning approach to make a donkey car learn to race. +.. Uses SAC on autoencoder features +.. +.. | Author: Antonin Raffin (@araffin) +.. | Github repo: https://github.com/araffin/RL-Racing-Robot + + +.. Generalized State Dependent Exploration for Deep Reinforcement Learning in Robotics +.. ----------------------------------------------------------------------------------- +.. +.. An exploration method to train RL agent directly on real robots. +.. +.. | Author: Antonin Raffin, Freek Stulp +.. | Github: https://github.com/DLR-RM/stable-baselines3/tree/sde +.. | Paper: diff --git a/docs/modules/a2c.rst b/docs/modules/a2c.rst index 0ee3aa7..38374f7 100644 --- a/docs/modules/a2c.rst +++ b/docs/modules/a2c.rst @@ -38,15 +38,15 @@ MultiBinary ❌ ❌ Example ------- -Train a A2C agent on `CartPole-v1` using 4 processes. +Train a A2C agent on ``CartPole-v1`` using 4 environments. .. code-block:: python import gym - from stable_baselines3.common.policies import MlpPolicy - from stable_baselines3.common import make_vec_env from stable_baselines3 import A2C + from stable_baselines3.a2c import MlpPolicy + from stable_baselines3.common.cmd_utils import make_vec_env # Parallel environments env = make_vec_env('CartPole-v1', n_envs=4) diff --git a/docs/modules/base.rst b/docs/modules/base.rst index 7fa2a59..36541d8 100644 --- a/docs/modules/base.rst +++ b/docs/modules/base.rst @@ -10,3 +10,12 @@ Common interface for all the RL algorithms .. autoclass:: BaseRLModel :members: + + +Base RL Class +============= + +The base RL model for Off-Policy algorithm (ex: SAC/TD3) + +.. autoclass:: OffPolicyRLModel + :members: diff --git a/docs/modules/ppo.rst b/docs/modules/ppo.rst index 477c13f..fb83c89 100644 --- a/docs/modules/ppo.rst +++ b/docs/modules/ppo.rst @@ -47,34 +47,32 @@ MultiBinary ❌ ❌ Example ------- -Train a PPO agent on `Pendulum-v0` using 4 processes. +Train a PPO agent on ``Pendulum-v0`` using 4 environments. .. code-block:: python - import gym + import gym - from stable_baselines3.ppo.policies import MlpPolicy - from stable_baselines3.common.vec_env import SubprocVecEnv - from stable_baselines3 import PPO + from stable_baselines3 import A2C + from stable_baselines3.ppo import MlpPolicy + from stable_baselines3.common.cmd_utils import make_vec_env - # multiprocess environment - n_cpu = 4 - env = SubprocVecEnv([lambda: gym.make('Pendulum-v0') for i in range(n_cpu)]) + # Parallel environments + env = make_vec_env('CartPole-v1', n_envs=4) - model = PPO(MlpPolicy, env, verbose=1) - model.learn(total_timesteps=25000) - model.save("ppo2_cartpole") + model = PPO(MlpPolicy, env, verbose=1) + model.learn(total_timesteps=25000) + model.save("ppo_cartpole") - del model # remove to demonstrate saving and loading + del model # remove to demonstrate saving and loading - model = PPO.load("ppo2_cartpole") + model = PPO.load("ppo_cartpole") - # Enjoy trained agent - obs = env.reset() - while True: - action, _states = model.predict(obs) - obs, rewards, dones, info = env.step(action) - env.render() + obs = env.reset() + while True: + action, _states = model.predict(obs) + obs, rewards, dones, info = env.step(action) + env.render() Parameters ---------- diff --git a/docs/modules/sac.rst b/docs/modules/sac.rst index c067bcf..359df4b 100644 --- a/docs/modules/sac.rst +++ b/docs/modules/sac.rst @@ -14,7 +14,7 @@ A key feature of SAC, and a major difference with common RL algorithms, is that .. warning:: - The SAC model does not support ``stable_baselines3.common.policies`` because it uses double q-values + The SAC model does not support ``stable_baselines3.ppo.policies`` because it uses double q-values and value estimation, as a result it must use its own policy models (see :ref:`sac_policies`). @@ -24,6 +24,7 @@ A key feature of SAC, and a major difference with common RL algorithms, is that :nosignatures: MlpPolicy + CnnPolicy Notes @@ -72,15 +73,13 @@ Example import gym import numpy as np - from stable_baselines3.sac.policies import MlpPolicy - from stable_baselines3.common.vec_env import DummyVecEnv from stable_baselines3 import SAC + from stable_baselines3.sac import MlpPolicy env = gym.make('Pendulum-v0') - env = DummyVecEnv([lambda: env]) model = SAC(MlpPolicy, env, verbose=1) - model.learn(total_timesteps=50000, log_interval=10) + model.learn(total_timesteps=10000, log_interval=4) model.save("sac_pendulum") del model # remove to demonstrate saving and loading @@ -90,8 +89,10 @@ Example obs = env.reset() while True: action, _states = model.predict(obs) - obs, rewards, dones, info = env.step(action) + obs, reward, done, info = env.step(action) env.render() + if done: + obs = env.reset() Parameters ---------- @@ -108,3 +109,7 @@ SAC Policies .. autoclass:: MlpPolicy :members: :inherited-members: + +.. .. autoclass:: CnnPolicy +.. :members: +.. :inherited-members: diff --git a/docs/modules/td3.rst b/docs/modules/td3.rst index 338b9da..02ae391 100644 --- a/docs/modules/td3.rst +++ b/docs/modules/td3.rst @@ -14,7 +14,7 @@ We recommend reading `OpenAI Spinning guide on TD3