PopUpSim is a microscopic simulation system for optimizing Pop-Up retrofitting sites during the European freight rail industry's transition to Digital Automatic Couplers (DAC). The tool simulates the complex logistics of retrofitting approximately 500,000 freight wagons during the critical 3-week "Big Bang" migration period (2029-2034).
PopUpSim helps railway operators:
- Test workshop configurations - Develop and validate standardized Pop-Up workshop designs
- Estimate throughput - Calculate maximum wagon processing capacity
- Import infrastructure data - Use existing railway infrastructure data (CSV/JSON)
- Identify bottlenecks - Optimize resource allocation before real-world implementation
- Assess capacity - Validate if planned workshops meet migration targets
- Microscopic Simulation - Track individual wagons and resources through workshop operations
- SimPy-based Engine - Deterministic discrete event simulation for reproducible results
- File-based Configuration - Easy-to-edit JSON/CSV configuration files
- Comprehensive Analysis - Throughput metrics, utilization statistics, bottleneck identification
- Open Source - Apache 2.0 licensed for cross-company collaboration
- Python 3.13 or higher
- uv package manager
If uv is used, the necessary Python version will be automatically installed during installation of PopUpSim. For different ways of installing uv can be found in Step 1 of the installation guide.
A more detailed description of the installation process can be found in the installation guide
If you have a git client installed:
# Clone repository
git clone https://github.com/OpenRailAssociation/dac-migration-dss-popupsim.git
cd dac-migration-dss-popupsim
# Install dependencies
uv sync
# Run example simulation
uv run python popupsim/backend/src/main.py --scenario Data/examples/demo/ --output output/If you don't have git installed:
-
Download the latest release as ZIP:
- Visit: https://github.com/OpenRailAssociation/dac-migration-dss-popupsim/archive/refs/heads/main.zip
- Or go to the GitHub repository and click "Code" → "Download ZIP"
-
Extract the archive to your desired location
-
Open a terminal/command prompt and navigate to the extracted folder:
cd dac-migration-dss-popupsim-main # Install dependencies uv sync # Run example simulation uv run python popupsim/backend/src/main.py --scenario Data/examples/demo/ --output output/
After installation, run simulations with:
# Navigate to project directory (if not already there)
cd dac-migration-dss-popupsim
# Run with baseline scenario
uv run python popupsim/backend/src/main.py --scenario Data/examples/ten_trains_two_days_baseline/ --output output/
# Or run a variant scenario
uv run python popupsim/backend/src/main.py --scenario Data/examples/ten_trains_two_days_var1/ --output output/var1/PopUpSim includes a web-based dashboard for visualizing simulation results:
Windows:
run_dashboard.batLinux/macOS:
uv run streamlit run popupsim/frontend/streamlit_dashboard.pyThe dashboard will open in your browser at http://localhost:8501
Dashboard Features:
- Overview - KPIs, wagon flow, locomotive activity, workshop utilization
- Wagon Flow - Individual wagon journeys, status distribution, track occupancy over time
- Workshop Performance - Utilization, throughput, comparison between workshops
- Locomotive Operations - Activity breakdown, utilization percentages
- Track Capacity - Track utilization, capacity analysis
- Rejected Wagons - Rejection reasons and details
- Event Log - Searchable simulation events
- Process Log - Detailed process execution log
Note: Run the dashboard in a separate terminal window so you can continue running simulations.
Seven ready-to-use scenarios are included (10 trains, 224 wagons over 2 days):
- Baseline - 2 locomotives, 2 collection tracks, 2 workshops (2 bays each), 1 retrofit track, 1 retrofitted track
- Variant 1 - 1 locomotive (bottleneck), 3 collection tracks, 2 workshops (2 bays each)
- Variant 2 - 1 locomotive, 3 collection tracks, 2 workshops (2 bays each), 2 retrofit tracks
- Variant 3 - 2 locomotives, 3 collection tracks, 2 workshops (2 bays each)
- Variant 4 - 2 locomotives, 3 collection tracks, 2 workshops (4 bays each - increased capacity)
- Variant 5 - 4 locomotives, 3 collection tracks, 2 workshops (4 bays each), 2 retrofitted tracks
- Variant 6 - Same as Variant 5 but with opportunistic parking strategy
Known Limitations:
⚠️ Multiple retrofitted tracks: Currently not fully stable - use single retrofitted track for production scenarios⚠️ Smart accumulation parking strategy: May cause simulation deadlock if threshold is not reached at end of simulation - useopportunisticstrategy for reliability
PopUpSim MVP uses a 3-context architecture:
- Configuration Context - Input validation & parsing (Pydantic)
- Workshop Operations Context - Simulation execution & analysis (SimPy)
- Analysis & Reporting Context - Orchestration & output (Matplotlib, CSV)
For detailed architecture documentation, see docs/mvp/architecture/.
- Tutorial - Step-by-step configuration guide using the ten_trains_two_days example
- Architecture Documentation - Complete arc42 architecture (12 sections)
- Development Guide - Implementation details and code examples
- Backend README - Backend-specific documentation
- Use Cases - User stories and requirements
# Install with development dependencies
uv sync --all-extras --dev
# Install pre-commit hooks
uv pip install pre-commit
pre-commit install
uv run ./setup/dev/set_commit_msg_hooks.py# Run all quality checks
uv run ruff format . && uv run ruff check . && uv run mypy popupsim/backend/src/ && uv run pylint popupsim/backend/src/ && uv run pytest
# Individual commands
uv run pytest # Run tests
uv run ruff format . # Format code
uv run ruff check . # Lint code
uv run mypy popupsim/backend/src/ # Type checking
uv run pylint popupsim/backend/src/ # Code quality analysis- Type hints mandatory - All functions/methods must have explicit type annotations
- MyPy strict mode -
disallow_untyped_defs = true - Ruff formatting - Consistent code style
- Pytest - Comprehensive test coverage
- Pylint - Static code analysis and linting
- Python 3.13+ - Latest stable Python with improved type system
- SimPy - Discrete event simulation framework
- Pydantic 2.0+ - Data validation and settings management
- Matplotlib - Visualization and chart generation
- Pandas - CSV data processing
- uv - Fast, reliable Python package manager
Current Phase: MVP Implementation and code stabilization
We welcome contributions from the railway industry and open source community!
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Make your changes following code quality standards
- Run all quality checks
- Commit your changes (
git commit -m 'Add feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
See CONTRIBUTING.md for detailed guidelines.
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
- Open Rail Association - Project governance and cross-company collaboration
- 3-Länderhack 2024 - Initial prototype development with ÖBB, DB, and SBB
- DB Cargo Migration Team - Domain expertise and requirements
- Skydeck Accelerator (DB Systel GmbH) - Project support
- GitHub Issues - Report bugs or request features
- Documentation - Complete architecture docs
- Open Rail Association - Project homepage
Note: PopUpSim is under active development. The MVP focuses on desktop simulation with file-based configuration. Future versions will include e.g. a web interface.