GAPEKA Simulator — Line Capacity Simulation & Train Schedule Conflict Detection

Overview

As a railfan, one of the most common discussions in the community is a proposed new route or train schedule — but how often is that proposal actually checked against the line’s real capacity? A single-track line has a hard capacity limit: two trains cannot pass each other on the same block section without crossing at a station. GAPEKA Simulator was built to simulate single-track line capacity and automatically detect schedule conflicts — for both existing data and fictional/proposed train scenarios — following the official PM 110/2017 (GAPEKA) and PM 62/2013 (Train Headway / WAK) standards. The underlying dataset covers 32 real trains across 7 single-track segments in West Sumatra.

---

Interface Screenshot

---

Technical Challenges

• Dual Regulatory Compliance: The engine complies with two separate regulations at once — PM 110/2017 for conflict classification (crossing/overtaking/station-track conflicts) and PM 62/2013 for train headway (WAK) calculations. Conflict detection is built as a 3-tier system, not a simple overlap check.
• Overnight Time Rollover: Trains departing late at night and arriving after midnight the next day need a consistent time representation. Internal time is stored as integer minutes (0–2879, instead of 0–1439) so schedule comparison logic stays linear without special-casing midnight rollovers.
• Pure Domain Logic Decoupled from Infrastructure: The engine/ module has no dependency on FastAPI or the database — it only accepts structured data and returns detection results. This separation makes the entire conflict-detection logic independently testable, including for fictional train scenarios, which only require a new entry in trains.json without touching existing trains.

---

Architecture Decisions

• Two Interfaces, One Engine: A CLI (reads JSON → renders PNG via Matplotlib for static reports/archives) and a Web app (FastAPI + MariaDB + interactive Plotly for scenario exploration). Both share the same domain engine.
• Fictional and Real Data Are Equal to the Engine: Since validation (validate_trains.py) only cares about data structure and consistency — not its source — proposed/fictional trains can be tested for feasibility in exactly the same way as trains already in operation.

---

Quality Evidence

• 140 tests, 98% code coverage on the engine module.
• 32 real trains, 7 single-track segments, based on official KP DJKA 226/2024 data.
• Regulatory documentation (PM 110/2017, PM 62/2013 PDFs) is included directly in the repo as the source of truth.

---

Status & Roadmap

What’s working today: single-track line capacity simulation and schedule conflict detection, for both existing data and fictional/proposed train scenarios.

Next direction is toward physics-aware simulation — incorporating locomotive parameters, gradient, and class-based dwell-time rules (including special cases like rack-rail locomotive changeovers) — so that proposed-schedule predictions get closer to real technical conditions on the ground, and can serve as a stronger tool for discussion and advocacy within the railfan community.