Sumo rl: Traffic Simulation Environment

[init27]

Complete OpenEnv integration for traffic signal control using SUMO (Simulation of Urban MObility).

src/envs/sumo_rl_env/
├── __init__.py ✅ (Export SumoRLEnv, SumoAction, etc.)
├── models.py ✅ (SumoAction, SumoObservation, SumoState - 122 lines)
├── client.py ✅ (SumoRLEnv HTTP client - 136 lines)
├── README.md ✅ (Comprehensive user guide - 390 lines)
└── server/
    ├── __init__.py ✅
    ├── sumo_environment.py ✅ (Environment wrapper - 218 lines)
    ├── app.py ✅ (FastAPI server - 45 lines)
    └── Dockerfile ✅ (Docker image with SUMO - 68 lines)

nets/single-intersection/
├── single-intersection.net.xml ✅ (Network topology)
├── single-intersection.rou.xml ✅ (Vehicle routes)
└── ... (other SUMO config files)

examples/
└── sumo_rl_simple.py ✅ (Example usage - 108 lines)

.github/workflows/
└── docker-build.yml ✅ (Updated with sumo-rl-env)

1. Single Environment Instance Pattern ✅

# In server/app.py
env = SumoEnvironment(...)  # Created once at startup
app = create_fastapi_app(env, ...)  # Reused for all requests

Benefit: Avoids TraCI connection conflicts

2. Defaults Used:

sumo_seed=42  # Deterministic by default
use_gui=False  # No GUI in Docker
out_csv_name=None  # No CSV accumulation
sumo_warnings=False  # Quiet operation

Basic Usage

from envs.sumo_rl_env import SumoRLEnv, SumoAction

# Start container automatically
env = SumoRLEnv.from_docker_image("sumo-rl-env:latest")

# Reset
result = env.reset()
print(f"Actions available: {result.observation.action_mask}")

# Take action
result = env.step(SumoAction(phase_id=1))
print(f"Reward: {result.reward}")

# Cleanup
env.close()

Custom Configuration

# Shorter episode for quick testing
env = SumoRLEnv.from_docker_image(
    "sumo-rl-env:latest",
    environment={
        "SUMO_NUM_SECONDS": "5000",
        "SUMO_DELTA_TIME": "10",
    }
)

Custom Network

# Use your own network files
env = SumoRLEnv.from_docker_image(
    "sumo-rl-env:latest",
    volumes={
        "/path/to/your/nets": {"bind": "/nets", "mode": "ro"}
    },
    environment={
        "SUMO_NET_FILE": "/nets/my-network.net.xml",
        "SUMO_ROUTE_FILE": "/nets/my-routes.rou.xml",
    }
)

[Darktex]

Nice!

[pankit-eng]

@init27 - in the custom network example above, we are calling out bind mounts for the docker container. Up until now, the implicit assumption has been that the containers don’t need persistent storage or need any bind mounts. But this env does need that, and if that’s the case then we will pbbly need to evolve the docker container set up into a more holistic spec that will be needed by the providers. What’s your take on this?

[pankit-eng]

Left a comment for further discussion on bind mounts(in this case its RO only)

[init27]

@pankit-eng Thanks for the Q:

You're right that bind mounts break the provider-agnostic abstraction. If OpenEnv is meant to work with different backends (Docker, K8s, cloud providers), then Docker-specific bind mounts are a leaky abstraction.

For now, in this case:

1. It's an advanced feature (80/20 rule):
   - 80% of users will use the bundled single-intersection network (works out-of-the-box)
   - Only 20% of advanced researchers need custom networks
   - Default case works perfectly without bind mounts
2. It's read-only and stateless:
   - No persistent storage concerns
   - No data corruption risks
   - No state management complexity
   - Just configuration data (network topology files)
3. It's isolated to SUMO-RL:
   - Atari, Chat, Echo, Coding don't need this pattern
   - Only SUMO-RL needs custom data files (so far)
4. Current design already assumes Docker:
   - from_docker_image() is explicitly Docker-specific
   - The abstraction is already somewhat leaky

If this pattern repeats (2-3+ environments need custom data), then yes, evolve to a formal spec.

I will open an issue and we can discuss