# instadeepai/mava architecture

> Architecture diagram of the GitHub repository instadeepai/mava, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/instadeepai/mava
- Repository: https://github.com/instadeepai/mava

## Overview

Mava is a JAX framework for distributed multi-agent reinforcement-learning research. Researchers launch a configured algorithm; its training loop interacts with wrapped environments, collects experience, updates policy/value networks, and evaluates and logs results. The repository supports multiple algorithm families and both Anakin and Sebulba execution architectures. The sampled code confirms environment construction, Sebulba actor-to-learner queues, and evaluation/logging behavior; several other subsystem connections are documented capabilities rather than inspected call sites.

Main entry points: [`mava/systems/ppo`](https://github.com/instadeepai/mava/tree/develop/mava/systems/ppo) (PPO variants), [`mava/systems/ppo/sebulba/rec_mappo.py`](https://github.com/instadeepai/mava/blob/develop/mava/systems/ppo/sebulba/rec_mappo.py) (Sebulba training), [`mava/systems/ppo/anakin/rec_mappo.py`](https://github.com/instadeepai/mava/blob/develop/mava/systems/ppo/anakin/rec_mappo.py) (Anakin training), [`mava/utils/make_env.py`](https://github.com/instadeepai/mava/blob/develop/mava/utils/make_env.py) (Environment factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_algorithms["MARL algorithms"]
  node_ppo["PPO variants"]
  node_qlearning["Q-learning variants"]
  node_sac["SAC variants"]
  node_mat["MAT"]
  node_sable["Sable and GPO"]
end

subgraph group_environments["Environment interface"]
  node_envfactory["Environment factory<br/>[make_env.py]"]
  node_envwrappers["Environment wrappers"]
  node_externalenvs["JAX MARL environments"]
end

subgraph group_networks["Policy networks"]
  node_networkmodules["Network modules"]
  node_sablemodel["Sable network<br/>[sable_network.py]"]
end

subgraph group_runtime["Training runtime"]
  node_anakin["Anakin training<br/>[rec_mappo.py]"]
  node_sebulba["Sebulba training<br/>[rec_mappo.py]"]
  node_pipeline["Rollout pipeline<br/>[pipelines.py]"]
  node_trainingutils["Training utilities<br/>[training.py]"]
end

subgraph group_results["Evaluation and results"]
  node_evaluator["Evaluator<br/>[evaluator.py]"]
  node_logger["Experiment logger<br/>[logger.py]"]
  node_checkpointing["Checkpointing<br/>[checkpointing.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"launches"| node_ppo
node_researcher -->|"launches"| node_qlearning
node_researcher -->|"launches"| node_sac
node_researcher -->|"launches"| node_mat
node_researcher -->|"launches"| node_sable
node_ppo -->|"constructs environments"| node_envfactory
node_envfactory -->|"applies wrappers"| node_envwrappers
node_envfactory -->|"creates environments"| node_externalenvs
node_ppo -->|"uses networks"| node_networkmodules
node_sable -->|"uses network"| node_sablemodel
node_ppo -->|"runs Anakin"| node_anakin
node_ppo -->|"runs Sebulba"| node_sebulba
node_sebulba -->|"transfers rollouts"| node_pipeline
node_sebulba -->|"constructs environments"| node_envfactory
node_sebulba -->|"evaluates policy"| node_evaluator
node_sebulba -->|"logs metrics"| node_logger
node_anakin -->|"constructs environments"| node_envfactory
node_anakin -->|"evaluates policy"| node_evaluator
node_anakin -->|"logs metrics"| node_logger
node_anakin -->|"uses utilities"| node_trainingutils
node_sebulba -->|"uses utilities"| node_trainingutils
node_ppo -.->|"saves state"| node_checkpointing

click node_ppo "https://github.com/instadeepai/mava/tree/develop/mava/systems/ppo"
click node_qlearning "https://github.com/instadeepai/mava/tree/develop/mava/systems/q_learning"
click node_sac "https://github.com/instadeepai/mava/tree/develop/mava/systems/sac"
click node_mat "https://github.com/instadeepai/mava/tree/develop/mava/systems/mat"
click node_sable "https://github.com/instadeepai/mava/tree/develop/mava/systems/sable"
click node_envfactory "https://github.com/instadeepai/mava/blob/develop/mava/utils/make_env.py"
click node_envwrappers "https://github.com/instadeepai/mava/tree/develop/mava/wrappers"
click node_networkmodules "https://github.com/instadeepai/mava/tree/develop/mava/networks"
click node_sablemodel "https://github.com/instadeepai/mava/blob/develop/mava/networks/sable_network.py"
click node_anakin "https://github.com/instadeepai/mava/blob/develop/mava/systems/ppo/anakin/rec_mappo.py"
click node_sebulba "https://github.com/instadeepai/mava/blob/develop/mava/systems/ppo/sebulba/rec_mappo.py"
click node_pipeline "https://github.com/instadeepai/mava/blob/develop/mava/utils/sebulba/pipelines.py"
click node_trainingutils "https://github.com/instadeepai/mava/blob/develop/mava/utils/training.py"
click node_evaluator "https://github.com/instadeepai/mava/blob/develop/mava/evaluator.py"
click node_logger "https://github.com/instadeepai/mava/blob/develop/mava/utils/logger.py"
click node_checkpointing "https://github.com/instadeepai/mava/blob/develop/mava/utils/checkpointing.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ppo,node_qlearning,node_sac,node_mat,node_sable toneBlue
class node_envfactory,node_envwrappers,node_externalenvs toneAmber
class node_networkmodules,node_sablemodel toneMint
class node_anakin,node_sebulba,node_pipeline,node_trainingutils toneRose
class node_evaluator,node_logger,node_checkpointing,node_researcher toneIndigo
```

## Components

### MARL algorithms

- [PPO variants](https://github.com/instadeepai/mava/tree/develop/mava/systems/ppo): `mava/systems/ppo`
- [Q-learning variants](https://github.com/instadeepai/mava/tree/develop/mava/systems/q_learning): `mava/systems/q_learning`
- [SAC variants](https://github.com/instadeepai/mava/tree/develop/mava/systems/sac): `mava/systems/sac`
- [MAT](https://github.com/instadeepai/mava/tree/develop/mava/systems/mat): `mava/systems/mat`
- [Sable and GPO](https://github.com/instadeepai/mava/tree/develop/mava/systems/sable): `mava/systems/sable`

### Environment interface

- [Environment factory](https://github.com/instadeepai/mava/blob/develop/mava/utils/make_env.py): `mava/utils/make_env.py`
- [Environment wrappers](https://github.com/instadeepai/mava/tree/develop/mava/wrappers): `mava/wrappers`
- **JAX MARL environments**

### Policy networks

- [Network modules](https://github.com/instadeepai/mava/tree/develop/mava/networks): `mava/networks`
- [Sable network](https://github.com/instadeepai/mava/blob/develop/mava/networks/sable_network.py): `mava/networks/sable_network.py`

### Training runtime

- [Anakin training](https://github.com/instadeepai/mava/blob/develop/mava/systems/ppo/anakin/rec_mappo.py): `mava/systems/ppo/anakin/rec_mappo.py`
- [Sebulba training](https://github.com/instadeepai/mava/blob/develop/mava/systems/ppo/sebulba/rec_mappo.py): `mava/systems/ppo/sebulba/rec_mappo.py`
- [Rollout pipeline](https://github.com/instadeepai/mava/blob/develop/mava/utils/sebulba/pipelines.py): `mava/utils/sebulba/pipelines.py`
- [Training utilities](https://github.com/instadeepai/mava/blob/develop/mava/utils/training.py): `mava/utils/training.py`

### Evaluation and results

- [Evaluator](https://github.com/instadeepai/mava/blob/develop/mava/evaluator.py): `mava/evaluator.py`
- [Experiment logger](https://github.com/instadeepai/mava/blob/develop/mava/utils/logger.py): `mava/utils/logger.py`
- [Checkpointing](https://github.com/instadeepai/mava/blob/develop/mava/utils/checkpointing.py): `mava/utils/checkpointing.py`

### Other components

- **Researcher**

## Connections

- Researcher → PPO variants: launches
- Researcher → Q-learning variants: launches
- Researcher → SAC variants: launches
- Researcher → MAT: launches
- Researcher → Sable and GPO: launches
- PPO variants → Environment factory: constructs environments
- Environment factory → Environment wrappers: applies wrappers
- Environment factory → JAX MARL environments: creates environments
- PPO variants → Network modules: uses networks
- Sable and GPO → Sable network: uses network
- PPO variants → Anakin training: runs Anakin
- PPO variants → Sebulba training: runs Sebulba
- Sebulba training → Rollout pipeline: transfers rollouts
- Sebulba training → Environment factory: constructs environments
- Sebulba training → Evaluator: evaluates policy
- Sebulba training → Experiment logger: logs metrics
- Anakin training → Environment factory: constructs environments
- Anakin training → Evaluator: evaluates policy
- Anakin training → Experiment logger: logs metrics
- Anakin training → Training utilities: uses utilities
- Sebulba training → Training utilities: uses utilities
- PPO variants → Checkpointing: saves state