pettingzoo

An API standard for multi-agent reinforcement learning environments, with popular reference environments and related utilities

https://github.com/farama-foundation/pettingzoo

Science Score: 64.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
✓
Academic publication links
Links to: arxiv.org
✓
Committers with academic emails
10 of 124 committers (8.1%) from academic institutions
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (15.9%) to scientific vocabulary

Keywords

api gym gymnasium multi-agent-reinforcement-learning multiagent-reinforcement-learning reinforcement-learning

Keywords from Contributors

gym-environment offline-rl gridworld-environment jax cryptocurrency data-profilers datacleaner pipeline-testing distributed yolov5s

Last synced: 6 months ago · JSON representation ·

Repository

An API standard for multi-agent reinforcement learning environments, with popular reference environments and related utilities

Basic Info

Host: GitHub
Owner: Farama-Foundation
License: other
Language: Python
Default Branch: master
Homepage: https://pettingzoo.farama.org
Size: 176 MB

Statistics

Stars: 3,069
Watchers: 16
Forks: 446
Open Issues: 46
Releases: 42

Topics

api gym gymnasium multi-agent-reinforcement-learning multiagent-reinforcement-learning reinforcement-learning

Created about 6 years ago · Last pushed 9 months ago

Metadata Files

Readme Contributing Funding License Code of conduct Citation

README.md

PettingZoo is a Python library for conducting research in multi-agent reinforcement learning, akin to a multi-agent version of Gymnasium.

The documentation website is at pettingzoo.farama.org and we have a public discord server (which we also use to coordinate development work) that you can join here: https://discord.gg/nhvKkYa6qX

Environments

PettingZoo includes the following families of environments:

Atari: Multi-player Atari 2600 games (cooperative, competitive and mixed sum)
Butterfly: Cooperative graphical games developed by us, requiring a high degree of coordination
Classic: Classical games including card games, board games, etc.
MPE: A set of simple nongraphical communication tasks, originally from https://github.com/openai/multiagent-particle-envs
SISL: 3 cooperative environments, originally from https://github.com/sisl/MADRL

Installation

To install the base PettingZoo library: pip install pettingzoo.

This does not include dependencies for all families of environments (some environments can be problematic to install on certain systems).

To install the dependencies for one family, use pip install 'pettingzoo[atari]', or use pip install 'pettingzoo[all]' to install all dependencies.

We support and maintain PettingZoo for Python 3.9, 3.10, 3.11, and 3.12 on Linux and macOS. We will accept PRs related to Windows, but do not officially support it.

Note: Some Linux distributions may require manual installation of cmake, swig, or zlib1g-dev (e.g., sudo apt install cmake swig zlib1g-dev)

Getting started

For an introduction to PettingZoo, see Basic Usage. To create a new environment, see our Environment Creation Tutorial and Custom Environment Examples. For examples of training RL models using PettingZoo see our tutorials: * CleanRL: Implementing PPO: train multiple PPO agents in the Pistonball environment. * Tianshou: Training Agents: train DQN agents in the Tic-Tac-Toe environment. * AgileRL: Training, Curriculums and Self-play: train agents with curriculum learning and self-play in the Connect Four environment.

API

PettingZoo model environments as Agent Environment Cycle (AEC) games, in order to be able to cleanly support all types of multi-agent RL environments under one API and to minimize the potential for certain classes of common bugs.

Using environments in PettingZoo is very similar to Gymnasium, i.e. you initialize an environment via:

python from pettingzoo.butterfly import pistonball_v6 env = pistonball_v6.env()

Environments can be interacted with in a manner very similar to Gymnasium:

python env.reset() for agent in env.agent_iter(): observation, reward, termination, truncation, info = env.last() action = None if termination or truncation else env.action_space(agent).sample() # this is where you would insert your policy env.step(action)

For the complete API documentation, please see https://pettingzoo.farama.org/api/aec/

Parallel API

In certain environments, it's a valid to assume that agents take their actions at the same time. For these games, we offer a secondary API to allow for parallel actions, documented at https://pettingzoo.farama.org/api/parallel/

SuperSuit

SuperSuit is a library that includes all commonly used wrappers in RL (frame stacking, observation, normalization, etc.) for PettingZoo and Gymnasium environments with a nice API. We developed it in lieu of wrappers built into PettingZoo. https://github.com/Farama-Foundation/SuperSuit

