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 delivered rolling stock at about $1.4M per self-contained car 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.1, with active v0.2 work.

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
Find any Markdown document	docs/INDEX.md
See generated city designs	designs/README.md
Run the simulator	Quick Start
Generate a city network	Designing Cities
Review rolling-stock design	docs/rolling-stock/light-metro-3car/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
Read the architecture	docs/ARCHITECTURE.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
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

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

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

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>.

Rolling Stock And CAD

The current reference train is the light-metro-3car: cabless, driverless, battery electric, powered end cars plus an unpowered middle car, 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 segmented glass-pane 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

Selected generated design views:

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

Cabless front/rear cowl close-up showing three heated laminated glass panes with bonded frame, mullions, demist traces, 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 17 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.

Generate CAD screenshots and STEP artifacts:

PYTHONPATH=mechanical-py/src python3 mechanical-py/scripts/render_screenshots.py
PYTHONPATH=mechanical-py/src python3 -m osr_mech.catalog --out mechanical-py/catalog

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

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.