How profreusch2026mor/sustainable_freight_mode_choice works
1. Repository purpose
This is a research/analysis repository for a multimodal freight mode-choice problem, not a production service. The core architecture is a pipeline for loading transport-network instances, solving an optimization model, comparing it with heuristics, and exporting experiment results for a thesis-style writeup.
2. Main domain boundary: freight_routing/
This package is the central application layer. It likely contains the reusable domain objects and logic shared across solver runs, heuristics, notebooks, and experiments:
- data_models.py for the network, shipment, terminal, and transport entities
- data_loader.py for turning JSON instance files into those domain objects
- model.py for the exact optimization model
- visualization.py for plotting or inspecting solutions
3. Input data layer: dataset/
The network instances live as JSON files: small_network.json, medium_network.json, large_network.json, and test_network.json. This is the primary input boundary into the system. data_collector.py suggests a preprocessing or instance-building step that feeds these JSON datasets.
4. Exact optimization path
The README describes a MILP-based decision model. In the codebase, this is most likely implemented in freight_routing/model.py and solved using Python optimization libraries mentioned in the README, specifically PuLP and OR-Tools. This layer takes the loaded instance data and produces route/mode decisions under constraints such as deadlines, capacities, and terminal transfers.
5. Heuristic path
The heuristics/ directory contains alternative solution approaches:
- dijkstra_router.py for shortest-path style routing
- Tabu search Heuristik.py for a metaheuristic search
These are separate from the exact model and likely operate on the same domain data but with a faster, approximate decision process.
6. Experimentation and benchmarking
experiments/ is the evaluation subsystem. run_experiments.py appears to orchestrate solver runs, sensitivity analyses, or scenario sweeps. compare_solver_heuristic.py explicitly compares exact and heuristic approaches. The results/ folder stores generated CSV/MD outputs, making experiments reproducible and separable from core model code.
7. Data flow across the system
The main flow is: dataset JSON files → data_loader/data_models → exact model or heuristic solvers → experiment scripts → result tables/plots. This is the key architecture boundary to capture in a diagram: instance data is transformed into a domain representation, then consumed by two different solution strategies.
8. Analysis and presentation layer
The notebooks/ directory contains exploratory and validation notebooks such as dijkstra_vs_solver.ipynb, multimodal_routing.ipynb, and scaling_tests.ipynb. These are not part of the core runtime; they sit on top of the solver/data layers for analysis, debugging, and presentation of findings.
9. Documentation and thesis output
documentation/ is a Typst-based document tree, with chapters like introduction, implementation, results, and conclusion. This suggests the repository doubles as the project’s thesis/report source. The presentations/ folder also uses Typst for slides or pitch material.
10. Validation and CI
The project has GitHub Actions CI (.github/workflows/ci.yml) and at least one test file (tests/test_run_experiments.py). The test boundary appears focused on validating experiment execution rather than a broad unit-test suite. This is important because it indicates the repository’s quality gate is centered on reproducible computations.
11. Supporting metadata and tooling
pyproject.toml and requirements.txt define the Python environment. README.md and literature/ support the research workflow, with sources.bib and a literature summary feeding the documentation. These are supporting assets rather than runtime components.
12. How to draw the architecture
A correct diagram should show four major blocks:
- Instance/data preparation (dataset/, data_collector.py)
- Core freight-routing model (freight_routing/)
- Alternative heuristics and benchmarking (heuristics/, experiments/)
- Research outputs (results/, notebooks/, documentation/, presentations/)
The most important dependency arrows go from the dataset into the core package, then outward into solver/heuristic experiment pipelines, and finally into stored results and documentation.
Main entry points: run_experiments.py Run experiments · model.py MILP model · data_models.py Domain models · results Results tables
Components 18
Instance prep
Transport-network instances and preprocessing into domain objects.
- Network data · Prepared freight-network datasets used as the main input boundary.
dataset - Collector · Builds or preprocesses instance data for the dataset boundary.
dataset/data_collector.py
Core model
Shared freight-routing domain types, loader, exact optimization model, and solution visualization.
- Domain models · Network, shipment, terminal, and transport objects shared across the repository.
freight_routing/data_models.py - Loader · Turns JSON instances into freight-routing domain objects.
freight_routing/data_loader.py - MILP model · Defines the exact multimodal freight mode-choice optimization model.
freight_routing/model.py - Plots · Visualizes or inspects routing and optimization outputs.
freight_routing/visualization.py
Alternatives
Heuristic solvers and experiment orchestration for benchmarking.
- Dijkstra router · Shortest-path style routing approach used as a heuristic baseline.
heuristics/dijkstra_router.py - Tabu search · Tabu-search heuristic for approximate route and mode selection.
heuristics/Tabu search Heuristik.py - Run experiments · Coordinates solver runs, scenario sweeps, and sensitivity analyses.
experiments/run_experiments.py - Compare methods · Compares exact optimization results against heuristic solutions.
experiments/compare_solver_heuristic.py
Research outputs
Results, notebooks, documentation, and presentation artifacts for analysis and thesis writing.
- Results tables · Stored CSV and markdown outputs from computational experiments.
experiments/results - Notebooks · Exploratory notebooks for routing analysis, scaling, and solver comparison.
notebooks - Documentation · Thesis/report source with chapters, appendix, and supporting templates.
documentation - Slides · Presentation materials for pitches or project updates.
presentations
Project tooling
Repository support files for environment, CI, and validation.
- README · Top-level project description and usage guidance.
README.md - CI workflow · Continuous integration workflow for repository validation.
.github/workflows/ci.yml - Tests · Smoke test coverage focused on experiment execution.
tests/test_run_experiments.py - Python env · Project dependency and packaging definitions.
pyproject.toml
Connections 22
- Network data → Collector: raw instances · JSON network data is prepared and curated before loading.
- Network data → Loader: loads · Instance files are parsed into runtime objects.
- Collector → Loader: feeds · Preprocessed instance data enters the loader boundary.
- Loader → Domain models: builds · Loader materializes the domain entities used across the repo.
- Domain models → MILP model: input state · Exact optimization operates on the shared freight domain model.
- Domain models → Dijkstra router: input state · Heuristics reuse the same network and shipment representation.
- Domain models → Tabu search: input state · Metaheuristic search consumes the shared domain objects.
- MILP model → Plots: solution · Optimization outputs are rendered or inspected visually.
- Dijkstra router → Run experiments: baseline · Heuristic results are included in experiment runs.
- Tabu search → Run experiments: baseline · Metaheuristic results are included in experiment runs.
- MILP model → Run experiments: exact runs · The MILP model is orchestrated during experiments.
- Run experiments → Compare methods: compare · Experiment outputs feed solver-versus-heuristic comparison.
- Compare methods → Results tables: writes · Benchmarking produces persisted result tables and summaries.
- Run experiments → Results tables: writes · Experiments export CSV and markdown artifacts.
- Results tables → Notebooks: analyzed in · Stored results are explored in notebooks.
- Results tables → Documentation: reported in · Results are summarized in the thesis/documentation tree.
- README → MILP model: describes · Repository overview documents the core modeling workflow.
- Python env → MILP model: supports · Python dependencies enable the optimization implementation.
- Python env → Run experiments: supports · Experiment scripts depend on the project environment.
- CI workflow → Tests: runs · CI validates the experiment-focused test suite.
- Tests → Run experiments: checks · Tests focus on reproducible experiment execution.
- Slides → Documentation: extends · Presentation material complements the written research output.