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, 1 m-wide clip-on fiberglass side/roof body modules, COTS rail/bus modules where sensible, commodity compute, and regenerable documentation/CAD artifacts. Six parallel two-person crews can install and release the exterior bodies of a three-car train in one eight-hour shift once the three painted frames pass their dimensional checks; doors, glazing, equipment, bogies, commissioning, and certification remain separate work.

Current city CAPEX uses trainset-family rolling-stock units, for example about $900k per 3-car light-metro trainset, plus a separate lean $60k per vehicle/car module railway production-plant setup allowance; $120k per vehicle/car module is retained only as the high sensitivity check. Distributed overnight stabling at powered stations also removes fleet-wide parking roads from depot scope; depot CAPEX retains inspection, defect repair, wheel, wash, and heavy-maintenance functions. 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 HTML
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 next release	docs/releases/next.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/	Compact machine-readable results for the 266-city catalogue, plus richer Samawah, Mosul, and Basra references
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

Generate the PDF reader edition with python3 scripts/build-doc-book.py; it is written to build/releases/.

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 evidence status
• Certification evidence register
• 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

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 the retained machine-readable core: design.toml, a simulator scenario TOML, corridor GeoJSON, station JSON, and design-quality YAML. Basra, Mosul, and Samawah additionally retain a reviewed network map and 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

This fast default resynthesises each canonical design before refreshing the complete package beside it. It reuses raster and corridor caches where they exist, and creates missing source caches automatically. Use scripts/regenerate-all.sh --from-scratch to force OSM, population raster, and corridor rebuilding even when current caches are available.

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 engineering toolchain generates GIS, SUMO, energy, finance, station-product, nominal/degraded simulation, operations, and acceptance evidence from the city source catalogue. Each full run ends with a hashed package-manifest.json and fails unless the complete screening package is present and passing. Full packages are local build products; the repository retains every compact routed design plus three richer reference fixtures.

After installing the pinned tools in engineering/toolchain/README.md, generate a city and run its engineering screen:

scripts/regenerate-city.sh samawah

Generated evidence is written into the city folder:

Output	Location
Full city package	designs/<region>/<country>/<City>/
GIS, SUMO, energy, and simulation evidence	that city package's engineering/ directory
Operations, QA, maintenance, and acceptance tables	that city package's operations/ directory
Engineering batch summary	build/engineering/cities/batch-summary.json
Complete-package summary	build/engineering/cities/package-summary.json

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 LFP batteries, mixed bonded/rail-mounted roof solar feeding a per-car MPPT and protected DC link, six independent traction controllers, direct-HV DC HVAC, 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.

The current RFC 0021 electrical baseline defines three 225 kWh gross LFP car packs on a 650–700 V nominal DC link, six independent heavy-vehicle-class PMSM controllers, direct-HV DC HVAC, isolated LV DC/DC domains, and a standard 500 kW station DC/DC cabinet backed by repeatable 500 kWh stationary-LFP modules. The welded S355 datum skeleton is the safety load path. Sixteen 1 m bays per 16.5 m car carry clipped fiberglass side and roof modules on keyed hooks, captive retainers, anti-lift locks, and dry replaceable EPDM seals; no full-length mould or production adhesive cure is required.

Key links:

• Rolling-stock package
• Rolling-stock section README
• BOM skeleton
• Marketplace price anchors
• Civil marketplace cost anchors
• Fabrication plan
• One-metre fiberglass body design
• Generated body module manifest
• 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/.