collectivecrossing 0.1.3

A multi-agent reinforcement learning environment for probing the overlap of MARL and social sciences

🚇 Collective Crossing

A multi-agent reinforcement learning environment for simulating collective behavior in tram boarding/exiting scenarios. This project provides a grid-world environment where multiple agents interact to achieve their goals while sharing some resources together.

🎯 Overview

The CollectiveCrossingEnv simulates a minimal tram boarding scenario where coordination is essential to find the optimal collective behavior:

• Boarding agents 🚶‍♂️ start in the platform area and navigate to the tram door
• Exiting agents 🚶‍♀️ start inside the tram and navigate to the exit
• Simple collision avoidance 🛡️ prevents agents from occupying the same space, which makes the passing through the tram door a bottleneck and a challenge
• Configurable geometry 🏗️ allows customization of tram size, door position, and environment
• Flexible reward system 🎁 supports multiple reward strategies (default, simple distance, binary)
• Customizable termination ⏹️ configurable episode termination conditions
• Adaptive truncation ⏱️ flexible episode truncation policies
• Configurable observations 👁️ customizable observation functions and spaces

🚀 Quick Start

from collectivecrossing import CollectiveCrossingEnv
from collectivecrossing.configs import CollectiveCrossingConfig
from collectivecrossing.reward_configs import DefaultRewardConfig
from collectivecrossing.terminated_configs import IndividualAtDestinationTerminatedConfig
from collectivecrossing.truncated_configs import MaxStepsTruncatedConfig
from collectivecrossing.observation_configs import DefaultObservationConfig

# Create environment with configurable systems
reward_config = DefaultRewardConfig(
    boarding_destination_reward=15.0,
    tram_door_reward=10.0,
    tram_area_reward=5.0,
    distance_penalty_factor=0.1
)

terminated_config = IndividualAtDestinationTerminatedConfig()
truncated_config = MaxStepsTruncatedConfig(max_steps=100)
observation_config = DefaultObservationConfig()

config = CollectiveCrossingConfig(
    width=12, 
    height=8, 
    division_y=4,
    tram_door_left=5, 
    tram_door_right=7, 
    tram_length=9,
    num_boarding_agents=5, 
    num_exiting_agents=3,
    exiting_destination_area_y=0, 
    boarding_destination_area_y=8,
    render_mode="rgb_array",
    reward_config=reward_config,
    terminated_config=terminated_config,
    truncated_config=truncated_config,
    observation_config=observation_config
)

env = CollectiveCrossingEnv(config=config)
observations, infos = env.reset(seed=42)

# Take actions for all agents
actions = {
    "boarding_0": 0,  # Move right
    "boarding_1": 1,  # Move up
    "boarding_2": 2,  # Move left
    "boarding_3": 3,  # Move down
    "boarding_4": 4,  # Wait
    "exiting_0": 0,   # Move right
    "exiting_1": 1,   # Move up
    "exiting_2": 2,   # Move left
}

# Step the environment
observations, rewards, terminated, truncated, infos = env.step(actions)

# Render the environment
rgb_array = env.render()

📚 Documentation

🌐 Live Documentation - Complete documentation site

• Installation Guide - Detailed setup instructions
• Usage Guide - Complete usage examples and configuration
• Baselines - Baseline policies and demo scripts
• Development Guide - Testing, contributing, and development
• Features Overview - Comprehensive feature descriptions
• Local Deployment - Simple deployment guide

🎮 Key Features

• Multi-agent simulation with boarding and exiting agents
• Collision avoidance prevents agents from overlapping
• Configurable geometry customizable tram and door positions
• Ray RLlib compatible uses MultiAgentEnv API
• Multiple rendering modes ASCII and RGB visualization
• Type-safe configuration using Pydantic v2 with automatic validation
• Flexible reward system multiple reward strategies (default, simple distance, binary, constant negative)
• Customizable termination configurable episode ending conditions (individual/all at destination)
• Adaptive truncation flexible episode timeout policies (max steps, custom)
• Configurable observations customizable observation functions and spaces
• Comprehensive validation automatic parameter validation with helpful error messages

🛠️ Installation

Quick Install with pip

pip install collectivecrossing

Development Install

# Clone and install
git clone [e-mail]:nima-siboni/collectivecrossing.git
cd collectivecrossing
uv sync

# Install development dependencies
uv sync --dev

# Optional: Install demo dependencies for RLlib examples
uv sync --group demo

See Installation Guide for detailed instructions.

🚀 Quick Deploy

# Deploy documentation to GitHub Pages
./scripts/docs.sh deploy

See Local Deployment Guide for details.

🧪 Testing

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=collectivecrossing

# Run type checking
uv run mypy src/collectivecrossing/

# Run linting
uv run ruff check . --config tool-config.toml

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

See Development Guide for detailed contribution guidelines.

📄 License

This project is licensed under the Apache License 2.0.

---

Happy simulating! 🚇✨