metrogym 0.1.1

About The Project

MetroGYM is a pure Python, pygame-powered teaching library for metro-network simulation, signalling, and control logic. It is intentionally small and inspectable: you build a network from primitives, attach train and signal agents, then run it visually or headlessly.

MetroGYM allows you to build complex metro systems from explicit primitives, then drive those worlds with typed train and signal solvers. It's designed for educational purposes, providing a clear and interactive way to understand transport network dynamics and algorithmic control.

See more in the documentation.

Installation

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Git: For cloning the repository.
• uv: The recommended Python package and project manager. Install it via astral.sh/uv.

Installation

To install MetroGYM, please run the following:

pip install metrogym
# You can also use uv add metrogym

Getting Started

To build your first simulation, you define the world through a pipeline of explicit primitives:

1. Initialise the System: Create a MetroSystem to manage the lifecycle and rendering.
2. Define the Infrastructure: Use a Network to group your Line paths and Station locations.
3. Attach Agents: Add a Train with a specific solver (the agent's brain) and a Signal that controls access to specific track segments.
4. Build and Run: Call .fit() to validate the topology and .run() to start the interactive simulation.

from metrogym import Color, MetroSystem, signal, train
from metrogym.primitives import ControlRule, Line, Network, Signal, Station, Train

system = MetroSystem(name="Quick Start", render_scale=2).pipeline([
    Network([
        Line("Loop", Color.BLUE, [(120, 120), (560, 120), (560, 360), (120, 360), (120, 120)]),
        Station("West", (120, 120)),
        Station("North", (560, 120)),
        Station("South", (560, 360)),
    ]),
    Train("A", line="Loop", solver=train.always_proceed(), asset="metro_nose"),
    Signal(
        "North Gate",
        (560, 85),
        controls=ControlRule("Loop", (560, 120), (560, 360)),
        solver=signal.pulse(green_ticks=5, red_ticks=3),
    ),
])

system.fit().run()

License

MetroGYM is licensed under the MIT License.