mamut-tools (MAMUT-routing-tools)¶
The local generation and solving suite of MAMUT-routing-tools: OpenStreetMap city acquisition, the road-graph engine, per-instance generation (CVRP, VRPTW and the time-dependent twins), converters, BKS route geometry, solving, and the local workbench GUI.
The reference below is generated from the Typer application at build time.
mamut-tools¶
Local MAMUT-routing tool suite: OSM acquisition, road-graph engine, route geometry, and instance generation.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--version, -V |
boolean | Show the installed version and package location, then exit. | None |
--help |
boolean | Show this message and exit. | False |
Subcommands
- convert: Converters for external benchmark distributions.
- generate: Interactive CVRP/VRPTW instance generation on city road graphs.
- geometry: BKS route-geometry materialization.
- gui: Local workbench GUI (loopback server owned by the CLI).
- osm: OSM city acquisition (Nominatim + Overpass).
- roadgraph: Road-graph engine (OpenStreetMapX-compatible construction).
- solve: Solve an instance: PyVRP via mamut-routing-lib, or KAYROS for TD instances.
mamut-tools convert¶
Converters for external benchmark distributions.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- blauth2024: Convert the Blauth et al. 2024 delivery-only instances into the canonical Blauth2024 family.
mamut-tools convert blauth2024¶
Convert the Blauth et al. 2024 delivery-only instances into the canonical Blauth2024 family.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-dir |
path | Family directory to write into (benchmarks/TDVRPTW/Blauth2024 or a preview dir). | _required |
--sizes |
text | Comma-separated sizes to convert. | 10,500 |
--cities |
text | Comma-separated upstream city names, or 'all'. | all |
--upstream-commit |
text | Upstream git commit recorded in provenance (default: read from the checkout). | None |
--verify / --no-verify |
boolean | Re-load every emitted instance and re-check the atf_sha256 pin. | True |
--help |
boolean | Show this message and exit. | False |
mamut-tools generate¶
Interactive CVRP/VRPTW instance generation on city road graphs.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- derive-td: Derive the TDVRP + TDVRPTW twins of a generated instance (traffic -> ATFs -> TW lift).
- derive-vrptw: Derive the fastest-metric VRPTW twin of an already generated CVRP base.
- materialize-distances: Rebuild the distance sidecars a large instance ships as pins rather than bytes.
- preview: Preview a selection as GeoJSON (no artifacts written).
- single: Generate one instance (3 metric .vrp files + meta + manifest + .vrp.json).
mamut-tools generate derive-td¶
Derive the TDVRP + TDVRPTW twins of a generated instance (traffic -> ATFs -> TW lift).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--model |
text | Traffic model: bpr or wave. | bpr |
--intensity |
text | Traffic intensity: light, moderate, or heavy. | moderate |
--all, --all-combos |
boolean | Derive all model x intensity combinations (6 twins each). | False |
--seed |
integer | N/A | 42 |
--force / --no-force |
boolean | Overwrite existing twins/sidecars. | False |
--help |
boolean | Show this message and exit. | False |
mamut-tools generate derive-vrptw¶
Derive the fastest-metric VRPTW twin of an already generated CVRP base.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--tw-method |
text | N/A | route_centered |
--seed |
integer | N/A | 0 |
--help |
boolean | Show this message and exit. | False |
mamut-tools generate materialize-distances¶
Rebuild the distance sidecars a large instance ships as pins rather than bytes.
Instances above the size where a distance matrix is worth storing publish the road graph and the matrix's sha256, not the matrix. This recomputes them from the committed road sidecar and refuses to write anything whose digest does not match the pin, so what lands on disk is byte-for-byte what the instance was published against.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--collection-root |
path | Collection root; found from the marker file above the instance when omitted. | None |
--force / --no-force |
boolean | Rebuild sidecars that are already present. | False |
--help |
boolean | Show this message and exit. | False |
mamut-tools generate preview¶
Preview a selection as GeoJSON (no artifacts written).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--n |
integer | N/A | 50 |
--method |
text | N/A | poi_categories |
--seed |
integer | N/A | 0 |
--depot-mode |
text | N/A | center |
--customer-mode |
text | N/A | random_clustered |
--osm-path |
path | N/A | None |
--output-dir |
path | N/A | None |
--help |
boolean | Show this message and exit. | False |
mamut-tools generate single¶
Generate one instance (3 metric .vrp files + meta + manifest + .vrp.json).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--n |
integer | Number of customers. | 50 |
--method |
text | Sampling method: poi_categories, parametric_attach, hybrid. | poi_categories |
--seed |
integer | N/A | 0 |
--demand-type |
integer range (between 1 and 7) |
N/A | 7 |
--avg-route-size |
integer range (between 1 and 7) |
N/A | 4 |
--depot-mode |
text | random, center, corner. | center |
--customer-mode |
text | random, clustered, random_clustered. | random_clustered |
--vrptw / --no-vrptw |
boolean | Also derive the fastest-metric VRPTW twin. | False |
--tw-method |
text | route_centered or reachable_interval. | route_centered |
--osm-path |
path | Explicit OSM extract path. | None |
--output-dir |
path | Workspace directory (default: the resolved workspace). | None |
--help |
boolean | Show this message and exit. | False |
mamut-tools geometry¶
BKS route-geometry materialization.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- materialize-plan: Materialize a route-geometry group plan (website build contract).
mamut-tools geometry materialize-plan¶
Materialize a route-geometry group plan (website build contract).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--repo-root |
path | MAMUT-routing repo root the plan paths are relative to. | _required |
--result-dir |
path | Directory for per-group result files. Prints to stdout when omitted. | None |
--help |
boolean | Show this message and exit. | False |
mamut-tools gui¶
Local workbench GUI (loopback server owned by the CLI).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- run: Run the GUI server in the foreground (development mode).
- start: Start the workbench GUI server as a managed background process.
- status: Show the GUI server status.
- stop: Stop the workbench GUI server.
mamut-tools gui run¶
Run the GUI server in the foreground (development mode).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--port |
integer | N/A | 8788 |
--output-dir |
path | N/A | None |
--help |
boolean | Show this message and exit. | False |
mamut-tools gui start¶
Start the workbench GUI server as a managed background process.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--port |
integer | Port to bind (0 = pick a free one). | 0 |
--output-dir |
path | Workspace directory. | None |
--open / --no-open |
boolean | Open the tokened URL in the default browser. | True |
--help |
boolean | Show this message and exit. | False |
mamut-tools gui status¶
Show the GUI server status.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-dir |
path | N/A | None |
--help |
boolean | Show this message and exit. | False |
mamut-tools gui stop¶
Stop the workbench GUI server.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-dir |
path | N/A | None |
--help |
boolean | Show this message and exit. | False |
mamut-tools osm¶
OSM city acquisition (Nominatim + Overpass).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- fetch-city: Download a filtered, road-graph-compatible OSM extract for a city.
- refresh-pois: Backfill amenities mapped as ways and relations into existing extracts.
- validate: Reject incomplete or Overpass-error extracts before graph construction.
mamut-tools osm fetch-city¶
Download a filtered, road-graph-compatible OSM extract for a city.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--country |
text | Optional country to disambiguate the geocode. | `` |
--osm-dir |
path | Directory for the downloaded |
osmdata |
--padding-km |
float | Extra bbox padding in km. | 0.0 |
--max-radius-km |
float | Clamp the administrative bbox to a square of this radius around the place's geocode point (0 = no clamp). | 0.0 |
--profile |
text | Data profile: generation, road_cache, or full. | generation |
--poi-category |
text | POI amenity category to include (repeatable; generation profile only). | None |
--tile-cache-dir |
path | Persistent validated Overpass tile cache (default: |
None |
--tile-cache / --no-tile-cache |
boolean | Reuse successful tiles across interrupted or repeated downloads. | True |
--help |
boolean | Show this message and exit. | False |
mamut-tools osm refresh-pois¶
Backfill amenities mapped as ways and relations into existing extracts.
Extracts fetched before ways and relations were queried hold only the POIs mapped as nodes -- roughly two thirds of a real city's amenities -- and nothing invalidates them, so generation keeps drawing from the smaller pool. Only the amenity query is re-run: the road network in each file is left alone, so this is far cheaper than re-fetching the cities.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--osm-dir |
path | Directory holding the |
None |
--output-dir |
path | Workspace directory, when --osm-dir is not given. | None |
--check |
boolean | Report coverage and exit without downloading anything. | False |
--all |
boolean | Refresh every extract, not only those missing way-mapped POIs. | False |
--poi-category |
text | Amenity category to backfill (repeatable; default: the full catalog). | None |
--tile-cache / --no-tile-cache |
boolean | Reuse successful tiles across interrupted or repeated runs. | True |
--help |
boolean | Show this message and exit. | False |
mamut-tools osm validate¶
Reject incomplete or Overpass-error extracts before graph construction.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
mamut-tools roadgraph¶
Road-graph engine (OpenStreetMapX-compatible construction).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- info: Build the road graph and print vertex/edge statistics.
mamut-tools roadgraph info¶
Build the road graph and print vertex/edge statistics.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--only-intersections / --all-nodes |
boolean | N/A | True |
--trim / --no-trim |
boolean | N/A | True |
--help |
boolean | Show this message and exit. | False |
mamut-tools solve¶
Solve an instance: PyVRP via mamut-routing-lib, or KAYROS for TD instances.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--time-limit |
integer | Wall-clock budget in seconds. | 30 |
--seed |
integer | N/A | 42 |
--objective |
text | MonoCost or HierarchicalVehicleCost (VRPTW only; kayros solves Duration). | MonoCost |
--solver |
text | pyvrp (CVRP/VRPTW) or kayros (TDVRPTW/TDVRP Duration, exact/anytime BPC-seeded). | pyvrp |
--update-bks / --no-update-bks |
boolean | Write a BKS file next to the instance when the solution improves it. | False |
--help |
boolean | Show this message and exit. | False |