RouteOpt: An Open-Source Modular Exact Solver for Vehicle Routing Problems

This archive is distributed in association with the INFORMS Journal on Computing under the GPLv3 license (see LICENSE).

The software and data in this repository are a snapshot of the software and data used in the paper "RouteOpt: An Open-Source Modular Exact Solver for Vehicle Routing Problems" by Zhengzhong You and Yu Yang.

Cite

To cite the contents of this repository, please cite both the paper and this archive using their DOIs.

https://doi.org/10.1287/ijoc.2025.1415

https://doi.org/10.1287/ijoc.2025.1415.cd

BibTeX for citing this archive:

@misc{you2025routeopt,
  author =        {You, Zhengzhong and Yang, Yu},
  publisher =     {INFORMS Journal on Computing},
  title =         {{RouteOpt: An Open-Source Modular Exact Solver for Vehicle Routing Problems}},
  year =          {2025},
  doi =           {10.1287/ijoc.2025.1415.cd},
  url =           {https://github.com/INFORMSJoC/2025.1415},
  note =          {Available for download at https://github.com/INFORMSJoC/2025.1415}
}

Description

RouteOpt is an open-source, modular exact solver for vehicle routing problems. It supports state-of-the-art branch-price-and-cut algorithms for CVRP and VRPTW and provides modular hooks for branching, cutting, pricing, and variable reduction.

What Is Reproduced

• Re-run CVRP and VRPTW experiments using RouteOpt.
• Regenerate summary tables directly from the archived logs under data/cvrp/ and data/vrptw/.

What Is Not Reproduced Directly

• The VRPSolver binaries themselves are not redistributed. VRPSolver results are provided as archived logs in data/cvrp/VRPSolver/ and data/vrptw/VRPSolver/.

---

Table of Contents

1. Repository Layout
2. System Requirements & Dependencies
3. Quick Start
4. Replication Workflow (Step-by-Step)
5. Generating Tables From Archived Logs
6. Two-Stage Runs (Optional)
7. Notes

Repository layout

.
├── code/RouteOpt/   # RouteOpt source code snapshot used for the paper
├── data/            # Archived logs + table-generation scripts
├── instance/        # Benchmark instances (cvrp/, vrptw/)
├── logs/            # Output from replication.py (created at runtime)
├── replication.py   # End-to-end replication helper
├── LICENSE
└── README.md

System Requirements & Dependencies

• C++20 compiler, CMake, Git, and Ninja.
• Python 3.10+.
• Gurobi installed and licensed (WLS or local license).

Data

The benchmark instances used in the paper are provided under:

• instance/cvrp/ (CVRP: *.vrp)
• instance/vrptw/ (VRPTW: *.txt)

replication.py passes absolute paths to the solver, so you do not need to copy instances into the application folder. For manual runs, you can either pass the absolute path from instance/ or copy files into code/RouteOpt/packages/application/cvrp/instance/.

The data/ directory is reserved for paper artifacts (tables, logs, and auxiliary datasets) and may be populated later. This repository also includes best-known upper bounds in data/ub_cvrp.txt and data/ub_vrptw.txt.

Quick Start

Working‑directory rule: run each helper from the folder where it resides.

1. Run the solver and generate fresh logs:

python3 replication.py --gurobi-root /path/to/gurobi

2. Generate tables directly from the archived logs (no solver run needed):

cd data
python3 generate_updated_tables.py > summary_tables.tex

Replication Workflow (Step-by-Step)

This section provides end-to-end steps to build the solver and run the CVRP and VRPTW instances used in the paper. The three open CVRP instances are skipped by default. macOS, Windows, and Linux are supported.

1) Quick replication (recommended)

Use the provided replication script to build, configure templates, and run all instances with logs:

python3 replication.py --gurobi-root /path/to/gurobi

Logs are written under logs/<timestamp>/. Inside each run folder:

• build_deps.log – output from build.py
• inspect_cvrp.log / inspect_vrptw.log – template configuration output
• cvrp_<instance>.log – per‑instance CVRP run logs
• vrptw_<instance>.log – per‑instance VRPTW run logs
• manifest.json – summary of the run (timestamp, log root, instance dirs, and missing instances)

The replication script automatically uses best‑known upper bounds from data/ub_cvrp.txt and data/ub_vrptw.txt if those files are present. Lines are formatted as:

InstanceName UB

Example:

A-n62-k8 1288
C204 825

Common options:

• --skip-build-deps
  Skips code/RouteOpt/build.py. Use this if you have already built the dependencies or want to manage builds manually.

• --skip-cvrp / --skip-vrptw
  Skips the corresponding template configuration and instance runs. This is useful for narrowing to a single problem class.

• --include-open-cvrp
  Includes the three open CVRP instances. These are computationally intensive and typically require HPC resources.

• --instance-root /path/to/instance
  Uses a custom instance root containing cvrp/ and vrptw/. You can also override just one side with --cvrp-instance-dir or --vrptw-instance-dir.

• --cvrp-template / --vrptw-template
  Selects the template under templates/ (e.g., benchmarks_tw_capmain.txt).

• --max-instances N
  Runs at most N instances per problem class (useful for quick smoke tests).

2) Manual replication (step-by-step)

