Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/google/dopamine

Dopamine is a research framework for fast prototyping of reinforcement learning algorithms.
https://github.com/google/dopamine

ai google ml rl tensorflow

Last synced: 5 days ago
JSON representation

Dopamine is a research framework for fast prototyping of reinforcement learning algorithms.

Awesome Lists containing this project

README 

        
# Dopamine

[Getting Started](#getting-started) |

[Docs][docs] |

[Baseline Results][baselines] |

[Changelist](https://google.github.io/dopamine/docs/changelist)





  






Dopamine is a research framework for fast prototyping of reinforcement learning

algorithms. It aims to fill the need for a small, easily grokked codebase in

which users can freely experiment with wild ideas (speculative research).



Our design principles are:



* _Easy experimentation_: Make it easy for new users to run benchmark

                          experiments.

* _Flexible development_: Make it easy for new users to try out research ideas.

* _Compact and reliable_: Provide implementations for a few, battle-tested

                          algorithms.

* _Reproducible_: Facilitate reproducibility in results. In particular, our

                  setup follows the recommendations given by

                  [Machado et al. (2018)][machado].



Dopamine supports the following agents, implemented with jax:



* DQN ([Mnih et al., 2015][dqn])

* C51 ([Bellemare et al., 2017][c51])

* Rainbow ([Hessel et al., 2018][rainbow])

* IQN ([Dabney et al., 2018][iqn])

* SAC ([Haarnoja et al., 2018][sac])

* PPO ([Schulman et al., 2017][ppo])



For more information on the available agents, see the [docs](https://google.github.io/dopamine/docs).



Many of these agents also have a tensorflow (legacy) implementation, though

newly added agents are likely to be jax-only.



This is not an official Google product.



## Getting Started



We provide docker containers for using Dopamine.

Instructions can be found [here](https://google.github.io/dopamine/docker/).



Alternatively, Dopamine can be installed from source (preferred) or installed

with pip. For either of these methods, continue reading at prerequisites.



### Prerequisites



Dopamine supports Atari environments and Mujoco environments. Install the

environments you intend to use before you install Dopamine:



**Atari**



1. These should now come packaged with

   [ale_py](https://github.com/Farama-Foundation/Arcade-Learning-Environment).

1. You may need to manually run some steps to properly install `baselines`, see

   [instructions](https://github.com/openai/baselines).



**Mujoco**



1. Install Mujoco and get a license

[here](https://github.com/openai/mujoco-py#install-mujoco).

2. Run `pip install mujoco-py` (we recommend using a

[virtual environment](virtualenv)).



### Installing from Source



The most common way to use Dopamine is to install it from source and modify

the source code directly:



```

git clone https://github.com/google/dopamine

```



After cloning, install dependencies:



```

pip install -r dopamine/requirements.txt

```



Dopamine supports tensorflow (legacy) and jax (actively maintained) agents.

View the [Tensorflow documentation](https://www.tensorflow.org/install) for

more information on installing tensorflow.



Note: We recommend using a [virtual environment](virtualenv) when working with Dopamine.



### Installing with Pip



Note: We strongly recommend installing from source for most users.



Installing with pip is simple, but Dopamine is designed to be modified

directly. We recommend installing from source for writing your own experiments.



```

pip install dopamine-rl

```



### Running tests



You can test whether the installation was successful by running the following

from the dopamine root directory.



```

export PYTHONPATH=$PYTHONPATH:$PWD

python -m tests.dopamine.atari_init_test

```



## Next Steps



View the [docs][docs] for more information on training agents.



We supply [baselines][baselines] for each Dopamine agent.



We also provide a set of [Colaboratory notebooks](https://github.com/google/dopamine/tree/master/dopamine/colab)

which demonstrate how to use Dopamine.



## References



[Bellemare et al., *The Arcade Learning Environment: An evaluation platform for

general agents*. Journal of Artificial Intelligence Research, 2013.][ale]



[Machado et al., *Revisiting the Arcade Learning Environment: Evaluation

Protocols and Open Problems for General Agents*, Journal of Artificial

Intelligence Research, 2018.][machado]



[Hessel et al., *Rainbow: Combining Improvements in Deep Reinforcement Learning*.

Proceedings of the AAAI Conference on Artificial Intelligence, 2018.][rainbow]



[Mnih et al., *Human-level Control through Deep Reinforcement Learning*. Nature,

2015.][dqn]



[Schaul et al., *Prioritized Experience Replay*. Proceedings of the International

Conference on Learning Representations, 2016.][prioritized_replay]



[Haarnoja et al., *Soft Actor-Critic Algorithms and Applications*,

arXiv preprint arXiv:1812.05905, 2018.][sac]



[Schulman et al., *Proximal Policy Optimization Algorithms*.][ppo]



## Giving credit



If you use Dopamine in your work, we ask that you cite our

[white paper][dopamine_paper]. Here is an example BibTeX entry:



```

@article{castro18dopamine,

  author    = {Pablo Samuel Castro and

               Subhodeep Moitra and

               Carles Gelada and

               Saurabh Kumar and

               Marc G. Bellemare},

  title     = {Dopamine: {A} {R}esearch {F}ramework for {D}eep {R}einforcement {L}earning},

  year      = {2018},

  url       = {http://arxiv.org/abs/1812.06110},

  archivePrefix = {arXiv}

}

```



[docs]: https://google.github.io/dopamine/docs/

[baselines]: https://google.github.io/dopamine/baselines

[machado]: https://jair.org/index.php/jair/article/view/11182

[ale]: https://jair.org/index.php/jair/article/view/10819

[dqn]: https://storage.googleapis.com/deepmind-media/dqn/DQNNaturePaper.pdf

[a3c]: http://proceedings.mlr.press/v48/mniha16.html

[prioritized_replay]: https://arxiv.org/abs/1511.05952

[c51]: http://proceedings.mlr.press/v70/bellemare17a.html

[rainbow]: https://www.aaai.org/ocs/index.php/AAAI/AAAI18/paper/download/17204/16680

[iqn]: https://arxiv.org/abs/1806.06923

[sac]: https://arxiv.org/abs/1812.05905

[ppo]: https://arxiv.org/abs/1707.06347

[dopamine_paper]: https://arxiv.org/abs/1812.06110

[vitualenv]: https://docs.python.org/3/library/venv.html#creating-virtual-environments