ExVrp
Elixir bindings for PyVRP, a state-of-the-art Vehicle Routing Problem (VRP) solver.
Uses the same C++ core as PyVRP via NIFs for high-performance solving of CVRP, VRPTW, multi-depot, heterogeneous fleet, prize-collecting, and multi-trip problems.
Installation
Add ex_vrp to your dependencies in mix.exs:
def deps do
[
{:ex_vrp, "~> 0.7"}
]
end
Precompiled NIF binaries are available for Linux (x86_64) and macOS (ARM). On other platforms, a C++20 compiler is required.
Quick Start
model =
ExVrp.Model.new()
|> ExVrp.Model.add_depot(x: 0, y: 0)
|> ExVrp.Model.add_vehicle_type(num_available: 2, capacity: [100])
|> ExVrp.Model.add_client(x: 10, y: 10, delivery: [20])
|> ExVrp.Model.add_client(x: 20, y: 0, delivery: [30])
|> ExVrp.Model.add_client(x: 0, y: 20, delivery: [25])
{:ok, result} = ExVrp.solve(model, max_iterations: 1000, seed: 42)
result.best.routes #=> [[2, 1, 3]]
result.best.distance #=> 68
result.best.is_feasible #=> true
Route entries are location indices, not client indices — locations are ordered
[depots..., clients...], so with one depot client n is location n + 1.
Features
- Parallel multi-start solving (automatic core utilization)
- Time windows, service durations, and shift constraints
- Multi-dimensional capacity (weight, volume, etc.)
- Prize-collecting with optional clients
- Multi-trip routes with depot reloads
- Same-vehicle grouping constraints
- Custom distance/duration matrices
- Configurable stopping criteria
- Progress callbacks
See the full documentation for detailed API reference and examples.
Usage rules
ExVrp ships a usage-rules.md describing the semantics that are easy to get wrong
from the type specs alone — location index offsets, capacity dimensions, vehicle time windows,
optional clients, and the cost model. If your project uses
usage_rules, list :ex_vrp in your project config and sync:
defp usage_rules do
[file: "CLAUDE.md", usage_rules: [:ex_vrp]]
end
mix usage_rules.sync
Development
Prerequisites
- Elixir 1.18+
- C++20 compiler (gcc 11+ or clang 14+)
- Make
Setup
mix deps.get
mix compile
mix test
mix compile downloads a precompiled NIF from a GitHub release. When changing anything under
c_src/, force a local build or your changes silently have no effect:
EX_VRP_FORCE_BUILD=1 mix compile
License
MIT License - see LICENSE file.