GAMA-PettingZoo

GAMA-PettingZoo is a generic PettingZoo environment that enables the integration of simulations from the GAMA modeling platform with multi-agent reinforcement learning algorithms.

🎯 Purpose

This library allows researchers and developers to easily use GAMA models as multi-agent reinforcement learning environments, leveraging the power of GAMA for agent-based modeling and the Python ecosystem for AI.

⚡ Quick Start

Installation

pip install gama-pettingzoo

Prerequisites

• GAMA Platform: Install GAMA from gama-platform.org
• Python 3.10 – 3.12 (see the compatibility note below)

⚠️ Supported Python versions: 3.10 to 3.12.

The upper bound comes from PettingZoo itself, not from this library: PettingZoo 1.25.0 declares requires-python = ">=3.9,<3.13", so Python 3.13 and above cannot work — installing on 3.13+ or 3.14 fails or leaves you with a broken dependency set.

The lower bound comes from the dependency chain: gama-client (≥2.0.0), gymnasium and torch all require Python ≥ 3.10, and recent NumPy (≥2.4) requires ≥ 3.11.

Tested on Python 3.11 with gama-client 2.0.1, PettingZoo 1.25.0, gymnasium 1.2.3.

package	constraint
pettingzoo 1.25.0	>=3.9,<3.13 ← sets the ceiling
gymnasium 1.2.3	>=3.10
gama-client 2.0.1	>=3.10
numpy 2.4	>=3.11

pip install pettingzoo gama-gymnasium numpy

Basic Usage

from gama_pettingzoo.gama_parallel_env import GamaParallelEnv

# Create the environment
env = GamaParallelEnv(
    gaml_experiment_path='your_model.gaml',
    gaml_experiment_name='main',
    gama_ip_address='localhost',
    gama_port=1001
)

# Use as a standard PettingZoo environment
observations, infos = env.reset()
for agent in env.agent_iter():
    observation, reward, termination, truncation, info = env.last()
    action = policy(observation, agent)  # Your policy
    env.step(action)

GamaMultiAgent

The GamaMultiAgent is a GAMA agent required in the model to enable interaction between the simulation's learning agents and the PettingZoo environment. It has specialized variables and actions for multi-agent management.

Structure of the agent:

species GamaMultiAgent {
    map<string, unknown> action_spaces;
    map<string, unknown> observation_spaces;
    list<string> agents_list;

    map<string, unknown> states;
    map<string, float> rewards;
    map<string, bool> terminated;
    map<string, bool> truncated;
    map<string, unknown> infos;

    map<string, unknown> next_actions;
    map<string, unknown> data;

    action update_data {
        data <- [
            "States"::states,
            "Rewards"::rewards,
            "Terminated"::terminated,
            "Truncated"::truncated,
            "Infos"::infos,
            "Agents"::agents_list
        ];
    }
}

GAMA Configuration

1. Add the GAMA component to your model: Make sure you have added the species GamaMultiAgent described above to your model:

   species GamaMultiAgent;
   

   Set up the action_spaces and observation_spaces:

   global {
       init {
           create GamaMultiAgent {
               agents_list <- ["prisoner", "guard"];
               action_spaces <- [
                   "prisoner"::["type"::"Discrete", "n"::4],
                   "guard"::["type"::"Discrete", "n"::4]
               ];
               observation_spaces <- [
                   "prisoner"::["type"::"Box", "low"::0, "high"::grid_size, "shape"::[2], "dtype"::"int"],
                   "guard"::["type"::"Box", "low"::0, "high"::grid_size, "shape"::[2], "dtype"::"int"]
               ];
           }
       }
   }
   

   Update the multi-agent's data after actions are completed:

   ask GamaMultiAgent[0] {
       do update_data;
   }
   

2. Launch GAMA in server mode:

# Linux/MacOS
./gama-headless.sh -socket 1001

# Windows
gama-headless.bat -socket 1001

📁 Project Structure

gama-pettingzoo/
├── 📁 src/                    # Main Python package source code
├── 📁 tests/                  # Comprehensive test suite
├── 📁 examples/               # Complete examples and tutorials
│   ├── 📁 Moving Exemple/     # Basic movement example
│   ├── 📁 Pac Man/           # Multi-agent Pac-Man game
│   └── 📁 Prison Escape/     # Prison escape environment
├── 📁 improved_trained_models/ # Advanced trained models
├── 📁 simple_trained_models/   # Basic trained models
├── pyproject.toml             # Python package configuration
├── pytest.ini                # Testing configuration
├── LICENSE                    # Package license
└── README.md                  # This documentation

📚 Documentation and Examples

🚀 Tutorials and Examples

📖 Detailed Guides

• Moving Exemple Guide: Complete tutorial for creating your first multi-agent environment
• Prison Escape Guide: Escape environment with antagonist agents
• Source Code Documentation: Technical documentation of the package structure
• Testing Guide: Comprehensive testing framework and best practices

🛠 Advanced Installation

From Source Code

git clone https://github.com/gama-platform/gama-pettingzoo.git
cd gama-pettingzoo
pip install -e src/

Development Dependencies

pip install -e ".[dev]"      # For development
pip install -e ".[examples]"  # For examples

🧪 Testing and Validation

# Run tests
pytest

# With coverage
pytest --cov=gama_pettingzoo --cov-report=html

# Multi-agent specific tests
pytest -m multiagent

🤖 Supported Algorithms

GAMA-PettingZoo supports all multi-agent reinforcement learning algorithms compatible with PettingZoo:

• Multi-Agent Q-Learning
• Independent Deep Q-Networks (DQN)
• Multi-Agent Deep Deterministic Policy Gradient (MADDPG)
• Multi-Agent Proximal Policy Optimization (PPO)
• And many more...

🎮 Available Environments

Prison Escape

An escape environment where a prisoner attempts to escape while a guard tries to stop them.

• Agents: prisoner, guard
• Action Space: Discrete (4 directions)
• Observation Space: Agent positions on the grid

Pac Man Multi-Agent

Multi-agent version of the famous Pac-Man game.

• Agents: pacman, ghost1, ghost2, ...
• Objective: Cooperation/competition in collecting points

Moving Exemple

Simple environment for learning the basics of mobile agents.

• Agents: Configurable
• Objective: Navigation and coordination

🤝 Contributing

Contributions are welcome! Check the issues to see how you can help.

Development

# Clone the repository
git clone https://github.com/gama-platform/gama-pettingzoo.git
cd gama-pettingzoo

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Code formatting
black src/ examples/ tests/
isort src/ examples/ tests/

🔗 Useful Links

• GAMA Platform
• PettingZoo Documentation
• GAMA-Gymnasium
• GAMA-Client PyPI

For more technical details and practical examples, check the documentation in the examples/ and src/ folders, or explore our comprehensive testing framework.