OpenSourceRail

OpenSourceRail is an open-source stack for designing, building, and operating affordable urban rail systems. It combines:

• city network generation from GIS data,
• a Rust simulator and control stack,
• parametric mechanical/CAD designs,
• hardware reference designs,
• operations and certification documentation,
• a machine-checkable safety case.

The default system is GoA 4 driverless, catenary-free, battery electric, and designed around local manufacture: welded steel primary structures, COTS rail/bus modules where sensible, commodity compute, and regenerable documentation/CAD artifacts.

Current city CAPEX uses trainset-family rolling-stock units, for example about $1.0M per 3-car light-metro trainset, plus a separate lean $100k per vehicle/car module railway production-plant setup allowance; $200k per vehicle/car module is retained only as the high sensitivity check. The machine-readable source is lib/templates/capex-costs.toml, with the audit trail in docs/cost-model.md.

Current milestone: v0.2 development baseline, with remaining validation and hardening tracked in docs/ROADMAP.md.

Adoption And Assurance Path

OpenSourceRail is not asking a city to accept an uncertified full-stack driverless metro as the first step. The practical first wedge is owner-operator software that can run without controlling trains: simulation/digital-twin studies, generated asset registers, manufacturing and construction QA, maintenance scheduling, Ops Core work orders, acceptance evidence, historian views, and depot CBM adapters. Those can be used on an existing railway, depot, test track, or city design study while the safety-critical train-control stack remains in shadow mode.

Step	Deployable result	Safety exposure
Planning / shadow mode	Simulator, cost/energy model, portal registers, QA/maintenance/evidence pack	No command of trains
Depot or closed test track	COTS hardware hosts, work orders, inspection forms, telemetry, restricted movement trials	Local rules and test authority only
Segregated pilot segment	Trial service with independent assessor review and deployment-specific safety case	Limited operational exposure
Revenue GoA 4 service	Certified train-control, rolling-stock, station, energy, and operations system	National authority acceptance required

The GoA 4 train-control and rolling-stock stack is therefore a later certification program, not a README promise. OpenSourceRail produces reference designs, code, proofs, tests, operating rules, and evidence packs. It does not itself carry the statutory safety certificate, operating license, product liability, insurance, or sovereign finance package. Those responsibilities sit with the deployment owner/operator, prime integrator, independent safety assessor, insurer, and national safety authority.

SIL names in this repository are target assurance and hazard-allocation labels. Nothing here is certified SIL-4, SIL-2, or any other SIL until a deployment-specific assessor and authority accept the evidence.

The battery-electric, catenary-free system is the default design target, not a universal law. Every city model must include battery replacement, charger dwell, fleet reserve, charger thermal limits, grid/PPA studies, fire/egress constraints, and station/depot storage. Catenary or third rail may still win for very high-frequency trunks, constrained dwell times, difficult climates, or weak station power sites; the point of OSR is to make that trade visible rather than bury it in vendor pricing.

Station And Track Renders

At-grade station	Elevated station	Elevated interchange

Generated from the FreeCAD station scene package in mechanical-py/catalog/freecad/station-scenes.FCStd; see docs/stations/README.md for the station artifact index.

Start Here

Goal	Go here
Read the short introduction brochure	OpenSourceRail introduction PDF
Understand the whole repo	docs/README.md
Understand the unified deployment model	docs/deployment-model.md
Understand deployment responsibilities	docs/deployment-roles.md
Review the first adoptable product	docs/first-adoptable-product.md
Find any Markdown document	docs/INDEX.md
See generated city designs	designs/README.md
Run the simulator	Quick Start
Run the operations portal	Operations Portal
Contribute or review governance	CONTRIBUTING.md and GOVERNANCE.md
Prepare the v0.2 release	docs/releases/v0.2.md
Generate a city network	Designing Cities
Generate engineering screening packages	Engineering Screening For All Cities
Review rolling-stock design	docs/rolling-stock/light-metro-3car/README.md
Use the buildable trainset handoff	mechanical-py/catalog/buildable-trainset/README.md
Review station and track renders	docs/stations/README.md
Review mechanical CAD outputs	mechanical-py/README.md
Review hardware host classes	hardware/README.md
Review deployable host compositions	deployment/README.md
Read the architecture	docs/ARCHITECTURE.md
Review software architecture diagrams	docs/software-architecture-diagrams.md
Read the RFCs	docs/rfcs/README.md
Review certification evidence	docs/certification/ and docs/safety-case/

