How darl-libsignal/libsignal works
Project Type and Purpose
• This is a Python-based library (“LibSignal”) providing OpenAI Gym-compatible environments for traffic signal control (TSC) and a suite of baseline methods (traditional and RL-based).
• It wraps three simulators (CityFlow, SUMO, CBEngine), handles data ingestion/conversion, and supports running complete train/evaluate pipelines with one command (python run.py).
High-Level File/Directory Analysis
• Top-level:
• run.py – CLI entrypoint and experiment driver
• requirements.txt – Python dependencies
• README.md – installation & usage
• Core modules:
• agent/ – implementations of RL and heuristic TSC agents (DQN, PPO, SAC, CoLight, etc.)
• common/ – shared interfaces, metric calculators, registry, converter utilities
• configs/ – simulator config files (CityFlow, SUMO, OpenEngine) and TSC hyperparameter YAMLs
• data/ & dataset/ – raw traffic network/flow data and on-the-fly dataset class
• generator/ – road network & traffic generator scripts
• world/ – simulator wrappers for CityFlow, SUMO, OpenEngine
• trainer/ – base trainer and TSC trainer that orchestrate RL training loops
• utils/ – logging utilities
• final_result/ – training logs and output artifacts
Key Architectural Patterns
• Modular “plugin” architecture via a central registry (common/registry.py) to decouple components (agents, worlds, tasks).
• Clear separation of concerns:
• Data generation/conversion (generator/, common/converter)
• Simulator abstraction (world/)
• Environment interface (environment.py)
• Agent logic (agent/)
• Training orchestration (trainer/)
• Configuration driven (configs/)
• Uniform experiment launcher (run.py) that reads configs, instantiates classes via registry, and triggers training/evaluation.
Main Components & Interactions
a. Components
1. Run Manager (run.py + Config Loader)
2. Registry Service (common/registry)
3. Generator & Converter (generator/, common/converter)
4. Data Store (data/raw_data, dataset/onfly_dataset)
5. Simulator Adapters (world_cityflow, world_sumo, world_openengine)
6. Gym-style Environment (environment.py)
7. Agent Module (agent/)
8. Trainer Module (trainer/)
9. Metrics & Logger (common/metrics, utils/logger)
10. Output Artifacts (final_result/)
11. External Simulators (CityFlow, SUMO, CBEngine binaries)
b. Relationships & Data Flow
1. Run Manager loads CLI args & YAML configs → Register desired Agent, World, Task.
2. Generator (if synthetic) prepares road network & flow files → Data Store.
3. Converter optionally transforms net/flow between formats.
4. World Adapter wraps external simulator API → exposes Gym-style step(), reset().
5. Trainer asks Environment for state → passes to Agent → receives action → applies to Environment → Environment calls Simulator → returns next state, reward.
6. Trainer updates Agent model (via PyTorch), logs metrics.
7. At end of epoch/experiment, Logger writes to final_result/.
c. Architectural Patterns & Principles
• Dependency Injection via registry to plug new agents or simulators.
• Single Responsibility: each module focuses on one facet (e.g., world vs. agent vs. trainer).
• Configuration-first: YAML and CFG files drive behavior, reducing hardcoding.
• Extensibility: adding a new agent or simulator only requires implementing the interface and registering it.
d. Key Technologies & Libraries
• Python 3.9, PyTorch 1.11.0, OpenAI Gym API
• CityFlow, SUMO, CBEngine simulators
• YAML for TSC hyperparameters
• Docker for reproducible execution