<p align="center">
<a href="docs/img/matrax_logo.png">
<img src="docs/img/matrax_logo.png" alt="Matrax logo" width="50%"/>
</a>
</p>
<h2 align="center">
<p>Matrix Games in JAX</p>
</h2>
<p align="center">
<a href="https://www.python.org/doc/versions/">
<img src="https://img.shields.io/badge/python-3.9-blue" alt="Python Versions">
</a>
<a href="https://badge.fury.io/py/matrax">
<img src="https://badge.fury.io/py/matrax.svg" alt="PyPI version" height="18">
</a>
<a href="https://github.com/instadeepai/matrax/actions/workflows/tests_linters.yml">
<img src="https://github.com/instadeepai/matrax/actions/workflows/tests_linters.yml/badge.svg" alt="Tests">
</a>
<a href="https://github.com/psf/black">
<img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style">
</a>
<a href="http://mypy-lang.org/">
<img src="http://www.mypy-lang.org/static/mypy_badge.svg" alt="MyPy">
</a>
<a href="https://opensource.org/licenses/Apache-2.0">
<img src="https://img.shields.io/badge/License-Apache%202.0-orange.svg" alt="License">
</a>
</p>
## Enter the Matrax! 😎
<div align="center">
<h3>
[**Installation**](#installation-) | [**Quickstart**](#quickstart-)
</div>
**Matrax** is a lightweight suite of [2-player matrix game](https://en.wikipedia.org/wiki/Normal-form_game) environments written in [JAX](https://github.com/google/jax). It is a direct re-implementation of the matrix games provided in [this repository](https://github.com/uoe-agents/matrix-games) from the [AARG](https://agents.inf.ed.ac.uk/). It follows the [Jumanji](https://github.com/instadeepai/jumanji) RL environment suite API developed by [InstaDeep](https://www.instadeep.com/).
<h2 name="environments" id="environments">2-Player Matrix Games 🧑🤝🧑 </h2>
| Category | Shape (action space) | Registered Version(s) | Source |
|------------------------------------------|----------|------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| 🔻 Penalty Game | 3 x 3 | `Penalty-{k}-{state}-v0` | [code](https://github.com/instadeepai/matrax/blob/main/matrax/games/penalty.py) |
| 🧗♀️ Climbing Game | 3 x 3 | `Climbing-{state}-v0` | [code](https://github.com/instadeepai/matrax/blob/main/matrax/games/climbing.py) |
| 🤝 No-Conflict Games | 2 x 2 | `NoConflict-{id}-{state}-v0` | [code](https://github.com/instadeepai/matrax/blob/main/matrax/games/no_conflict.py) |
| 💣 Conflict Games | 2 x 2 | `Conflict-{id}-{state}-v0` | [code](https://github.com/instadeepai/matrax/blob/main/matrax/games/conflict.py) |
<h2 name="install" id="install">Installation 🎬</h2>
You can install the latest release of **Matrax** from PyPI:
```bash
pip install matrax
```
Alternatively, you can install the latest development version directly from GitHub:
```bash
pip install git+https://github.com/instadeepai/matrax.git
```
**Matrax** has been tested on Python 3.9.
Note that because the installation of JAX differs depending on your hardware accelerator,
we advise users to explicitly install the correct JAX version (see the
[official installation guide](https://github.com/google/jax#installation)).
<h2 name="quickstart" id="quickstart">Quickstart ⚡</h2>
```python
import jax
import matrax
# Instantiate a matrix game environment using the registry
env = matrax.make("Penalty-25-stateless-v0")
# Reset your (jit-able) environment
key = jax.random.PRNGKey(0)
state, timestep = jax.jit(env.reset)(key)
# Interact with the (jit-able) environment
action = env.action_spec.generate_value() # Action selection (dummy value here)
state, timestep = jax.jit(env.step)(state, action) # Take a step and observe the next state and time step
```
### Registry and Versioning 📖
Like Jumanji, **Matrax** keeps a strict versioning of its environments for reproducibility reasons.
We maintain a registry of standard environments with their configuration.
For each environment, a version suffix is appended, e.g. `EnvironmentName-v1`.
When changes are made to environments that might impact learning results,
the version number is incremented by one to prevent potential confusion.
## Citing Matrax 📝
If you use any of the environment implementations in Matrax please consider citing this library.
```
@software{matrax2023github,
author = {Arnu Pretorius},
title = {Matrax: Matrix Games in JAX},
url = {http://github.com/instadeepai/matrax},
version = {v0.0.4-alpha},
year = {2023},
}
```
## See Also 🔎
Other works have embraced the approach of writing RL environments in JAX.
In particular, we suggest users check out the following sister repositories:
- 🌴 [Jumanji](https://github.com/instadeepai/jumanji) is a diverse suite of scalable reinforcement learning environments.
- 🦾 [Brax](https://github.com/google/brax) is a differentiable physics engine that simulates
environments made up of rigid bodies, joints, and actuators.
- 🏋️ [Gymnax](https://github.com/RobertTLange/gymnax) implements classic environments including
classic control, bsuite, MinAtar and a collection of meta RL tasks.
- 🎲 [Pgx](https://github.com/sotetsuk/pgx) provides classic board game environments like
Backgammon, Shogi, and Go.
Raw data
{
"_id": null,
"home_page": "https://github.com/instadeepai/matrax/",
"name": "matrax",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "matrix-games python jax",
"author": "InstaDeep",
"author_email": "a.pretorius@instadeep.com",
"download_url": "https://files.pythonhosted.org/packages/f6/64/c4fc3d8a7c737facd8d589a9b61e0a10868735325433f1cc1fb4c68bbe18/matrax-0.0.5.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"docs/img/matrax_logo.png\">\n <img src=\"docs/img/matrax_logo.png\" alt=\"Matrax logo\" width=\"50%\"/>\n </a>\n</p>\n\n<h2 align=\"center\">\n <p>Matrix Games in JAX</p>\n</h2>\n<p align=\"center\">\n <a href=\"https://www.python.org/doc/versions/\">\n <img src=\"https://img.shields.io/badge/python-3.9-blue\" alt=\"Python Versions\">\n </a>\n <a href=\"https://badge.fury.io/py/matrax\">\n <img src=\"https://badge.fury.io/py/matrax.svg\" alt=\"PyPI version\" height=\"18\">\n </a>\n <a href=\"https://github.com/instadeepai/matrax/actions/workflows/tests_linters.yml\">\n <img src=\"https://github.com/instadeepai/matrax/actions/workflows/tests_linters.yml/badge.svg\" alt=\"Tests\">\n </a>\n <a href=\"https://github.com/psf/black\">\n <img src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"Code Style\">\n </a>\n <a href=\"http://mypy-lang.org/\">\n <img src=\"http://www.mypy-lang.org/static/mypy_badge.svg\" alt=\"MyPy\">\n </a>\n <a href=\"https://opensource.org/licenses/Apache-2.0\">\n <img src=\"https://img.shields.io/badge/License-Apache%202.0-orange.svg\" alt=\"License\">\n </a>\n</p>\n\n## Enter the Matrax! \ud83d\ude0e\n\n<div align=\"center\">\n<h3>\n\n[**Installation**](#installation-) | [**Quickstart**](#quickstart-)\n\n</div>\n\n**Matrax** is a lightweight suite of [2-player matrix game](https://en.wikipedia.org/wiki/Normal-form_game) environments written in [JAX](https://github.com/google/jax). It is a direct re-implementation of the matrix games provided in [this repository](https://github.com/uoe-agents/matrix-games) from the [AARG](https://agents.inf.ed.ac.uk/). It follows the [Jumanji](https://github.com/instadeepai/jumanji) RL environment suite API developed by [InstaDeep](https://www.instadeep.com/).\n\n<h2 name=\"environments\" id=\"environments\">2-Player Matrix Games \ud83e\uddd1\u200d\ud83e\udd1d\u200d\ud83e\uddd1 </h2>\n\n| Category | Shape (action space) | Registered Version(s) | Source |\n|------------------------------------------|----------|------------------------------------------------------|--------------------------------------------------------------------------------------------------|\n| \ud83d\udd3b Penalty Game | 3 x 3 | `Penalty-{k}-{state}-v0` | [code](https://github.com/instadeepai/matrax/blob/main/matrax/games/penalty.py) |\n| \ud83e\uddd7\u200d\u2640\ufe0f Climbing Game | 3 x 3 | `Climbing-{state}-v0` | [code](https://github.com/instadeepai/matrax/blob/main/matrax/games/climbing.py) |\n| \ud83e\udd1d No-Conflict Games | 2 x 2 | `NoConflict-{id}-{state}-v0` | [code](https://github.com/instadeepai/matrax/blob/main/matrax/games/no_conflict.py) |\n| \ud83d\udca3 Conflict Games | 2 x 2 | `Conflict-{id}-{state}-v0` | [code](https://github.com/instadeepai/matrax/blob/main/matrax/games/conflict.py) |\n\n<h2 name=\"install\" id=\"install\">Installation \ud83c\udfac</h2>\n\nYou can install the latest release of **Matrax** from PyPI:\n\n```bash\npip install matrax\n```\n\nAlternatively, you can install the latest development version directly from GitHub:\n\n```bash\npip install git+https://github.com/instadeepai/matrax.git\n```\n\n**Matrax** has been tested on Python 3.9.\nNote that because the installation of JAX differs depending on your hardware accelerator,\nwe advise users to explicitly install the correct JAX version (see the\n[official installation guide](https://github.com/google/jax#installation)).\n\n<h2 name=\"quickstart\" id=\"quickstart\">Quickstart \u26a1</h2>\n\n```python\nimport jax\nimport matrax\n\n# Instantiate a matrix game environment using the registry\nenv = matrax.make(\"Penalty-25-stateless-v0\")\n\n# Reset your (jit-able) environment\nkey = jax.random.PRNGKey(0)\nstate, timestep = jax.jit(env.reset)(key)\n\n# Interact with the (jit-able) environment\naction = env.action_spec.generate_value() # Action selection (dummy value here)\nstate, timestep = jax.jit(env.step)(state, action) # Take a step and observe the next state and time step\n```\n\n### Registry and Versioning \ud83d\udcd6\n\nLike Jumanji, **Matrax** keeps a strict versioning of its environments for reproducibility reasons.\nWe maintain a registry of standard environments with their configuration.\nFor each environment, a version suffix is appended, e.g. `EnvironmentName-v1`.\nWhen changes are made to environments that might impact learning results,\nthe version number is incremented by one to prevent potential confusion.\n\n## Citing Matrax \ud83d\udcdd\n\nIf you use any of the environment implementations in Matrax please consider citing this library.\n\n```\n@software{matrax2023github,\n author = {Arnu Pretorius},\n title = {Matrax: Matrix Games in JAX},\n url = {http://github.com/instadeepai/matrax},\n version = {v0.0.4-alpha},\n year = {2023},\n}\n```\n\n## See Also \ud83d\udd0e\n\nOther works have embraced the approach of writing RL environments in JAX.\nIn particular, we suggest users check out the following sister repositories:\n\n- \ud83c\udf34 [Jumanji](https://github.com/instadeepai/jumanji) is a diverse suite of scalable reinforcement learning environments.\n- \ud83e\uddbe [Brax](https://github.com/google/brax) is a differentiable physics engine that simulates\nenvironments made up of rigid bodies, joints, and actuators.\n- \ud83c\udfcb\ufe0f\u200d [Gymnax](https://github.com/RobertTLange/gymnax) implements classic environments including\nclassic control, bsuite, MinAtar and a collection of meta RL tasks.\n- \ud83c\udfb2 [Pgx](https://github.com/sotetsuk/pgx) provides classic board game environments like\nBackgammon, Shogi, and Go.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Matrix games in JAX",
"version": "0.0.5",
"project_urls": {
"Homepage": "https://github.com/instadeepai/matrax/"
},
"split_keywords": [
"matrix-games",
"python",
"jax"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e093b11ca9f0da688a6ff957e7d94367d83c765bc0277671ce3878d924c7668",
"md5": "ce8df70d3a0ddd2496a64d258a684519",
"sha256": "5f97837d2b104fb4766b180b980c5202c0791cd38db7ce12066c51048f0b88bb"
},
"downloads": -1,
"filename": "matrax-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ce8df70d3a0ddd2496a64d258a684519",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18290,
"upload_time": "2024-11-28T09:02:42",
"upload_time_iso_8601": "2024-11-28T09:02:42.356777Z",
"url": "https://files.pythonhosted.org/packages/0e/09/3b11ca9f0da688a6ff957e7d94367d83c765bc0277671ce3878d924c7668/matrax-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f664c4fc3d8a7c737facd8d589a9b61e0a10868735325433f1cc1fb4c68bbe18",
"md5": "35135dabd8b54253a05a98411695e88b",
"sha256": "1eac133220775afdddc8eb06431c65318a57cf3eb437470afe70fcb3a10accbc"
},
"downloads": -1,
"filename": "matrax-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "35135dabd8b54253a05a98411695e88b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16808,
"upload_time": "2024-11-28T09:02:43",
"upload_time_iso_8601": "2024-11-28T09:02:43.722718Z",
"url": "https://files.pythonhosted.org/packages/f6/64/c4fc3d8a7c737facd8d589a9b61e0a10868735325433f1cc1fb4c68bbe18/matrax-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-28 09:02:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "instadeepai",
"github_project": "matrax",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "matrax"
}
JSON
