FAQ¶
This page collects short answers to common questions about contributing benchmark material and comparing MAMUT-routing conventions with other VRPTW sources.
Why did instance generation and solving move out of the website?¶
The workbench used to run OSM city fetches, CVRP/VRPTW instance generation, and heuristic solving on the public server. These are compute-heavy, long-running jobs; hosting them publicly meant rate limits, timeouts, queueing, and abuse handling that made both the website and the tools worse. Since the project is in an active beta phase, we decoupled the two concerns: the website is now fully static and only visualizes the published benchmark data, while all generation and solving runs on your own machine with the MAMUT-routing-tools suite.
Local runs are faster (your CPU, no shared limits), work offline once a city extract is cached, support much larger instances than the public endpoints ever allowed, and write the generated files directly to your disk. The tools ship a command-line interface plus a local workbench GUI with the same generation flows the website tab used to host.
Quick start: install uv, then run uvx --from mamut-routing-tools mamut-tools --help (the suite is published on PyPI, so nothing needs to be cloned or installed). The uploaded-file visualizer in the public workbench still works; it draws straight-line routes, and road-following rendering for your own data is part of the local tools.
How to download and manipulate instances and BKS¶
The benchmark instances and their best-known solutions (BKS) can be retrieved in two complementary ways. Pick whichever fits your workflow best.
Option A: Install mamut-routing-lib and use its CLI¶
Recommended for selective downloads, programmatic access, and scripting. The library is published on PyPI and ships an optional mamut-routing CLI backed by per-family release archives, so you only pull what you need (typically a few MB to a few hundred MB per family rather than the whole tree).
Install with pip or the uv package manager. The [cli] extra adds the mamut-routing command-line interface:
List, download, and verify benchmark archives from the published GitHub release feed:
# Get help on the CLI
mamut-routing --help
mamut-routing remote --help
mamut-routing <command> --help
# List archives available in the latest release directly from GitHub (requires network)
mamut-routing remote list
# Filter by problem-type and benchmark family
mamut-routing remote list --problem-type CVRP --benchmark-name Poryos2026
# Download and extract one or more archives into ./benchmarks
mamut-routing --benchmarks-dir ./benchmarks remote \
fetch --problem-type CVRP --benchmark-name Poryos2026
# Verify local zip checksums against the remote manifest
mamut-routing --benchmarks-dir ./benchmarks remote verify
Once instances are on disk, list and load them locally:
# List local instances under ./benchmarks
mamut-routing --benchmarks-dir ./benchmarks list \
--problem-type CVRP --benchmark-name Poryos2026
# Print only matching paths (useful for piping into other tools)
mamut-routing --benchmarks-dir ./benchmarks list \
--problem-type CVRP --paths-only
From Python, the same instances can be discovered and loaded directly:
from pathlib import Path
from mamut_routing_lib import discover_benchmark_instances, load_benchmark_instance
items = discover_benchmark_instances(benchmarks_root=Path("./benchmarks"))
instance = load_benchmark_instance("benchmarks/.../poryos-n100-9517368.vrp.json")
A [pyvrp] extra wires up the PyVRP HGS metaheuristic so the same CLI can also solve loaded instances. See the MAMUT-routing-lib README for the full reference.
Option B: Add MAMUT-routing as a git submodule¶
Recommended when you want the entire benchmark tree available offline and pinned to a specific commit, for example to reference a frozen snapshot from a paper or experiment.
git submodule add https://github.com/ANR-MAMUT/MAMUT-routing.git external/MAMUT-routing
git submodule update --init --recursive
Heads-up: the full checkout is on the order of several gigabytes, dominated by VRPTW road-geometry sidecar files (*.meta.json). If you only need a single problem family or a subset of metric variants, mamut-routing-lib's remote fetch command above will be much lighter.
Option C: one instance as a classic CVRPLIB .vrp file¶
Solvers that do not read .vrp.json can take the classic TSPLIB-derived
CVRPLIB text instead. Every static instance (CVRP and VRPTW; not the
time-dependent families, which have no static matrix) can be downloaded in that
format directly from this site: select an instance in a catalog and use the
.vrp ↓ chip of the inspector pane, or the Artifacts card of its record page.
The file is generated in your browser from the published .vrp.json (and, for
the shortest/fastest collection instances, from the sha256-pinned distances
sidecar), so no extra data is stored server-side.
The same writer ships in mamut-routing-lib for batches:
# One instance: writes <name>.vrp next to the source .vrp.json
mamut-routing export vrp path/to/instance.vrp.json
# A whole family, mirrored into an output directory
mamut-routing --benchmarks-dir ./benchmarks export vrp \
--problem-type CVRP --benchmark-name Mamut2026 --output-dir ./vrp-out
The default is EDGE_WEIGHT_TYPE : EXPLICIT with the full matrix, so the
solver sees exactly the published costs (3-decimal floats for the collections,
integers for Dimacs/Ortec, full-precision floats for Sintef); VRPTW files use
TYPE : CVRPTW with TIME_WINDOW_SECTION and SERVICE_TIME_SECTION, the
dialect read by VRPLIB and PyVRP. For euclidean-metric instances a
coordinates-only EUC_2D variant (and, for VRPTW, a Solomon .txt) is also
offered: classic readers then compute nint(euclidean) distances, which are
not the published 3-decimal costs, so BKS values do not transfer to that
variant. Node ids are 1-based, the depot is node 1.
Contributions¶
MAMUT-routing, including its tooling, website, instance collection, and BKS collection, is open-source. Modifications, new benchmark instances, new problem classes, new objective functions, and other contributions are welcome.
Use the GitHub repository to discuss or request changes, propose your help, fix issues, or upload new BKS files directly.
CVRPLib, SINTEF, and DIMACS BKS¶
CVRPLib also lists Solomon and Gehring-Homberger VRPTW instances with BKS. These follow the DIMACS VRPTW benchmark convention: single-objective total-cost minimization over scaled, integerized Euclidean arc costs. They therefore share the contract of our Dimacs2021 family. (An earlier version of this page incorrectly assumed CVRPLib used floating-point arc costs; thanks to Leon Lan for the correction.)
That contract differs from the historic SINTEF VRPTW benchmark, which uses double-precision floating-point arc costs and a hierarchical objective: first minimize the number of vehicles, then minimize travel cost. The DIMACS integerization changes the optimization landscape, so BKS values and routes are only comparable when the complete benchmark contract matches.
As a side note, there appears to be no well-known VRPTW benchmark family combining a mono-cost objective with SINTEF-style double-precision arc costs. This is understandable: floating-point arc costs are harder to compare exactly, since floating-point operations are non-associative. Providing such a contract combination is a possible future addition to the MAMUT-routing collection.
This page is shared with the website: /project/faq/.