Repository Map

Path	Purpose
crates/	Rust workspace: simulator, interlocking, ATP, brake, obstacle detection, TCMS, GUIs, design synthesis, safety-case compiler
designs/	Generated city models, maps, scenarios, and cost summaries
design-py/	Python GIS/design sidecar for OSM, WorldPop, raster generation, maps, and batch tooling
mechanical-py/	Python parametric mechanical catalogue: rolling stock, track, civil, stations, depots, fixtures, generated FreeCAD review artifacts
hardware/	Hardware reference designs and DIY assembly for T-ECU/S, T-ECU/A, T-OBS, W-SBC, S-SBC
docs/	Architecture, RFCs, certification pack, safety case, operations, civil, stations, rolling-stock docs
docs/operations-portal/	Browser operations portal for asset registers, manufacturing schedules, QA gates, maintenance work orders, defects/NCR, audit, SQLite storage, and reconciliation
lib/	Machine-readable templates, recipes, examples, city batches, cost/finance inputs
formal/	TLA+ consensus specification and model-checking harnesses
tools/	Companion tools including LandXML to OSR-ALN and the Python MA reference interpreter
scripts/	Regeneration, publishing, repository health, BOM, and book-builder helpers
.github/repository-metadata.yml	Recommended GitHub description, homepage, and topics

The generated PDF reader edition is opensource-rail-docs-book.pdf.

Software Architecture Diagrams

Editable Mermaid diagrams for the backend, train, station, depot, wayside waypoint, energy, manufacturing, QA, maintenance, and safety/security layers are collected in docs/software-architecture-diagrams.md.

Diagram	Scope
Deployment context	OCC, depot, stations, wayside nodes, trains, passengers, utilities, and regulator evidence
Backend / OCC services	Event log, read models, historian, analytics, AFC back office, CBM, and Ops Core
Onboard train software	T-ECU/S, T-ECU/A, T-OBS, TCN-E, CAN-FD, sensors, traction, brakes, doors, BMS
Station and depot software	S-SBC station/depot host, PIS, AFC, TVM, PSD, SCADA, energy, self-test, workshop tools
Wayside / waypoint node software	W-SBC, consensus, interlocking, points, balises, intrusion, crossings, hot-axle detection
Control and data flow	Dispatcher request through route safety, movement authority, telemetry, CBM, and work orders
Energy and charging software	Charging dispatch, train BMS, regen, station/depot PV, BESS, chargers, and grid tie
Manufacturing, QA, maintenance, and evidence flow	Generated asset/manufacturing/QA/maintenance data into Ops Core, SQLite, evidence, NCR, and audit
Safety and security boundaries	Target assurance tiers, crypto, time sync, self-test, and signed firmware boundaries

Quick Start

Requirements: Rust via rustup. Python is needed only for GIS and CAD sidecars.

Run the bundled Samawah simulator scenario:

cargo run --release --bin osr-sim -- --duration 3600 --status-every 300

Run another generated city:

cargo run --release --bin osr-sim -- \
    --config designs/south-asia/Pakistan/Karachi/karachi.toml \
    --duration 3600

Check repository health and generated artifact drift:

python3 scripts/repo-health.py --quiet

Check the FreeCAD bridge for CAD assemblies, FEM models, and screenshots:

scripts/freecad-generate.sh --check

Run the top-down / bottom-up rolling-stock design iterator:

scripts/design-iterate.sh
scripts/buildable-trainset.sh
scripts/buildable-stations.sh

Operations Portal

The browser portal gives each generated city an asset register, manufacturing schedule, QA gate register, maintenance schedule, lightweight Ops Core work-order loop, defects/NCR register, audit trail, SQLite persistence, and a reconciliation path for browser-local fallback records. Manufacturing rows include controlled material/BOM refs, QA verification rows, resolved predecessor ids, and release blocking until predecessor work is closed with pass evidence.

Run the SQLite-backed portal:

python3 scripts/generate-qa-maintenance-data.py
python3 scripts/ops-core-server.py --port 8008

Then open:

http://127.0.0.1:8008/docs/operations-portal/

Key docs:

• Operations portal
• OSR Ops Core
• Acceptance and accreditation evidence basis
• Acceptance evidence matrix CSV
• Operations portal gap analysis
• RFC 0028 construction QA
• RFC 0029 maintenance schedule system
• RFC 0030 manufacturing schedule system

