Ri7la: Composable VRP Library#

A modern C++20 library for Vehicle Routing Problems
Combining metaheuristics, constraint programming, and mixed-integer programming with a composable attribute system.

Composable Attributes

Runtime composition of problem features. No deep inheritance hierarchies needed.

Composable Attribute System API

Multiple Solvers

GA, MA, VNS, PSO, MIP (CPLEX/HiGHS), CP (CPLEX/OR-Tools) - all unified under one API.

Solvers

Python & C++

Full Python bindings with pip install. Native C++20 performance when you need it.

Getting Started

XCSP3 Export

Export problems to XCSP3 format for interoperability with any CP solver.

https://www.xcsp.org/

Plugin Architecture

Extensible design with plugins for attributes, constraints, solvers, and evaluators.

Plugin System API

Quick Start#

Python

import routing

# Initialize the library
routing.init()

# Load a Solomon CVRPTW instance
problem = routing.load_solomon("data/CVRPTW/Solomon/10/c101.txt")

# Solve with genetic algorithm
solver = routing.create_solver("ga", problem)
solver.set_param_int("iterMax", 5000)

if solver.solve(30.0):  # 30 second timeout
    print(f"Best cost: {solver.get_objective_value():.2f}")

C++

#include <routing/routing.hpp>

int main() {
    routing::Problem problem;

    // Enable CVRPTW attributes
    problem.enableAttributes<
        routing::attributes::GeoNode,
        routing::attributes::Consumer,
        routing::attributes::Stock,
        routing::attributes::Rendezvous,
        routing::attributes::ServiceQuery>();

    // Add depot at origin
    auto* depot = problem.addDepot(0);
    depot->addAttribute<routing::attributes::GeoNode>(0.0, 0.0);
    depot->addAttribute<routing::attributes::Rendezvous>(0.0, 1000.0);

    // Add a client
    auto* client = problem.addClient(1);
    client->addAttribute<routing::attributes::GeoNode>(10.0, 20.0);
    client->addAttribute<routing::attributes::Consumer>(15);
    client->addAttribute<routing::attributes::Rendezvous>(0.0, 200.0);
    client->addAttribute<routing::attributes::ServiceQuery>(5.0);

    // Add vehicle
    auto* vehicle = problem.addVehicle(0);
    vehicle->addAttribute<routing::attributes::Stock>(100);

    // Solve with MIP
    routing::MIPSolver solver(&problem, "highs");
    if (solver.solve(60.0)) {
        std::cout << "Optimal: " << solver.getObjectiveValue() << std::endl;
    }
}

Supported Problem Types#

Problem	Attributes	Description
TSP	`GeoNode`	Traveling Salesman Problem
VRP	`GeoNode`	Vehicle Routing Problem
CVRP	`GeoNode`, `Consumer`, `Stock`	Capacitated VRP
VRPTW	`GeoNode`, `Rendezvous`, `ServiceQuery`	VRP with Time Windows
CVRPTW	`GeoNode`, `Consumer`, `Stock`, `Rendezvous`, `ServiceQuery`	Capacitated VRPTW
TOP	`GeoNode`, `Profiter`	Team Orienteering Problem
PDVRP	`GeoNode`, `Pickup`, `Delivery`	Pickup & Delivery VRP
VRPTWTD	All above + `Synced`	VRPTW with Temporal Dependencies

Available Solvers#

Metaheuristics

Genetic Algorithm (GA)
Memetic Algorithm (MA)
Variable Neighborhood Search (VNS)
Particle Swarm (PSO)
Local Search (LS)

Exact Methods (MIP)

CPLEX MIP
HiGHS MIP (open-source)

Constraint Programming

CPLEX CP Optimizer
OR-Tools CP-SAT
XCSP3 export

Plugin System#

The library uses a modular plugin architecture for maximum extensibility:

Attributes

GeoNode, Consumer, Stock, Rendezvous…

Define problem features

Constraints

RoutingGenerator, CapacityGenerator, TimeWindowGenerator…

Generate solver constraints

Solvers

GASolver, MIPSolver, CPSolver…

Optimization engines

Evaluators

DistanceEvaluator, CapacityEvaluator…

Solution quality metrics

Plugins are auto-registered at startup. Add your own by implementing the interface and using the ROUTING_REGISTER_* macros:

// Custom constraint generator - automatically registered
class MyConstraintGenerator : public IConstraintGenerator {
    std::string name() const override { return "MyConstraint"; }
    void addConstraints(IBackend& backend) override { /* ... */ }
};
ROUTING_REGISTER_GENERATOR(MyConstraintGenerator)

See Plugins for the full guide.

Installation#

Python (pip)

# From the repository
cd python
pip install -e .

# Quick test
python -c "import routing; routing.init(); print(routing.list_solvers())"

C++ (CMake)

# Clone and build
git clone https://github.com/sohaibafifi/routing.git
cd routing
git submodule update --init --recursive

# Configure and build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

# Run tests
ctest --test-dir build --output-on-failure

Documentation#

User Guide

API Reference

API Reference
- C++ API (Doxygen)
- Python API

Citing#

If you use this library in research, please cite:

@software{routing2026,
  author = {AFIFI, Sohaib},
  title = {Rihla: A Composable Vehicle Routing Problem Library},
  year = {2026},
  url = {https://github.com/sohaibafifi/routing}
}

See paper/ for the manuscript and benchmarks.

License: Academic/Research Use | Language: C++20 | Python: 3.9+