Environment Versioning

PettingZoo keeps strict versioning for reproducibility reasons. All environments end in a suffix like "_v0". When changes are made to environments that might impact learning results, the number is increased by one to prevent potential confusion.

Citation

To cite this project in publication, please use

@article{terry2021pettingzoo, title={Pettingzoo: Gym for multi-agent reinforcement learning}, author={Terry, J and Black, Benjamin and Grammel, Nathaniel and Jayakumar, Mario and Hari, Ananth and Sullivan, Ryan and Santos, Luis S and Dieffendahl, Clemens and Horsch, Caroline and Perez-Vicente, Rodrigo and others}, journal={Advances in Neural Information Processing Systems}, volume={34}, pages={15032--15043}, year={2021} }

Project Maintainers

Project Manager: David Gerard - david.gerard.23@ucl.ac.uk
Maintainer: Albert Han - yjhan96@gmail.com.
Maintenance for this project is also contributed by the broader Farama team: farama.org/team.

Owner

Name: Farama Foundation
Login: Farama-Foundation
Kind: organization
Email: contact@farama.org

Website: farama.org
Twitter: FaramaFound
Repositories: 49
Profile: https://github.com/Farama-Foundation

The Farama foundation is a nonprofit organization working to develop and maintain open source reinforcement learning tools.

Citation (CITATION.cff)

cff-version: 1.2.0
title: 'PettingZoo: Gym for multi-agent reinforcement learning'
message: >-
  If you use this software, please cite it using the
  metadata from this file.
type: software
authors:
  - given-names: Jordan
    family-names: Terry
    email: j.k.terry@swarmlabs.com
  - given-names: Benjamin
    family-names: Black
    email: benjamin.black@swarmlabs.com
  - given-names: Nathaniel
    family-names: Grammel
    email: ngrammel@umd.edu
  - given-names: Mario
    family-names: Jayakumar
    email: mariojay@umd.edu
  - given-names: Ananth
    family-names: Hari
    email: aharil@umd.edu
  - given-names: Ryan
    family-names: Sullivan
    email: ryna.sullivan@swarmlabs.com
  - given-names: Luis
    family-names: Santos
    email: lss@umd.edu
  - given-names: Rodrigo
    family-names: Perez
    email: rlazcano@umd.edu
  - given-names: Caroline
    family-names: Horsch
    email: caroline.horsch@swarmlabs.com
  - given-names: Clemens
    family-names: Dieffendahl
    email: dieffendahl@campus.tu-berlin.de
  - given-names: Niall
    family-names: Williams
    email: niallw@umd.edu
  - given-names: Yashas
    family-names: Lokesh
    email: yashloke@umd.edu
identifiers:
  - type: url
    value: >-
      https://proceedings.neurips.cc/paper_files/paper/2021/file/7ed2d3454c5eea71148b11d0c25104ff-Paper.pdf
  - type: doi
    value: 10.48550/arXiv.2009.14471
repository-code: 'https://github.com/Farama-Foundation/PettingZoo'
url: 'https://pettingzoo.farama.org/'
abstract: >-
  This paper introduces the PettingZoo library and the
  accompanying Agent Environment Cycle ("AEC") games model.
  PettingZoo is a library of diverse sets of multi-agent
  environments with a universal, elegant Python API.
  PettingZoo was developed with the goal of accelerating
  research in Multi-Agent Reinforcement Learning ("MARL"),
  by making work more interchangeable, accessible and
  reproducible akin to what OpenAI's Gym library did for
  single-agent reinforcement learning. PettingZoo's API,
  while inheriting many features of Gym, is unique amongst
  MARL APIs in that it's based around the novel AEC games
  model. We argue, in part through case studies on major
  problems in popular MARL environments, that the popular
  game models are poor conceptual models of games commonly
  used in MARL and accordingly can promote confusing bugs
  that are hard to detect, and that the AEC games model
  addresses these problems.
keywords:
  - Machine Learning
  - Reinforcement Learning
  - Multiagent Reinforcement Learning
  - Multiagent Systems
license: MIT

GitHub Events

Total