Portal dashboard	Ops Core + SQLite	QA gates

The acceptance/accreditation evidence basis is generated from the same city operations bundle. It checks that every manufacturing row has material/BOM refs, a QA verification row, a linked QA action, resolved predecessor ids, and release blocking through Ops Core evidence.

Acceptance dashboard	Manufacturing controls

Simulation Screenshots

Simulator playback GUI	Samawah run dashboard

Regenerate the current simulator screenshots:

python3 scripts/render-sim-screenshots.py

The Samawah reference was acceptance-tested on 2026-08-12 using the generated 96-trainset, three-line scenario: 86 peak sets, 7 planned spares, and 3 cold reserves. Morning and afternoon peaks retain quick turnarounds; the 12-minute concurrent clean, safety inspection, diagnostics download, and 150 kW low-C recharge moves to 6- and 12-minute off-peak windows, so no additional depot-service trainsets are required. The corrected model uses a 675 kWh nameplate / 540 kWh usable pack, protects a 20% SoC reserve, models 150 kW low-C top-up at all six depot/terminal layups, and uses a 3.0 kWh/car-km nominal base before the scenario climate uplift (the design and infrastructure plan retains the conservative 4.0 kWh/car-km case).

Verified run	Result
2-hour screenshot trace	2,343.09 train-km; 23,617.08 kWh consumed; 20,327.01 kWh charged; 34 depot services completed; minimum SoC 62%; 0 onboard emergencies; 0 invariant violations
Full 05:30–02:00 service-window soak	24,839.54 train-km; 250,376.24 kWh consumed; 219,389.36 kWh charged; 453 depot services completed (3 still active at the cutoff); minimum SoC 20%; 0 onboard emergencies; 0 invariant violations

The full-window result is the simulated movement actually completed, not the 27,177 train-km timetable-planning upper bound. Energy-reserve gating now holds a train for charging instead of allowing motion at zero SoC.

Designing Cities

Generated city models live under:

designs/<region>/<country>/<City>/

Each city folder contains design.toml, a simulator scenario TOML, route GeoJSON, a network map PNG, design-quality YAML, and a generated README. The catalogue table is included in designs/README.md.

Regenerate one city:

pip install -e design-py[geotiff,batch]
cargo build --release --bin osr-design
scripts/regenerate-city.sh samawah

Regenerate the catalogue:

scripts/regenerate-all.sh --jobs 4

To add a city, add an entry to lib/city-batches/world-sample.toml, then run scripts/regenerate-city.sh <slug>.

Engineering Screening For All Cities

The open-source engineering toolchain can generate the same screening package for one city, a selected group, or the complete design catalogue. It discovers the canonical designs/*/*/*/design.toml files directly, so it does not maintain a separate city list.

After installing the pinned tools described in engineering/toolchain/README.md, run a full catalogue simulation with:

scripts/engineering-toolchain.sh --cities \
    --all \
    --allow-input-gaps \
    --jobs 2 \
    --resume

Run the Samawah acceptance example by itself with:

scripts/engineering-toolchain.sh --cities \
    --city samawah \
    --allow-input-gaps \
    --jobs 1

Generate reviewable inputs without launching SUMO:

scripts/engineering-toolchain.sh --cities \
    --all \
    --generate-only \
    --allow-input-gaps \
    --jobs 8

This still runs the GIS packaging and electrical/PV screening. Add --skip-gis or --skip-energy when only the remaining package types are wanted. The default is the complete city engineering package.

Replace --all with --city samawah or a comma-separated selection such as --city samawah,songea. --resume reuses only successful results whose canonical input and generator hashes still match. Transient Flatpak launcher failures are retried automatically at reduced concurrency.

Each batch produces:

• a QGIS/GDAL GeoPackage of populated corridor, station, civil-segment, energy-site, depot and input-issue layers, plus all six source GeoJSON review layers in EPSG:4326;
• SUMO node, edge, route, timetable, log, trip and summary files for every declared city line, shaped from the canonical corridor GeoJSON rather than schematic parallel lines;
• pandapower grid-only and coordinated PV/storage load flows, plus a pvlib clear-sky and climate-derated annual PV planning envelope;
• source hashes, tool versions, service arrivals, per-line journey times and structured input-quality findings;
• a mapping from every city station to its station archetype, BOM/product-item count, assembly count, open-release count and shared IFC template;
• checked IFC 4X3 product structures for all seven shared station archetypes;
• the shared JuPedSim normal/constrained station-corridor benchmark; and
• per-city logs under each canonical city folder plus a catalogue summary at build/engineering/cities/batch-summary.json.

