# alanmac07/marl-aquarium architecture

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

- Interactive diagram: https://gitdiagram.com/alanmac07/marl-aquarium
- Repository: https://github.com/alanmac07/marl-aquarium

## Overview

Aquarium is a PettingZoo-compatible multi-agent predator–prey simulation for reinforcement-learning experiments. The main workflow is to create the wrapped environment, let an agent choose actions from observations, advance the simulation, and obtain rewards, termination status, and rendered frames. The environment also exposes configurable population dynamics, field of view, toroidal-world behavior, and visual debugging options. The environment source is partial, so some internal stage boundaries are modeled from documented behavior; unsampled implementation details and unverified links are omitted.

Main entry points: [`marl_aquarium/env/aquarium.py`](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/aquarium.py) (Aquarium runtime), [`marl_aquarium/env/view.py`](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/view.py) (Aquarium view), [`marl_aquarium/env/vector.py`](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/vector.py) (Vector math), [`marl_aquarium/env/prey.py`](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/prey.py) (Prey entities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Environment API"]
  node_factory["Environment factory<br/>[aquarium_v0.py]"]
end

subgraph group_simulation["Simulation"]
  node_sim["Aquarium runtime<br/>[aquarium.py]"]
  node_observations["Observations<br/>[aquarium.py]"]
  node_actions["Action dynamics<br/>[aquarium.py]"]
  node_rewards["Rewards and outcomes<br/>[aquarium.py]"]
end

subgraph group_domain["Entities and Geometry"]
  node_prey["Prey entities<br/>[prey.py]"]
  node_predator["Predator entities<br/>[predator.py]"]
  node_entity["Entity base<br/>[entity.py]"]
  node_geometry["Torus utilities<br/>[utils.py]"]
  node_vector["Vector math<br/>[vector.py]"]
end

subgraph group_rendering["Rendering"]
  node_view["Aquarium view<br/>[view.py]"]
end

node_user(("Environment user"))
node_policy(("Agent policy"))
node_pygame["Pygame"]

node_user -->|"creates environment"| node_factory
node_factory -->|"configures runtime"| node_sim
node_user -->|"steps and resets"| node_sim
node_policy -->|"supplies actions"| node_sim
node_sim -->|"provides observations"| node_observations
node_sim -->|"returns rewards"| node_rewards
node_sim -->|"advances simulation"| node_actions
node_sim -->|"creates prey"| node_prey
node_sim -->|"creates predators"| node_predator
node_sim -->|"uses torus helpers"| node_geometry
node_sim -->|"uses vector math"| node_vector
node_sim -->|"renders frames"| node_view
node_prey -->|"inherits from"| node_entity
node_predator -->|"inherits from"| node_entity
node_entity -->|"uses vectors"| node_vector
node_prey -->|"uses vectors"| node_vector
node_predator -->|"uses vectors"| node_vector
node_geometry -->|"uses vectors"| node_vector
node_view -->|"draws with"| node_pygame
node_view -->|"uses helpers"| node_geometry
node_view -->|"draws entities"| node_entity
node_view -->|"draws prey"| node_prey
node_view -->|"draws predators"| node_predator
node_view -->|"uses vectors"| node_vector
node_user -->|"requests rendering"| node_view

click node_factory "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/aquarium_v0.py"
click node_sim "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/aquarium.py"
click node_observations "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/aquarium.py"
click node_actions "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/aquarium.py"
click node_rewards "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/aquarium.py"
click node_prey "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/prey.py"
click node_predator "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/predator.py"
click node_entity "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/entity.py"
click node_geometry "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/utils.py"
click node_vector "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/vector.py"
click node_view "https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/view.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_factory,node_user toneBlue
class node_sim,node_observations,node_actions,node_rewards toneAmber
class node_prey,node_predator,node_entity,node_geometry,node_vector toneMint
class node_view toneRose
class node_policy,node_pygame toneIndigo
```

## Components

### Environment API

- [Environment factory](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/aquarium_v0.py): `marl_aquarium/aquarium_v0.py`

### Simulation

- [Aquarium runtime](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/aquarium.py): `marl_aquarium/env/aquarium.py`
- [Observations](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/aquarium.py): `marl_aquarium/env/aquarium.py`
- [Action dynamics](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/aquarium.py): `marl_aquarium/env/aquarium.py`
- [Rewards and outcomes](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/aquarium.py): `marl_aquarium/env/aquarium.py`

### Entities and Geometry

- [Prey entities](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/prey.py): `marl_aquarium/env/prey.py`
- [Predator entities](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/predator.py): `marl_aquarium/env/predator.py`
- [Entity base](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/entity.py): `marl_aquarium/env/entity.py`
- [Torus utilities](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/utils.py): `marl_aquarium/env/utils.py`
- [Vector math](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/vector.py): `marl_aquarium/env/vector.py`

### Rendering

- [Aquarium view](https://github.com/alanmac07/marl-aquarium/blob/main/marl_aquarium/env/view.py): `marl_aquarium/env/view.py`

### Other components

- **Environment user**
- **Agent policy**
- **Pygame**

## Connections

- Environment user → Environment factory: creates environment (evidence: `README.md`)
- Environment factory → Aquarium runtime: configures runtime (evidence: `marl_aquarium/aquarium_v0.py`)
- Environment user → Aquarium runtime: steps and resets (evidence: `README.md`)
- Agent policy → Aquarium runtime: supplies actions (evidence: `README.md`)
- Aquarium runtime → Observations: provides observations (evidence: `README.md`)
- Aquarium runtime → Rewards and outcomes: returns rewards (evidence: `README.md`)
- Aquarium runtime → Action dynamics: advances simulation (evidence: `marl_aquarium/env/aquarium.py`)
- Aquarium runtime → Prey entities: creates prey (evidence: `marl_aquarium/env/aquarium.py`)
- Aquarium runtime → Predator entities: creates predators (evidence: `marl_aquarium/env/aquarium.py`)
- Aquarium runtime → Torus utilities: uses torus helpers (evidence: `marl_aquarium/env/aquarium.py`)
- Aquarium runtime → Vector math: uses vector math (evidence: `marl_aquarium/env/aquarium.py`)
- Aquarium runtime → Aquarium view: renders frames (evidence: `marl_aquarium/env/aquarium.py`)
- Prey entities → Entity base: inherits from (evidence: `marl_aquarium/env/prey.py`)
- Predator entities → Entity base: inherits from (evidence: `marl_aquarium/env/predator.py`)
- Entity base → Vector math: uses vectors (evidence: `marl_aquarium/env/entity.py`)
- Prey entities → Vector math: uses vectors (evidence: `marl_aquarium/env/prey.py`)
- Predator entities → Vector math: uses vectors (evidence: `marl_aquarium/env/predator.py`)
- Torus utilities → Vector math: uses vectors (evidence: `marl_aquarium/env/utils.py`)
- Aquarium view → Pygame: draws with (evidence: `marl_aquarium/env/view.py`)
- Aquarium view → Torus utilities: uses helpers (evidence: `marl_aquarium/env/view.py`)
- Aquarium view → Entity base: draws entities (evidence: `marl_aquarium/env/view.py`)
- Aquarium view → Prey entities: draws prey (evidence: `marl_aquarium/env/view.py`)
- Aquarium view → Predator entities: draws predators (evidence: `marl_aquarium/env/view.py`)
- Aquarium view → Vector math: uses vectors (evidence: `marl_aquarium/env/view.py`)
- Environment user → Aquarium view: requests rendering (evidence: `README.md`)
