gama-gymnasium 1.0.0

A Gymnasium environment for reinforcement learning with GAMA agent-based simulations

GAMA-Gymnasium

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

🎯 Purpose

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

⚡ Quick Start

Installation

pip install gama-gymnasium

Prerequisites

• GAMA Platform: Install GAMA from gama-platform.org
• Python 3.8+ with required dependencies

pip install gama-client gymnasium

Basic Usage

import gama_gymnasium
import gymnasium as gym

# Create the environment
env = gym.make('gama-gymnasium-v0', 
               gama_model_path='your_model.gaml',
               gama_port=6868)

# Use as a standard Gymnasium environment
obs, info = env.reset()
for _ in range(100):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        obs, info = env.reset()

GymAgent

The GymAgent is a GAMA agent that is required in the model to enable interaction between the simulation's learning agent and the Gymnasium environment. It has nine variables and one action. The GymAgent is a GAMA agent required in the model to allow the interaction between the learning agent of the simulation and Gymnasium environments. It have 9 variables and 1 action

Structure of the agent:

species GymAgent{
	map<string, unknown> action_space;
	map<string, unknown> observation_space;

	unknown state;
	float reward;
	bool terminated;
	bool truncated;
	map<string, unknown> info;

	unknown next_action;

	map<string, unknown> data;

	action update_data {
		data <- [
			"State"::state,
			"Reward"::reward,
			"Terminated"::terminated,
			"Truncated"::truncated,
			"Info"::info
		];
	}
}

GAMA Configuration

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

   species GymAgent;
   

   Set up the action_space and observation_space:

   global {
       init{
           create GymAgent{
             action_space <- ["type"::"Discrete", "n"::4];
             observation_space <- ["type"::"Box", "low"::0, "high"::grid_size, "shape"::[2], "dtype"::"int"];
           }
       }
   }
   

   Update the gym agent's data after the action is completed:

   ask GymAgent[0] {
       do update_data;
   }
   

2. Launch GAMA in server mode:

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

# Windows
gama-headless.bat -socket 6868

📁 Project Structure

gama-gymnasium/
├── 📁 src/               # Main Python package source code
├── 📁 tests/             # Comprehensive test suite
├── 📁 examples/          # Complete examples and tutorials
├── pyproject.toml	      # Python package configuration
├── LICENSE               # Package license
└── pytest.ini            # Testing configuration

📚 Documentation and Examples

🚀 Tutorials and Examples

Example	Description	Documentation
Basic Example	Introduction to GAMA-Gymnasium integration	📖 README
CartPole DQN	Deep Q-Network implementation on CartPole environment	📖 README
Frozen Lake Q-Learning	An example of Q-Learning purely in gama

📖 Detailed Guides

• Basic Example Guide: Complete tutorial for creating your first environment
• Direct GAMA Test: Low-level communication with GAMA
• 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-gymnasium.git
cd gama-gymnasium
pip install -e src/ 

🧪 Testing and Validation

# Run tests
python tests/test_manager.py --quick

🤝 Contributing

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

🔗 Useful Links

• GAMA Platform
• Gymnasium Documentation
• 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.