Create event: 18
Release event: 4
Issues event: 49
Watch event: 452
Delete event: 10
Member event: 2
Issue comment event: 92
Push event: 108
Pull request review comment event: 31
Pull request review event: 55
Pull request event: 62
Fork event: 56

Last Year

Create event: 18
Release event: 4
Issues event: 49
Watch event: 452
Delete event: 10
Member event: 2
Issue comment event: 92
Push event: 108
Pull request review comment event: 31
Pull request review event: 55
Pull request event: 62
Fork event: 56

Committers

Last synced: 9 months ago

All Time

Total Commits: 3,750
Total Committers: 124
Avg Commits per committer: 30.242
Development Distribution Score (DDS): 0.701

Past Year

Commits: 36
Committers: 20
Avg Commits per committer: 1.8
Development Distribution Score (DDS): 0.778

Top Committers

Name	Email	Commits
Justin Terry	j**y@g**m	1,122
Ben Black	w**n@g**m	862
Jet	t**t@h**m	243
marioj	m**r@g**m	210
AnanthHari	h**2@g**m	164
Ryan Sullivan	r**s@g**m	153
Elliot Tower	e**t@e**m	128
Kyle Sang	s**e@g**m	85
Rodrigo de Lazcano	r**6@g**m	82
Will Dudley	1****y	50
Yashas Lokesh	y**h@g**m	40
niallwphd	n**w@c**u	37
Andrea PIERRÉ	a**e@b**u	36
lssr	s**s@g**m	33
Rohan138	r**8@g**m	27
Bolun Dai	b**5@n**u	24
RushivArora	r**a@g**m	22
Tianchen Liu	3****u	20
QiyaoWei	j**4@g**m	19
AnanthHari	A**i@g**m	19
Manuel Goulão	m**o@g**m	18
Ariel Kwiatkowski	a**i@g**m	18
Praveen Ravi	p**7@g**m	17
Ryan-Amaral	r**l@l**m	16
Paaras Bhandari	p**i@g**m	15
David Ackerman	1****n	13
Caroline Horsch	c**h@t**u	13
dsctt	d**1@g**m	11
ErikL97	6****7	11
Praveen Ravi	p**i@r**m	10
and 94 more...

Committer Domains (Top 20 + Academic)

proton.me: 1 sjtu.edu.cn: 1 wydmuch.poznan.pl: 1 uhlik.me: 1 florinpop.com: 1 cin.ufpe.br: 1 emanuelepetriglia.com: 1 jhuapl.edu: 1 alexyzhang.dev: 1 bolundembp.myfiosgateway.com: 1 bosch.com: 1 ucsd.edu: 1 gmx.at: 1 rachum.com: 1 davids-mbp.fios-router.home: 1 camao.one: 1 snu.ac.kr: 1 ad.umiacs.umd.edu: 1 gmai.com: 1 me.com: 1 ucl.ac.uk: 1 terpmail.umd.edu: 1 nyu.edu: 1 brown.edu: 1 cs.umd.edu: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 142
Total pull requests: 340
Average time to close issues: 3 months
Average time to close pull requests: 18 days
Total issue authors: 109
Total pull request authors: 62
Average comments per issue: 2.49
Average comments per pull request: 1.33
Merged pull requests: 249
Bot issues: 0
Bot pull requests: 2

Past Year

Issues: 39
Pull requests: 69
Average time to close issues: 29 days
Average time to close pull requests: 20 days
Issue authors: 25
Pull request authors: 17
Average comments per issue: 0.51
Average comments per pull request: 1.14
Merged pull requests: 43
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

dm-ackerman (10)
David-GERARD (8)
yjhan96 (3)
jjshoots (3)
jkterry1 (3)
WillDudley (3)
Kallinteris-Andreas (3)
xihuai18 (2)
elliottower (2)
matteobettini (2)
chrisyeh96 (2)
wpm (2)
kuds (2)
labanca (2)
NeoBerekov (1)

Pull Request Authors

elliottower (132)
dm-ackerman (38)
David-GERARD (20)
jjshoots (15)
nicku-a (10)
yjhan96 (10)
RedTachyon (6)
GiovanniGrotto (5)
BertrandDecoster (5)
pandyah5 (4)
Bamboofungus (4)
murtazarang (3)
mikepratt1 (3)
kuds (3)
Kallinteris-Andreas (3)

Top Labels

Issue Labels

