How cooperativex/socialjax works
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