{"id":13935599,"url":"https://github.com/google-deepmind/meltingpot","last_synced_at":"2025-06-17T00:39:24.099Z","repository":{"id":37263189,"uuid":"386577599","full_name":"google-deepmind/meltingpot","owner":"google-deepmind","description":"A suite of test scenarios for multi-agent reinforcement learning.","archived":false,"fork":false,"pushed_at":"2025-05-23T19:30:54.000Z","size":211809,"stargazers_count":702,"open_issues_count":9,"forks_count":138,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-05-27T08:51:32.585Z","etag":null,"topics":["multiagent-reinforcement-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google-deepmind.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-16T09:12:01.000Z","updated_at":"2025-05-27T08:32:11.000Z","dependencies_parsed_at":"2023-09-07T20:34:58.998Z","dependency_job_id":"9738df9b-2391-481a-b2e9-618d63d1160d","html_url":"https://github.com/google-deepmind/meltingpot","commit_stats":{"total_commits":422,"total_committers":14,"mean_commits":"30.142857142857142","dds":0.3672985781990521,"last_synced_commit":"d6847dc65f580a552b808ee50764bc8ccce8c44c"},"previous_names":["google-deepmind/meltingpot","deepmind/meltingpot"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/google-deepmind/meltingpot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmeltingpot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmeltingpot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmeltingpot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmeltingpot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google-deepmind","download_url":"https://codeload.github.com/google-deepmind/meltingpot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmeltingpot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260268635,"owners_count":22983601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["multiagent-reinforcement-learning"],"created_at":"2024-08-07T23:01:55.197Z","updated_at":"2025-06-17T00:39:24.086Z","avatar_url":"https://github.com/google-deepmind.png","language":"Python","funding_links":[],"categories":["Python","Industry Strength Reinforcement Learning"],"sub_categories":[],"readme":"# Melting Pot\n\n*A suite of test scenarios for multi-agent reinforcement learning.*\n\n\u003c!-- linter off --\u003e\n\u003c!-- GITHUB --\u003e\n[![Python](https://img.shields.io/pypi/pyversions/dm-meltingpot.svg)](https://pypi.python.org/pypi/dm-meltingpot)\n[![PyPI version](https://img.shields.io/pypi/v/dm-meltingpot.svg)](https://pypi.python.org/pypi/dm-meltingpot)\n[![PyPI tests](../../actions/workflows/pypi-test.yml/badge.svg)](../../actions/workflows/pypi-test.yml)\n[![Tests](../../actions/workflows/test-meltingpot.yml/badge.svg)](../../actions/workflows/test-meltingpot.yml)\n[![Examples](../../actions/workflows/test-examples.yml/badge.svg)](../../actions/workflows/test-examples.yml)\n\u003c!-- /GITHUB --\u003e\n\u003c!-- linter on --\u003e\n\n\u003c!-- disableFinding(SNIPPET_INVALID_LANGUAGE) --\u003e\n\u003c!-- disableFinding(IMAGE_ALT_TEXT_INACCESSIBLE) --\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/google-deepmind/meltingpot/blob/main/docs/images/meltingpot_montage.gif?raw=true\"\n       alt=\"Melting Pot substrates\"\n       height=\"250\" width=\"250\" /\u003e\n\u003c/div\u003e\n\n[Melting Pot 2.0 Tech Report](https://arxiv.org/abs/2211.13746)\n[Melting Pot Contest at NeurIPS 2023](https://www.aicrowd.com/challenges/meltingpot-challenge-2023)\n\n## About\n\nMelting Pot assesses generalization to novel social situations involving both\nfamiliar and unfamiliar individuals, and has been designed to test a broad range\nof social interactions such as: cooperation, competition, deception,\nreciprocation, trust, stubbornness and so on. Melting Pot offers researchers a\nset of over 50 multi-agent reinforcement learning _substrates_ (multi-agent\ngames) on which to train agents, and over 256 unique test _scenarios_ on which\nto evaluate these trained agents. The performance of agents on these held-out\ntest scenarios quantifies whether agents:\n\n*   perform well across a range of social situations where individuals are\n    interdependent,\n*   interact effectively with unfamiliar individuals not seen during training\n\nThe resulting score can then be used to rank different multi-agent RL algorithms\nby their ability to generalize to novel social situations.\n\nWe hope Melting Pot will become a standard benchmark for multi-agent\nreinforcement learning. We plan to maintain it, and will be extending it in the\ncoming years to cover more social interactions and generalization scenarios.\n\nIf you are interested in extending Melting Pot, please refer to the\n[Extending Melting Pot](https://github.com/google-deepmind/meltingpot/blob/main/docs/extending.md) documentation.\n\n## Installation\n\n### `pip` install\n\n[Melting Pot is available on PyPI](https://pypi.python.org/pypi/dm-meltingpot)\nand can be installed using:\n\n```shell\npip install dm-meltingpot\n```\n\nNOTE: Melting Pot is built on top of [DeepMind Lab2D](https://github.com/google-deepmind/lab2d)\nwhich is distributed as pre-built wheels. If there is no appropriate wheel for\n`dmlab2d`, you will need to build it from source (see\n[the `dmlab2d` `README.md`](https://github.com/google-deepmind/lab2d/blob/main/README.md)\nfor details).\n\n### Manual install\n\nIf you want to work on the Melting Pot source code, you can perform an editable\ninstallation as follows:\n\n1.  Clone Melting Pot:\n\n    ```shell\n    git clone -b main https://github.com/google-deepmind/meltingpot\n    cd meltingpot\n    ```\n\n2.  (Optional) Activate a virtual environment, e.g.:\n\n    ```shell\n    python -m venv venv\n    source venv/bin/activate\n    ```\n\n3.  Install Melting Pot:\n\n    ```shell\n    pip install --editable .[dev]\n    ```\n\n4.  (Optional) Test the installation:\n\n    ```shell\n    pytest --pyargs meltingpot\n    ```\n\n### Devcontainer (x86 only)\n\n*NOTE: This Devcontainer only works for x86 platforms. For arm64 (newer M1 Macs)\nusers will have to follow the manual installation steps.*\n\nThis project includes a pre-configured development environment\n([devcontainer](https://containers.dev)).\n\nYou can launch a working development environment with one click, using e.g.\n[Github Codespaces](https://github.com/features/codespaces) or the\n[VSCode Containers](https://code.visualstudio.com/docs/remote/containers-tutorial)\nextension.\n\n#### CUDA support\n\nTo enable CUDA support (required for GPU training), make sure you have the\n[nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)\npackage installed, and then run Docker with the `---gpus all` flag enabled. Note\nthat for GitHub Codespaces this isn't necessary, as it's done for you\nautomatically.\n\n## Example usage\n\n### Evaluation\nThe [evaluation](https://github.com/google-deepmind/meltingpot/blob/main/meltingpot/utils/evaluation/evaluation.py) library can be used\nto evaluate [SavedModel](https://www.tensorflow.org/guide/saved_model)s\ntrained on Melting Pot substrates.\n\nEvaluation results from the [Melting Pot 2.0 Tech Report](https://arxiv.org/abs/2211.13746)\ncan be viewed in the [Evaluation Notebook](https://github.com/google-deepmind/meltingpot/blob/main/notebooks/evaluation_results.ipynb).\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/deepmind/meltingpot/blob/main/notebooks/evaluation_results.ipynb)\n\n### Interacting with the substrates\n\nYou can try out the substrates interactively with the\n[human_players](https://github.com/google-deepmind/meltingpot/blob/main/meltingpot/human_players) scripts. For example, to play\nthe `clean_up` substrate, you can run:\n\n```shell\npython meltingpot/human_players/play_clean_up.py\n```\n\nYou can move around with the `W`, `A`, `S`, `D` keys, Turn with `Q`, and `E`,\nfire the zapper with `1`, and fire the cleaning beam with `2`. You can switch\nbetween players with `TAB`. There are other substrates available in the\n[human_players](https://github.com/google-deepmind/meltingpot/blob/main/meltingpot/human_players) directory. Some have multiple\nvariants, which you select with the `--level_name` flag.\n\n### Training agents\n\nWe provide an illustrative example script using\n[RLlib](https://github.com/ray-project/ray). However, note\nthat Melting Pot is agnostic to how you train your agents, and this\nscript is not meant to be a suggestion for how to achieve a good score\nin the task suite. The authors of the suite never used this example training\nscript in their own work.\n\n#### RLlib\n\nThis example uses RLlib to train agents in\nself-play on a Melting Pot substrate.\n\nFirst you will need to install the dependencies needed by the examples:\n\n```shell\ncd \u003cmeltingpot_root\u003e\npip install -r examples/requirements.txt\n```\n\nThen you can run the training experiment using:\n\n```shell\ncd examples/rllib\npython self_play_train.py\n```\n\n## Documentation\n\nFull documentation is available [here](https://github.com/google-deepmind/meltingpot/blob/main/docs/index.md).\n\n## Citing Melting Pot\n\nIf you use Melting Pot in your work, please cite the accompanying articles:\n\n```bibtex\n@inproceedings{leibo2021meltingpot,\n    title={Scalable Evaluation of Multi-Agent Reinforcement Learning with\n           Melting Pot},\n    author={Joel Z. Leibo AND Edgar Du\\'e\\~nez-Guzm\\'an AND Alexander Sasha\n            Vezhnevets AND John P. Agapiou AND Peter Sunehag AND Raphael Koster\n            AND Jayd Matyas AND Charles Beattie AND Igor Mordatch AND Thore\n            Graepel},\n    year={2021},\n    journal={International conference on machine learning},\n    organization={PMLR},\n    url={https://doi.org/10.48550/arXiv.2107.06857},\n    doi={10.48550/arXiv.2107.06857}\n}\n```\n\n```bibtex\n@article{agapiou2022melting,\n  title={Melting Pot 2.0},\n  author={Agapiou, John P and Vezhnevets, Alexander Sasha and Du{\\'e}{\\~n}ez-Guzm{\\'a}n, Edgar A and Matyas, Jayd and Mao, Yiran and Sunehag, Peter and K{\\\"o}ster, Raphael and Madhushani, Udari and Kopparapu, Kavya and Comanescu, Ramona and Strouse, {DJ} and Johanson, Michael B and Singh, Sukhdeep and Haas, Julia and Mordatch, Igor and Mobbs, Dean and Leibo, Joel Z},\n  journal={arXiv preprint arXiv:2211.13746},\n  year={2022}\n}\n```\n\n## Disclaimer\n\nThis is not an officially supported Google product.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fmeltingpot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle-deepmind%2Fmeltingpot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fmeltingpot/lists"}