feat: readme revamp

docs/CONTRIBUTING.md

@@ -39,7 +39,7 @@ pre-commit run --all-files
 
 ## Naming Conventions
 ### Branch Names
-We name our feature and bugfix branches as follows - `feature/[BRANCH-NAME]`, `bugfix/[BRANCH-NAME]` or `maintenance/[BRANCH-NAME]`. Please ensure `[BRANCH-NAME]` is hyphen delimited.
+We name our feature and bugfix branches as follows - `feat/[BRANCH-NAME]`, `fix/[BRANCH-NAME]`. Please ensure `[BRANCH-NAME]` is hyphen delimited.
 ### Commit Messages
 We follow the conventional commits [standard](https://www.conventionalcommits.org/en/v1.0.0/).
 

docs/DETAILED_INSTALL.md

@@ -1,12 +1,11 @@
 # Detailed installation guide
 
 ### Conda virtual environment
-We recommend using `conda` for package management. These instructions should allow you to install and run mava.
+We recommend using [uv](https://docs.astral.sh/uv/) for package management. These instructions should allow you to install and run mava.
 
-1. Create and activate a virtual environment
+1. Install `uv`
 ```bash
-conda create -n mava python=3.12
-conda activate mava
+curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
 2. Clone mava
@@ -15,19 +14,22 @@ git clone https://github.com/instadeepai/Mava.git
 cd mava
 ```
 
-3. Install the dependencies
+3. Create and activate a virtual environment and install requirements
 ```bash
-pip install -e .
+uv venv -p=3.12
+source .venv/bin/activate
+uv pip install -e .
 ```
 
-4. Install jax on your accelerator. The example below is for an NVIDIA GPU, please the [official install guide](https://github.com/google/jax#installation) for other accelerators
+4. Install jax on your accelerator. The example below is for an NVIDIA GPU, please the [official install guide](https://github.com/google/jax#installation) for other accelerators.
+Note that the Jax version we use will change over time, please check the [requirements.txt](https://github.com/instadeepai/Mava/blob/develop/requirements/requirements.txt) for our latest tested Jax verion.
 ```bash
-pip install "jax[cuda12]==0.4.30"
+uv pip install "jax[cuda12]==0.4.30"
 ```
 
 5. Run a system!
 ```bash
-python mava/systems/ppo/ff_ippo.py env=rware
+python mava/systems/ppo/anakin/ff_ippo.py env=rware
 ```
 
 ### Docker

mava/systems/mat/README.md

@@ -0,0 +1,13 @@
+# Proximal Policy Optimization
+
+We provide the following four multi-agent extensions to [PPO](https://arxiv.org/pdf/1707.06347).
+* [ff-IPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/ff_ippo.py)
+* [ff-MAPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/ff_mappo.py)
+* [rec-IPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/rec_ippo.py)
+* [rec-MAPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/rec_mappo.py)
+
+In all cases IPPO implies that it is an implementation following the independent learners MARL paradigm while MAPPO implies that the implementation follows the centralised training with decentralised execution paradigm by having a centralised critic during training. The `ff` and `rec` in the system names implies that the policies are MLPs or have a [GRU](https://arxiv.org/pdf/1406.1078) memory module to help learning despite partial observability in the environment.
+
+## Relevant papers:
+* [Single agent Proximal Policy Optimization Algorithms](https://arxiv.org/pdf/1707.06347)
+* [The Surprising Effectiveness of PPO in Cooperative Multi-Agent Games](https://arxiv.org/pdf/2103.01955)

mava/systems/ppo/README.md

@@ -0,0 +1,13 @@
+# Proximal Policy Optimization
+
+We provide 4 implementations of multi-agent PPO.
+* [ff-IPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/ff_ippo.py): feed forward independant PPO
+* [ff-MAPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/ff_mappo.py): feed forward multi-agent PPO
+* [rec-IPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/rec_ippo.py): recurrent independant PPO
+* [rec-MAPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/rec_mappo.py): recurrent multi-agent PPO
+
+Where independant PPO uses independant learners and multi-agent PPO uses a CTDE style of training with a centralized critic.
+
+## Relevant papers:
+* [Single agent Proximal Policy Optimization Algorithms](https://arxiv.org/pdf/1707.06347)
+* [The Surprising Effectiveness of PPO in Cooperative Multi-Agent Games](https://arxiv.org/pdf/2103.01955)

mava/systems/q_learning/README.md

@@ -0,0 +1,10 @@
+# Q Learning
+
+We provide 2 Q-Learning based systems:
+* [rec-IQL](https://github.com/instadeepai/Mava/tree/feat/develop/mava/systems/q_learning/anakin/rec_iql.py): a multi-agent recurrent DQN implementation with double DQN.
+* [rec-QMIX](https://github.com/instadeepai/Mava/tree/feat/develop/mava/systems/q_learning/anakin/rec_qmix.py): an implementation of QMIX.
+
+## Relevant papers:
+* [Single agent DQN](https://arxiv.org/pdf/1312.5602)
+* [Multiagent Cooperation and Competition with Deep Reinforcement Learning](https://arxiv.org/pdf/1511.08779)
+* [QMIX](https://arxiv.org/pdf/1803.11485)

mava/systems/sable/README.md

@@ -0,0 +1,13 @@
+# Proximal Policy Optimization
+
+We provide 4 implementations of multi-agent PPO.
+* [ff-IPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/ff_ippo.py): feed forward independant PPO
+* [ff-MAPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/ff_mappo.py): feed forward multi-agent PPO
+* [rec-IPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/rec_ippo.py): recurrent independant PPO
+* [rec-MAPPO](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/ppo/anakin/rec_mappo.py): recurrent multi-agent PPO
+
+Where independant PPO uses independant learners and multi-agent PPO uses a CTDE style of training with a centralized critic.
+
+## Relevant papers:
+* [Single agent Proximal Policy Optimization Algorithms](https://arxiv.org/pdf/1707.06347)
+* [The Surprising Effectiveness of PPO in Cooperative Multi-Agent Games](https://arxiv.org/pdf/2103.01955)

mava/systems/sac/README.md

@@ -0,0 +1,14 @@
+# Soft Actor Critic
+
+We provide 3 implementations of multi-agent SAC.
+* [ff-ISAC](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/sac/anakin/ff_isac.py): feed forward independant SAC
+* [ff-MASAC](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/sac/anakin/ff_masac.py): feed forward multi-agent SAC
+* [ff-HASAC](https://github.com/instadeepai/Mava/blob/feat/develop/mava/systems/sac/anakin/ff_hasac.py): recurrent independant SAC
+
+Where independant SAC uses independant learners and multi-agent SAC uses a CTDE style of training with a centralized critic and HASAC uses heterogenous style, sequential updates.
+Note: independant SAC is included for completeness, however we find that it does not perform well.
+
+## Relevant papers
+* [Single agent Soft Actor Critic](https://arxiv.org/pdf/1801.01290)
+* [MADDPG](https://arxiv.org/pdf/1706.02275)
+* [HASAC](https://arxiv.org/pdf/2306.10715)