2.1) Build dependencies (once)

cd code/RouteOpt
python3 build.py

When prompted, enter your Gurobi installation path (examples):

• macOS: /Library/gurobi1300/macos_universal2
• Linux: /opt/gurobi1300/linux64
• Windows: C:\gurobi1300\win64

2.2) Configure + build CVRP (template-driven)

cd code/RouteOpt/packages/application/cvrp
python3 inspect_code.py benchmarks_cvrp.txt

This updates macro files and runs build.sh to compile.

If build.sh fails on macOS because nproc is missing, replace it with sysctl -n hw.ncpu, or run CMake manually.

2.3) Run CVRP instances

cd code/RouteOpt/packages/application/cvrp
./bin/benchmarks_cvrp /path/to/2025.1415/instance/cvrp/A-n62-k8.vrp -u 1288

Replace the instance name and -u as needed (the paper uses best-known UBs; you can omit -u if not available). If you used a different template name, the binary name under bin/ will match that template.

2.4) Configure + build VRPTW (template-driven)

For VRPTW:

cd code/RouteOpt/packages/application/cvrp
python3 inspect_code.py benchmarks_tw_single.txt

Use benchmarks_tw_capmain.txt for type-1 instances and benchmarks_tw_single.txt for type-2 instances. With replication.py, choose the VRPTW template via --vrptw-template.

2.5) Run VRPTW instances

cd code/RouteOpt/packages/application/cvrp
./bin/benchmarks_tw_single /path/to/2025.1415/instance/vrptw/C204.txt -u 825

Generating Tables From Archived Logs

All scripts in this section use the existing log files already included under:

• data/cvrp/RouteOpt/ and data/cvrp/VRPSolver/
• data/vrptw/RouteOpt/ and data/vrptw/VRPSolver/

Run each script from data/ so its relative paths resolve correctly.

1) Summary tables (CVRP + VRPTW)

cd data
python3 generate_updated_tables.py > summary_tables.tex

This produces LaTeX tables (printed to stdout) that summarize CVRP and VRPTW performance, and uses both RouteOpt and VRPSolver logs.

2) Instance‑level CVRP table

cd data
python3 get_cvrp.py > cvrp_instance_table.tex

3) Instance‑level VRPTW table

cd data
python3 get_vrptw.py > vrptw_instance_table.tex

4) Open‑instance table (optional)

If you have the open‑instance logs and the tally file:

Download the open_instance_logs release ZIPs into data/, unzip them (large files; this may take time), then run python3 tally_open_instance.py X-n313-k71 (repeat for X-n359-k29 and X-n384-k52) before generating the open‑instance table.

cd data
python3 get_open_table.py

This writes metrics_table.tex in data/.

Two-Stage Runs (Optional)

Two-stage runs write node snapshots in stage 1 and reload them in stage 2.

1. Enable node output in code/RouteOpt/packages/application/cvrp/src/main/include/cvrp_macro.hpp:

constexpr bool IF_WRITE_NODE_OUT{true};

2. Rebuild (via inspect_code.py or build.sh) and run normally. Node files are written to code/RouteOpt/packages/application/cvrp/nodes/ with names like:

<instance>_<counter>_G<memory>.node

3. Run stage 2 by passing the node file name with -b:

./bin/benchmarks_cvrp /path/to/2025.1415/instance/cvrp/A-n62-k8.vrp -b A-n62-k8_0_G160000.node

If -b is not provided, the solver builds a fresh root node as usual.

Notes

• Open CVRP instances (X-n313-k71, X-n359-k29, X-n384-k52) are computationally intensive and typically require HPC resources. They are excluded from the default replication workflow (use --include-open-cvrp to run them).
• Build and usage details are in code/RouteOpt/README.md.
• Online documentation: https://zhengzhong-you.github.io/RouteOpt-Docs/
• Development repository: https://github.com/Zhengzhong-You/RouteOpt

License

GPLv3. See LICENSE.

Contact

Zhengzhong You (ricky.you.or@gmail.com), Yu Yang (yu.yang@ise.ufl.edu)