For a city named <slug>, generated evidence is written to:

Output	Location
QGIS GeoPackage and review layers	designs/<region>/<country>/<City>/engineering/gis/
SUMO network, timetable and results	designs/<region>/<country>/<City>/engineering/sumo/
pandapower networks and pvlib summary	designs/<region>/<country>/<City>/engineering/energy/
Station-to-BOM/assembly mapping	designs/<region>/<country>/<City>/engineering/station-product-map.json
Combined logs	designs/<region>/<country>/<City>/engineering/generation.log
Catalogue summary	build/engineering/cities/batch-summary.json

Current verification status

Scope	Result
Catalogue input compatibility	263 city designs; companion-input and schema counts must be refreshed after the current regeneration
Previous catalogue-wide SUMO run	262 city summaries completed, but only 258 still match the current design hash; these are historical until regenerated into each city folder
Expanded end-to-end package	Samawah acceptance run passed; Songea portability run passed
Expanded catalogue-wide solver run	Not yet rerun after adding GIS, corridor geometry and energy generation

The expanded package has been acceptance-run on Samawah and independently exercised on Songea. All 263 designs have the required city scenario and corridor companion files, so the same generator path applies catalogue-wide. Samawah's three-line GIS package contains 3 corridors, 31 stations, 12 civil segments, 29 energy sites and 6 depots. Its geometry-shaped SUMO test completed all services. The electrical screen converged in both cases: the grid-only peak exposed 14 transformer overloads, while the coordinated daylight case had no overload or voltage-band findings. These are screening findings, not a claim of utility approval or measured-weather performance.

Samawah's design also selects the temperate-continental climate preset while its scenario ambient is 28 °C, 16 °C above that preset's annual average. The energy result records this as a climate-input review finding; it should be resolved against an approved local weather file before thermal or PV sizing.

The mapped geometry also remains a coordination input rather than survey evidence. In Samawah, the corridor-to-declared-length ratios are 0.9772, 0.9576 and 1.0018 for Lines 1–3, and the largest station-to-corridor offset is 92.2 m. These values are retained in the SUMO summary for alignment review.

The aggregate input-quality gate remains open for nine station-to-line endpoint gaps:

City	Line	Finding
Kananga	line 1	Start station is 116.6 m from the declared line origin
Mbuji-Mayi	line 4	Start gap 3,337.6 m; end gap 40.0 m
Gazipur	line 6	End gap 3,241.4 m
Hyderabad-Pk	line 6	Start gap 28.3 m; end gap 2,289.9 m
Karachi	line 9	Start gap 3,025.9 m; end gap 20.0 m
Gaza-City	line 3	End gap 518.0 m

--allow-input-gaps permits generation and simulation while retaining those findings; it does not mark the aggregate as input-quality-passed. Omit the flag when gaps must fail the command.

These outputs are screening evidence, not automatically approved engineering. Surveyed alignments, calibrated passenger demand and dwell, connected interchange/junction topology, road interactions, local climate and fire inputs, and competent deployment review remain required before release. The detailed boundaries and remaining tasks are in docs/engineering-design-simulation-plan.md.

Rolling Stock And CAD

The current reference train is the light-metro-3car: cabless, driverless, battery electric, three repeated self-contained cars with one powered bogie and one trailer bogie each, under-seat sodium-ion batteries, mixed bonded/rail-mounted roof solar feeding a per-car PV/station charge inverter, COTS doors/windows/HVAC, two low-floor door pairs per side per car, and T-OBS sensor packs behind single dark panoramic-glass noses at both ends.

Key links:

• Rolling-stock package
• Rolling-stock section README
• BOM skeleton
• Marketplace price anchors
• Civil marketplace cost anchors
• Fabrication plan
• Drawing register
• Mechanical package
• Parametric rolling-stock source
• Generated mechanical review catalogue
• Generated review catalogue README
• Buildable trainset handoff
• Product-tree definitions
• Shop traveler templates

Buildable handoff quick path:

Need	Use
See selected baseline and metrics	design iteration summary
See parts → subassemblies → assemblies → trainset	buildable manifest
Start drawing/RFQ work	definition pack with structured material/process specs
Start shop routing / QA planning	shop traveler pack with material/process controls
Review current buildability gaps	buildability review
Review geometry and FEM evidence	FreeCAD catalogue and FEA summary

Selected generated design views:

Final three-car reference consist with panoramic-glass end cowls, bodies, bogies, roof PV, and train-level systems.

Cabless front/rear cowl close-up showing the identical multi-part fiberglass end kit, one heated laminated panoramic glass pane, bonded edge frame, demist busbars, and service hardware.

HVAC ducting, LV/data trays, lighting, HV/PV routing, coolant, and fire-vent paths inside one car.

Primary body structure with translucent shell, 10 m low-floor centre pan, raised bogie-end decks, side sills, and portal frames.

Single-car structure mounted over standard motor/trailer bogies, showing the ~3 m high-floor end decks and the 10 m low-floor centre zone.

Manufacturing-oriented sheet-metal kit for underframe, bolsters, coupler pockets, side posts, roof bows, and floor transitions.

Production concept board showing the repeated 16.5 m car module, welded datum frame, COTS module installation, and bogie marriage sequence.

One self-contained car equipment package: four door cassettes, platform safety interfaces, batteries, rooftop PV package, charging interface, traction/charge power rack, and accessibility/safety reservations.

Per-car rooftop PV package with bonded flexible laminates, raised rigid panels, mounting rails, edge clamps, junction boxes, fire isolators, MPPT combiner, and downlink gland.

Semi-permanent articulated gangway module with lower spherical joint, anti-lift keeper, upper links, bellows, turntable floor, trainline routing, and kinematic clearance frame.

Powered bogie assembly with frame, wheelsets, PMSM motors, gearboxes, suspension, and brakes.

Selected CalculiX FEA screening result plots:

Chassis service gravity	Bogie brake/traction	Body lateral sway

The full screening summary and raw solver outputs are in mechanical-py/catalog/fea.

The rolling-stock design hierarchy and candidate-iteration workflow are documented in docs/rolling-stock/design-system.md; generated scorecards are in mechanical-py/catalog/design-system. The buildable trainset handoff is generated in mechanical-py/catalog/buildable-trainset. It includes a manifest, buildability review, one definition per product-tree node, and one unsigned shop-traveler template per node. Definitions and travelers now carry structured material specs, process specs, operation routers, estimated labor, tooling IDs, QA gates, approval blocks, signoff blocks, and NCR/deviation logs.

Regenerate the design/buildable handoff and the CAD/FEM/screenshots:

scripts/design-iterate.sh
scripts/buildable-trainset.sh
scripts/freecad-generate.sh --check
scripts/freecad-generate.sh --models --assemblies --fem
scripts/freecad-generate.sh --screenshots --station-scenes
PYTHONPATH=mechanical-py/src python3 mechanical-py/scripts/render_screenshots.py

Hardware

Hardware docs are consolidated under hardware/:

• T-ECU/S train safety kernel,
• T-ECU/A train application computer,
• T-OBS obstacle-detection ECU,
• W-SBC wayside controller,
• S-SBC station/depot host,
• DIY assembly for commodity-module pilots,
• rolling-stock hardware integration.

Safety And Certification

Important entry points:

• Architecture
• Operations rulebook
• Safety case
• Certification pack
• TLA+ consensus spec
• RFC 0005 software architecture
• RFC 0015 driverless operation
• RFC 0016 wayside intrusion detection

Development Commands

# Rust workspace checks
cargo test --workspace

# Mechanical package tests
PYTHONPATH=mechanical-py/src pytest mechanical-py/tests -q

# Design-side tests
pytest design-py/tests -q

# Repository drift checks
python3 scripts/repo-health.py --quiet

See CHANGELOG.md for the current verification snapshot.

License

Project split, per ARCHITECTURE §9:

• Software: Apache 2.0
• Hardware designs: CERN-OHL-S v2
• Documentation: CC-BY-SA 4.0

OpenSourceRail is not a safety certifier or standards body. It produces open artifacts suitable for independent assessment by deployment partners and national authorities.

The contribution process and governance model are in CONTRIBUTING.md and GOVERNANCE.md. Complete license texts and the path mapping are in LICENSE.md and LICENSES/.