REQreate 🚌

REQreate is a tool to generate instances for on-demand transportation problems. Such problems consist of optimizing the routes of vehicles according to passengers' demand for transportation under space and time restrictions (requests). REQreate is flexible and can be configured to generate instances for a large number of problems in this problem class. For example, the Dial-a-Ride Problem (DARP) and On-demand Bus Routing Problem (ODBRP). The tool makes use of real-life networks from OpenStreetMaps to generate instances for an extensive catalogue of existing and upcoming on-demand transportation problems.

Installation

Requires Python 3.11 or newer (osmnx 2.x does not support older versions).

pip install "reqreate[app]"

If you use conda, create a fresh environment rather than reusing an old one — environments built for earlier versions of this tool usually have a Python older than 3.11 and pinned packages that conflict:

conda create -n reqreate python=3.11 -y
conda activate reqreate
pip install "reqreate[app]"

Check it worked:

reqreate --version

Optional extras

pip install "reqreate[app]"

The parallel extra installs ray. Until recently compute_distance_matrix shadowed the imported module with a dummy and ran sequentially regardless; that is fixed, so the distance-matrix work now really is handed to ray when the extra is installed. Results are identical either way (verified value-by-value and dtype-by-dtype on a synthetic graph).

It is not necessarily faster, and we have not measured a speedup on a real city. On a 4-core machine a synthetic 1500-node graph took 20s sequentially and 33s through ray, because starting ray and shipping the graph to the workers costs more than the shortest paths save at that size. Larger networks have more work to amortise that over, but until someone measures one, treat the extra as experimental and leave it out if in doubt.

Quick start: the web interface

The output is written to the directory you run the command from, so start in an empty folder:

mkdir my-instances
cd my-instances
reqreate app

Your browser opens at http://localhost:8501. Then:

1. Choose a problem type (DARP or ODBRP; Patient Transport is temporarily unavailable while a bug is fixed)
2. Enter a location, for example Aachen, Germany
3. Set the number of requests
4. Click Generate, and leave the browser tab open

Start with a small number of requests (around 20) the first time you try a new city. Almost all of the running time goes into processing the street network rather than into the requests themselves, so a 20-request run costs about the same as a large one. What it buys you is a check that the pipeline works for that location before you commit to a full-size run.

Expect hours, not minutes. Downloading the network takes a few minutes, but the distance and travel-time matrices that follow are the expensive part, and they scale with the size of the city rather than the number of requests. A 20-request run for Aachen, Germany took about 90 minutes end to end on a single core, most of it in those matrices. The parallel extra may help on large networks, but no speedup has been measured; see the note above.

Runs of the same location afterwards are quicker, because the OpenStreetMap responses are cached in a cache/ folder next to the output.

Desktop window

To open the interface in a native desktop window rather than a browser tab:

pip install "reqreate[app,desktop]"
reqreate app --window

On Linux, pywebview requires WebKitGTK (python3-gi gir1.2-webkit2-4.1 on Debian/Ubuntu) or the Qt backend.

Where the output goes

Files are written to a folder named after the location you entered, inside the directory you launched from:

my-instances/
└── Aachen, Germany/
    ├── csv_format/           generated instances
    ├── json_format/
    ├── csv/                  network data: stops, zones, POIs, matrices
    ├── graphml_format/       street network
    ├── travel_time_matrix/
    ├── images/               maps and heatmaps
    ├── logs/
    └── pickle/

The interface also offers the whole folder as a single ZIP download.

Command line

Generate from a JSON configuration file or a folder of configurations without the interface:

reqreate generate my_config.json
reqreate generate examples/ODBRP_benchmark_configuration_files/my_set/ --skip-existing --continue-on-error

When given a folder, REQreate processes its .json files in sorted order and ignores macOS ._* files. --skip-existing skips a configuration when its first generated CSV already exists. --continue-on-error reports failures, continues with the remaining configurations, and prints a summary (returning a non-zero status if any config failed). Use -o/--output to select the output subfolder. reqreate generate --help lists every option.

