Code of the Master-Thesis "Mathematical Modeling for Driver Routing and Shift Planning in Vehicle Relocation Services"

Requirements

Python Dependencies

Required packages are specified in requirements.txt. Create a virtual environment and install dependencies using:

python -m venv .venv

.venv\Scripts\activate # on Windows
source .venv/bin/activate # on MacOS/Linux

pip install -r requirements.txt

Gurobi Solver

An installation of the Gurobi solver is required. Follow the Installation Guidelines for setup instructions.

OpenRouteService API Key

Set up an OpenRouteService API key from HeiGIT and save it in a file called .env in the root directory of the project (see example.env) or set it as the ORS_API_KEY environment variable using:

• Windows:

  set ORS_API_KEY=replace_this_by_ors_api_key

• MacOS/Linux:

  export ORS_API_KEY=replace_this_by_ors_api_key

Note: If no OpenRouteService API key is set as the environment variable ORS_API_KEY, the instance generation relies on the Haversine formula for distance calculations.

Quick Start

1. Generate Instances

First, specify the desired instances in generate_instance_suite.py, then generate instances using:

python generate_instance_suite.py

The instances are saved as JSON files to the instances/ directory together with map visualizations using Folium. Note that previously generated instances are overwritten if the <size> and <seed> combination is the same.

2. Run the Solver

Use main.py to run the solver on the desired instances. Specify the desired instances in the main.py file. This uses the mp_md_VReP_solver_full.py solver.

Note: The solvers/ folder also includes a basic model solver (mp_md_VReP_solver.py) without the breka and shift planning, and ride-along features.

python main.py

3. Compare Ridealong Options

Alternatively, compare_ridealong.py can be used to run and compare the results for one instance with ridealongs disabled vs. enabled.

Usage:

python compare_ridealong.py <instance_path> [time_limit] [tolerance]

4. Analyze Results

analysis.py can be used to analyze solutions. It generates detailed shift planning tables from solver results, including shift timings, routes, working times, and KPIs. Supports multiple output formats (table, detailed, latex).

Project Structure

thesis-code/
├── data/                          # Raw data files
│   └── sharing_stations.csv       # Carsharing station data (Baden-Württemberg)
├── solvers/                       # Optimization solvers
│   ├── mp_md_VReP_solver.py       # Basic multi-period multi-depot VReP solver
│   └── mp_md_VReP_solver_full.py  # Full-featured solver with all options
├── utility/                       # Utility modules
│   ├── real_world_generation.py   # Instance generation from real-world data
│   ├── map_visualization.py       # Folium-based map visualization
│   ├── result_stats.py            # Solution analysis and statistics
│   └── utils.py                   # General utility functions
├── instances/                     # Generated problem instances (JSON + HTML maps)
├── results/                       # Solver results and solution files (JSON + HTML maps)
├── generate_instance_suite.py     # Script to generate multiple instances
├── main.py                        # Main solver execution script
├── compare_ridealong.py           # Compare ridealong enabled vs disabled
├── analysis.py                    # Generate shift planning tables from results
├── requirements.txt               # Python package dependencies
└── .env                           # Environment variables (API keys)

Data Source

This project uses data licensed under the Data License Germany – Attribution – Version 2.0.

• Dataset Name: Gebündelte Daten Carsharing Baden Württemberg
• Provider: MobiData BW
• Version: 2020-08-31
• Last Updated: 23. October 2025, 12:21 (UTC+02:00)
• Data obtained from: MobiData BW
• License Notice: Data License Germany – Attribution – Version 2.0

Notice regarding modifications: The dataset is stored in its original format (sharing_stations.csv). Data processing, filtering, and transformation occur during the instance generation process (see real_world_generation.py) and do not modify the source file.