# cooperativex/socialjax architecture

> Architecture diagram of the GitHub repository cooperativex/socialjax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cooperativex/socialjax
- Repository: https://github.com/cooperativex/socialjax

## Overview

##### Project Type and Purpose
- SocialJax is an open-source library and evaluation suite for multi-agent reinforcement learning in sequential social dilemmas, built on JAX.
- It provides:
– A _Core_ environment package (socialjax) with multiple scenarios (Coins, Harvest, Clean Up, Territory, Coop Mining, Mushrooms).
– Modular RL algorithm runners (IPPO, MAPPO, SVO) configurable via YAML.
– Evaluation pipelines and baseline policies.
– Performance benchmarking scripts (speed_test).

##### File Structure
Top-level directories:
- socialjax/
– environments/ (one folder per scenario, each with code + rendering)
– wrappers/ (Gymnax, Baselines, Transformers)
– registration.py (registry / factory for all envs)
– multi_agent_env.py (base class)
- algorithms/
– IPPO, MAPPO, SVO subfolders
– config/*.yaml (hyperparameters)
– algorithm runner scripts (.py)
- evaluation/ (post-training evaluation pipelines)
- fixed_policy/ (hard-coded baseline policies)
- speed_test/ (benchmark notebooks + scripts)
- checkpoints/ (model snapshots)
- docs/, .github/, environment.yml, pyproject.toml, requirements.txt

##### README Insights
- Describes “make('env_name')” factory interface (JaxMARL‐style).
- Shows training loops: PRNGKey splitting → env.step_env → obs/state/reward → algorithm update → checkpoint.
- Notes external stack: JAX, jaxlib (CUDA/CUDNN), Poetry/Conda setups, integration points with Gymnax & PettingZoo patterns.

##### Diagramming the Architecture
1) User / Researcher Code
2) Environment Factory & Registry (registration.py)
4) Wrapper Layer (Gymnax, Baselines, Transformers)
5) RL Algorithm Module (three subboxes: IPPO, MAPPO, SVO + YAML Configs)
6) Evaluation & Fixed Policies
7) Speed Test Harness
8) Checkpoint Storage
9) Documentation & CI (docs/, .github/)
10) External Dependencies (JAX, jaxlib, Numpy, Gymnax, PettingZoo)

– User Code → calls → Environment Factory → returns → Env Instance
– Env Instance ↔ step_env ↔ User/Algorithm Loop
– Algorithm Module ← loads ← YAML Configs
– Algorithm Loop → writes → Checkpoints
– Evaluation & Fixed Policies → reads → Checkpoints + Env → outputs → Metrics
– Speed Test → loads → Env → measures → Throughput
– CI Workflows → lint/test → Repo

c. Key Architectural Patterns:
- Registry / Factory for plugging in new environments via socialjax/registration.py.
- Modular algorithm directories with config‐driven behavior (YAML + runner).
- Wrapper pattern abstracts multiple backends (Gymnax, Baselines).
- Separation of concerns: core envs vs. algorithms vs. evaluation vs. benchmarks.

d. Technologies & Frameworks:
- JAX / jaxlib for GPU‐accelerated computation
- YAML for hyperparameter configs
- Poetry / Conda for environment management
- PyTorch‐style registry inspired by PettingZoo / Gymnax interfaces

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main flow
    User["User / Researcher"]:::external
    User -->|"calls"| Registration["Environment Factory & Registry"]:::core
    Registration -->|"returns"| EnvModule["Core Environments Module"]:::core
    EnvModule -->|"instantiates"| EnvInstance["Env Instance"]:::core
    EnvInstance -->|"step_env↔"| AlgorithmLoop["RL Algorithm Loop"]:::alg
    AlgorithmLoop -->|"writes"| Checkpoints["Checkpoint Storage"]:::pipeline
    AlgorithmLoop -->|"loads configs"| AlgConfig["YAML Configs"]:::config
    FixedEval["Evaluation & Fixed Policies"]:::pipeline
    FixedEval -->|"reads Checkpoints"| Checkpoints
    FixedEval -->|"reads Env"| EnvInstance
    FixedEval -->|"outputs"| Metrics["Metrics"]:::pipeline
    SpeedTest["Speed Test Harness"]:::pipeline
    SpeedTest -->|"loads Env"| EnvInstance
    SpeedTest -->|"measures"| Throughput["Throughput"]:::pipeline
    CI["CI Workflows"]:::support
    Docs["Documentation"]:::support
    CI -->|"runs on repo"| Repo["Project Repo"]:::support
    Docs --> Repo
    Repo["Project Repo"]:::support
    Repo -->|"contains"| EnvironmentYML["environment.yml"]:::config
    Repo -->|"contains"| PyProject["pyproject.toml"]:::config
    Repo -->|"contains"| Requirements["requirements.txt"]:::config

    subgraph "RL Algorithm Module"
        IPPO["IPPO"]:::alg
        MAPPO["MAPPO"]:::alg
        SVO["SVO"]:::alg
        AlgConfig
        IPPO --> AlgConfig
        MAPPO --> AlgConfig
        SVO --> AlgConfig
    end

    subgraph "Wrapper Layer"
        GymnaxWrapper["Gymnax Wrapper"]:::core
        BaselinesWrapper["Baselines Wrapper"]:::core
        TransformersWrapper["Transformers Wrapper"]:::core
    end
    EnvInstance --> GymnaxWrapper
    EnvInstance --> BaselinesWrapper
    EnvInstance --> TransformersWrapper

    %% Click events
    click Registration "https://github.com/cooperativex/socialjax/blob/main/socialjax/registration.py"
    click EnvModule "https://github.com/cooperativex/socialjax/tree/main/socialjax/environments/"
    click EnvInstance "https://github.com/cooperativex/socialjax/blob/main/socialjax/environments/multi_agent_env.py"
    click GymnaxWrapper "https://github.com/cooperativex/socialjax/blob/main/socialjax/wrappers/gymnax.py"
    click BaselinesWrapper "https://github.com/cooperativex/socialjax/blob/main/socialjax/wrappers/baselines.py"
    click TransformersWrapper "https://github.com/cooperativex/socialjax/blob/main/socialjax/wrappers/transformers.py"
    click IPPO "https://github.com/cooperativex/socialjax/tree/main/algorithms/IPPO/"
    click MAPPO "https://github.com/cooperativex/socialjax/tree/main/algorithms/MAPPO/"
    click SVO "https://github.com/cooperativex/socialjax/tree/main/algorithms/SVO/"
    click FixedEval "https://github.com/cooperativex/socialjax/tree/main/fixed_policy/"
    click Evaluation "https://github.com/cooperativex/socialjax/tree/main/evaluation/"
    click SpeedTest "https://github.com/cooperativex/socialjax/tree/main/speed_test/"
    click Checkpoints "https://github.com/cooperativex/socialjax/tree/main/checkpoints/"
    click Docs "https://github.com/cooperativex/socialjax/tree/main/docs/"
    click CI "https://github.com/cooperativex/socialjax/blob/main/.github/workflows/speet_example.yml"
    click EnvironmentYML "https://github.com/cooperativex/socialjax/blob/main/environment.yml"
    click PyProject "https://github.com/cooperativex/socialjax/blob/main/pyproject.toml"
    click Requirements "https://github.com/cooperativex/socialjax/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#006064,color:#006064
    classDef alg fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef pipeline fill:#FFFDE7,stroke:#F9A825,color:#F9A825
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#607D8B
    classDef support fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef config fill:#FFEBEE,stroke:#B71C1C,color:#B71C1C
```