bug (67) question (42) enhancement (23) documentation (2) help wanted (2) PettingZoo 2 (1) in progress (1) python (1)

Pull Request Labels

enhancement (27) bug (20) documentation (11) in progress (9) python (8) github_actions (6) dependencies (4) good first issue (2) PettingZoo 2 (1)

Packages

Total packages: 1
Total downloads:
- pypi 209,348 last-month
Total docker downloads: 24,427,098

Total dependent packages: 51
Total dependent repositories: 240
Total versions: 67
Total maintainers: 3

pypi.org: pettingzoo

Gymnasium for multi-agent reinforcement learning.

Homepage: https://farama.org
Documentation: https://pettingzoo.farama.org
License: MIT License
Latest release: 1.25.0
published 10 months ago

Versions: 67
Dependent Packages: 51
Dependent Repositories: 240
Downloads: 209,348 Last month
Docker Downloads: 24,427,098

Rankings

Dependent packages count: 0.4%

Dependent repos count: 1.0%

Downloads: 1.1%

Stargazers count: 1.6%

Average: 1.6%

Forks count: 2.8%

Docker downloads count: 2.9%

Maintainers (3)

jj_shoots jkterry pseudornd

Last synced: 6 months ago

Dependencies

.github/workflows/docs-test.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite

pyproject.toml pypi

gymnasium >=0.28.0
numpy >=1.21.0

setup.py pypi

tutorials/AgileRL/requirements.txt pypi

Pillow >=9.5.0
SuperSuit >=3.9.0
agilerl >=0.1.11
fastrand ==1.3.0
gymnasium >=0.28.1
imageio >=2.31.1
pettingzoo >=1.23.1
torch >=2.0.1

tutorials/CustomEnvironment/requirements.txt pypi

pettingzoo ==1.24.0

tutorials/LangChain/requirements.txt pypi

langchain *
openai *
pettingzoo *
tenacity *

tutorials/SB3/connect_four/requirements.txt pypi

pettingzoo >=1.24.0
sb3-contrib >=2.0.0
stable-baselines3 >=2.0.0

tutorials/SB3/kaz/requirements.txt pypi

pettingzoo >=1.24.0
stable-baselines3 >=2.0.0
supersuit >=3.9.0

tutorials/SB3/pistonball/requirements.txt pypi

pettingzoo >=1.24.0
stable-baselines3 >=2.0.0
supersuit >=3.9.0

tutorials/SB3/test/requirements.txt pypi

pettingzoo >=1.24.0 test
pytest * test
sb3-contrib >=2.0.0 test
stable-baselines3 >=2.0.0 test

tutorials/SB3/waterworld/requirements.txt pypi

pettingzoo >=1.24.0
pymunk *
stable-baselines3 >=2.0.0
supersuit >=3.9.0

.github/workflows/build-docs.yml actions

JamesIves/github-pages-deploy-action v4 composite
actions/checkout v3 composite
actions/setup-python v4 composite

.github/workflows/build-publish.yml actions

actions/checkout v3 composite
actions/download-artifact v2 composite
actions/setup-python v2 composite
actions/upload-artifact v2 composite
pypa/gh-action-pypi-publish release/v1 composite

.github/workflows/docs-manual-versioning.yml actions

JamesIves/github-pages-deploy-action v4 composite
actions/checkout v3 composite
actions/setup-python v4 composite

.github/workflows/docs-versioning.yml actions

JamesIves/github-pages-deploy-action v4 composite
actions/checkout v3 composite
actions/setup-python v4 composite
dawidd6/action-get-tag v1 composite

.github/workflows/linux-test.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite

.github/workflows/linux-tutorials-test.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite

.github/workflows/macos-test.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite

.github/workflows/pre-commit.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite

docs/requirements.txt pypi

furo *
myst-parser *
sphinx *

tutorials/CleanRL/requirements.txt pypi

SuperSuit ==3.6.0
pettingzoo ==1.22.3
torch ==1.13.1

tutorials/Ray/requirements.txt pypi

Pillow ==9.3.0
SuperSuit ==3.6.0
pettingzoo ==1.22.3
pickle5 ==0.0.11
ray ==2
torch ==1.13.1

tutorials/Tianshou/requirements.txt pypi

packaging ==21.3
pettingzoo ==1.22.3