Attributes and parameters that define an instance are described in a configuration file given as input to REQreate. The syntax used is JSON. Each configuration file can generate one or more instances. See examples/basic_examples for example configuration files.

Troubleshooting

"Connection refused" or other Overpass API errors

If generation fails with a connection error mentioning overpass-api.de, the public OpenStreetMap query servers are refusing or rate-limiting the request. This is unrelated to the location you asked for — the same run usually succeeds if you retry a few minutes later.

REQreate retries and fails over across several mirrors automatically. If none of them are reachable, point it at an Overpass instance you can reach:

# Linux / macOS
export REQREATE_OVERPASS_URL=https://overpass.kumi.systems/api/interpreter

# Windows
set REQREATE_OVERPASS_URL=https://overpass.kumi.systems/api/interpreter

Any instance you set this way must hold planet-wide data. A regional Overpass mirror answers a query for a place it does not cover with an empty result rather than an error, which would produce an instance with no network in it.

To check whether Overpass is reachable from your machine at all:

python -c "import requests; print(requests.get('https://overpass-api.de/api/status', timeout=30).text[:300])"

The install fails, or reqreate is not found

Almost always a Python version problem. Check with python --version; it must be 3.11 or newer. If you are in a conda environment created for an older version of this tool, make a fresh one as shown under Installation.

Running it hosted

The repository includes a Dockerfile for deploying the interface to Hugging Face Spaces — see the deployment guide.

Running locally is recommended over a hosted deployment. OpenStreetMap downloads then leave from your own IP address rather than one shared with every other user of a hosting platform, and a shared address is what gets requests refused or rate-limited by the public Overpass API.

Features

• 🌍 Real-world networks from OpenStreetMap
• 🚍 Flexible configuration for various on-demand transport problems
• 📊 Multiple output formats (CSV, JSON, GraphML, Pickle)
• 🎯 Realistic request patterns based on POI density
• ⏱️ Accurate travel times using actual road speeds
• 🗺️ Interactive maps with request distribution and demand heatmaps
• 🖥️ User-friendly web interface for easy instance generation

Output files

REQreate generates comprehensive datasets including:

• Bus station locations
• Network topology (walk + drive)
• Passenger requests with time windows
• Travel time matrices
• Zone definitions
• Points of Interest (POIs)
• Network visualizations

Development

To work on REQreate itself, install from a checkout in editable mode:

git clone https://github.com/michellqueiroz-ua/instance-generator.git
cd instance-generator
pip install -e ".[app]"

Citing REQreate

If you use REQreate in your research, please cite:

Queiroz, M., Lucas, F., & Sörensen, K. (2024). Instance generation tool for on-demand transportation problems. European Journal of Operational Research, 317(3), 696–717. https://doi.org/10.1016/j.ejor.2024.03.006

@article{queiroz2024reqreate,
  title   = {Instance generation tool for on-demand transportation problems},
  author  = {Queiroz, Michell and Lucas, Flavien and S{\"o}rensen, Kenneth},
  journal = {European Journal of Operational Research},
  volume  = {317},
  number  = {3},
  pages   = {696--717},
  year    = {2024},
  doi     = {10.1016/j.ejor.2024.03.006}
}

GitHub's "Cite this repository" button uses CITATION.cff.

Data and licenses

The REQreate code is released under the MIT License.

REQreate downloads its networks and points of interest from OpenStreetMap at run time; no OpenStreetMap data is included in this repository. Networks, travel-time matrices and instances generated with REQreate are derived from OpenStreetMap data:

Map data © OpenStreetMap contributors, available under the Open Database License (ODbL).

If you publish generated networks or instances, keep this attribution and follow the ODbL terms for the derived data. See NOTICE for details.

The legacy/ folder holds archived research scripts that analysed third-party trip datasets (NYC TLC, Chicago TNP, Uber Movement and others). Those datasets are not included.

Questions? Do not hesitate to send an e-mail to:

michell.queiroz@uantwerpen.be