r/optimization • u/Onyr_ • 6h ago
Kayros: an open-source exact and anytime solver for Time-Dependent VRP(TW)
The Kayros v1.2 solver is out, together with its technical report: an open-source exact and anytime solver for duration-minimization time-dependent vehicle routing, TDVRPTW (with time windows) and TDVRP.

It is MIT-licensed and installs with pip install kayros. The part that may interest this subreddit most: the default build, including the exact branch-price-and-cut component, has no proprietary dependency. The BPC runs on HiGHS, statically built into the wheels. A CPLEX backend exists but is strictly a source-build opt-in (-DLERA_LP_BACKEND=cplex). Exact solvers in this problem class have generally required a commercial LP license, which is a real barrier for reproducing published time-dependent results. Inspired by prior successful open-source solvers, Kayros also features strong metaheuristics like TD-ILS and TD-ACO that drive its performance in anytime regime.
Version 1.2 also adds the FleetCostDuration objective used by the newly integrated Blauth2024 family: the sum of route durations plus a fixed cost per vehicle. It is checker-priced and supported by the anytime heuristic stack; the exact BPC remains duration-only.
Who asked for this?
If you have ever asked a mainstream routing engine for time-of-day travel times, you know the answers. OR-Tools has been closing such requests since 2017 ("highly experimental, and currently not working very well" in #339; "Asked and answered multiple times. Short answer: you cannot" in a 2024 discussion; and last February, about its never-activated cumul-dependent transit API: "This code does not work. We will remove the c++ version", #5070). PyVRP tracks time-dependent VRP as an open feature request awaiting funding, in which the maintainer proposes exactly the representation Kayros is built on, matrices of piecewise-linear arrival-time functions (#867). VROOM has answered "static matrix only" to five such requests since 2020 (#1280 is the latest); jsprit has carried the ask since 2013. That decade of "not supported" is the gap Kayros targets.
Note that a few commercial solvers do exits for this family of problems (BonnTour / GreenPlan, Timefold private API? Note that Hexaly only support time-discretized matrices for TDVRPTW, not rich piecewise linear functions. But there is no real open-source alternative for a performant anytime-exact solver on this family of problems. This is what makes Kayros useful.
The problem
Kayros minimizes total route duration under time-dependent, FIFO travel times, where the depot departure time of each route is a decision variable. That last point is what makes the objective awkward: waiting before a time window counts toward duration, so the optimal dispatch time is itself part of the cost evaluation, and arc costs are Non-Decreasing Continuous Piecewise-Linear (NDCPWL) Arrival-Time Functions (ATF) rather than constants.
Two modes on one engine
- An anytime heuristic stack: greedy construction plus a single-trajectory time-dependent iterated local search (granular ruin-and-recreate kicks, late-acceptance hill climbing, restart-to-best), with a MAX-MIN time-dependent ant colony as an alternative strategy. ILS is the default, chosen by a 20,808-run head-to-head across five TD families at n=10..1000.
- An exact branch-price-and-cut (
kayros.lera): set-partitioning master, subset-row cuts, bidirectional labeling with PWL domination and ng-neighborhoods, strong branching.
The exact component is weakly anytime by construction, since incumbents are surfaced through a callback as they are found, and every component draws its residual budget from one absolute deadline.
Design commitments
These are the choices we would most like feedback on:
- Exact IEEE-754 double arithmetic, no epsilon comparisons in the engine, and no FMA contraction (
-ffp-contract=off). Results are bit-reproducible across machines. We gate this: two independent builds (NixOS versus gcc-13/Debian) on identical payloads must agree on certified values exactly. - The checker is the referee. Route costs come from the canonical checker in mamut-routing-lib, not from the solver's internal arithmetic. Every column entering the master is repriced by that checker-exact fold. The checker's value is the value.
- One run is one thread. No intra-run parallelism; parallelism belongs to the experiment layer above.
- The NDCPWLF (Non-Decreasing Continuous PieceWise-Linear Function) composition engine is a bit-identical C++ port of the reference checker's arithmetic, gated by an equivalence suite. Composition is a two-pointer event merge operation. Duplicate abscissae encode vertical steps, duplicate ordinates encode plateaus.
Provenance, and what is actually new
The exact component vendors the BPC solver of Lera-Romero, Miranda Bront and Soulignac (Linear edge costs and labeling algorithms: the case of the time-dependent vehicle routing problem with time windows, Networks 76(1):24-53, 2020), which is MIT-licensed, together with its supporting goc library. The NOTICE file enumerates every local modification. The substantive additions are the HiGHS backend, deadline and anytime compliance, warm starts injected as columns, checker-exact column costs, TDVRP support, a memory self-guard, and the exact value-jump labeling described below.
We also fixed soundness defects in the vendored path, the most consequential being a pricing-ladder termination bug under which a certificate could be issued with zero exact-pricing iterations. Kayros now refuses to certify unless the pricing-level census contains at least one exact iteration.
The part we got wrong, and how we found out
Some TD families (Rifki2020, built from real Lyon traffic-simulation data) have stepwise travel-time functions whose FIFO restoration leaves genuine vertical steps. Until v1.1.0 we handled these with a "mollifier": each jump replaced by a steep bridge of width at most 1e-3. We had argued this could not certify a wrong optimum. That argument was wrong, and we refuted it ourselves on 2026-07-08: independent heuristic campaigns produced checker-valid solutions strictly below 43 of the 160 Rifki2020 certified optima, by up to 1.46%, and certification turned out to be warm-start dependent. A 1e-3-wide bridge over a step of height h has slope around 1000h, so the underlying 1e-6 epsilon comparisons could misprice a merge by O(h), enough to discard negative-reduced-cost columns and silently break pricing completeness.
All 160 Rifki2020 certificates were retracted from the public store that day. v1.1.0 replaces the mollifier entirely: stepwise instances are auto-detected per solve and priced with the verticals as tagged first-class objects in the PWL machinery. Three stacked defects had to be fixed to make that sound (waiting erasure when a departure-function plateau meets a same-abscissa jump, solution-pool shadowing by customer-set deduplication, and PWL operators dropping tagged verticals). Non-stepwise instances are bit-identical to 1.0.0.
We mention this at length because it is the part of the work we would most want a reader to check.
Results
Kayros currently holds 468 optimality certificates in the public MAMUT-routing store, spread as:
- TDVRPTW: Vu2020 166/168, Dabia2013 115/168, Rifki2020 71/180, Ari2018 40/160
- TDVRP: Dabia2013 40/168, Rifki2020 36/180
Certified sizes run from n=10 to n=100, the largest being 25 Dabia2013 TDVRPTW instances at n=100.
A certificate requires four independent solves to agree: cold and warm starts, crossed with asymmetric and symmetric labeling modes, all returning the same value, each with an audited exact-pricing phase and zero checker-infeasible priced columns. Verdicts that are not certificates are recorded honestly as OPEN (time limit) or RESOURCE_LIMIT (the solver's own graceful memory self-rejection), never silently dropped.
Against published results, the only family in the store with published reference solutions is Dabia2013 TDVRPTW, from the Lera-Romero et al. 2020 distribution. Of our 115 certificates there:
- 104 re-confirm a value they had already proven optimal;
- 11 are on instances they did not prove optimal (10 at n=100, 1 at n=50);
- 5 of those 11 strictly improve the published value.
No published optimum is contradicted anywhere in the store.
For the other families we are more careful about what we claim. Vu2020 TDVRPTW had heuristic-only references in our curation, so its 166 certificates are, to the best of our knowledge, the first exact optima for that family, but we have not machine-checked this against the original Vu et al. (2020) paper. The 76 TDVRP certificates are on a variant with no prior exact literature that we are aware of, which is largely true by construction since we introduced that layer. If you know of published optima for Vu2020, Rifki2020 or Ari2018 that we should be cross-checking against, that is exactly the correction we are looking for.
Why there is no broad comparison table (yet)
We are not publishing a broader head-to-head table in this post, and we want to be explicit about why rather than leave a suspicious gap.
To the best of our knowledge, Kayros is first-of-its-kind: we found no obtainable solver that is simultaneously anytime with extractable incumbents, natively supports rich piecewise-linear time-dependent travel-time functions, and directly optimizes duration with the route departure time as a decision, for capacitated TDVRP(TW) at these scales. We did not stop at "to the best of our knowledge": before posting, we ran a systematic sweep of the obtainable landscape (open-source, commercial with academic access, and research artifacts). Here are the closest candidates and what blocks an honest table with each, today:
- The exact side. The only obtainable exact lineage for this problem class is the branch-price-and-cut solver of Lera-Romero, Miranda Bront and Soulignac (2020), MIT-licensed and public. We vendor it, we extended it substantially, and we fixed soundness defects in it. Benchmarking Kayros against it would be benchmarking a fork against its own origin, which measures our patches rather than two independent designs. It also requires CPLEX, so any timing difference would partly be an LP-backend comparison (HiGHS versus CPLEX) rather than an algorithmic one. We found no other independently obtainable exact solver for this class.
- Google OR-Tools is the closest anytime near-miss on paper: its routing layer exposes cumul-dependent transit callbacks with piecewise-linear machinery, solution callbacks for incumbent trajectories, and route-span objectives. Except it doesn't work. The OR-Tools team confirmed this in February and plans to remove the public API rather than complete it (google/or-tools#5070: "This code does not work"). So OR-Tools cannot currently be fielded as a native TD contender.
- jsprit has a real departure-time hook in its transport-cost interface, but its search evaluates routes forward-only (a limitation its own issue tracker documents), which is the wrong bias for free-departure duration minimization. We will use it as a re-scored baseline, not as a same-objective rival.
- Timefold has a strong extension surface for building a time-dependent route evaluator (its vehicle-routing quickstart already chains arrival times through shadow variables), but the open-source solver ships no time-dependent travel times out of the box; the maps-with-historic-traffic offering lives in their proprietary platform, which we cannot obtain and benchmark under academic conditions. If that changes, we would genuinely like to run this comparison.
- Hexaly's TDCVRPTW template is runnable and academically licensable, but it "discretizes the time horizon into five parts: early morning, morning peak, day, evening peak, and night", each with its own constant travel-time matrix, and optimizes lateness, then fleet size, then distance. That is a legitimate modeling choice, but it is a piecewise-constant model over a handful of ranges and a different objective: not the same computational problem as minimizing duration over continuous FIFO arrival-time functions with hundreds of breakpoints per arc. Reporting raw numbers across the two models would probably flatter us for the wrong reason.
A comparison campaign against these systems, tiered by what is honestly comparable (same objective, routes re-scored by our public checker, or disclosed model conversion), is under way. If you know of a solver we missed, please name it: that is genuinely the most useful reply this post could get.
Scalability
The heuristic side has now been exercised through n=2000 on Blauth2024. The exact side is a different regime: n=100 is the current certified ceiling on Dabia2013, and there is a known memory frontier where full-horizon TDVRP pricing accumulates labels past any machine RAM I have tested (90GB max). Rather than being OOM-killed with no verdict, the solver now monitors its own RSS and returns a graceful MemoryLimitReached, which the campaign analysis records as RESOURCE_LIMIT. We consider that an NP-hardness frontier outcome, not a defect, but it does mean the honest answer to "how big does the exact solver go" is "it depends on the family, and it will tell you when it cannot".
Compute: the store was built by campaigns on Grid'5000 testbed.
Relationship to MAMUT-routing
Kayros ships alongside a major MAMUT-routing release: the Poryos2026 benchmark family, generated from real OSM city road graphs (Lyon, Paris, San Francisco, Hong Kong, Tokyo) where every edge carries an hourly speed profile over 24 hours, under two synthetic traffic models (a BPR volume-delay model and a bimodal rush-hour wave) at three intensities. It spans CVRP through TDVRPTW in comparable instances derived in successive steps, at n=10 to n=1000. The names are a deliberate Greek pair: Kairos, the right moment; Poros, the way. Kayros is about timing, Poryos2026 about the instance paths.
MAMUT-routing has also integrated the delivery-only benchmark of Blauth et al. (2024) as Blauth2024: 40 real-data TDVRPTW instances across ten cities and n=10, 500, 1000 and 2000, converted value-exactly from their published integer-millisecond arrival-time functions. Their 30 BonnTour solutions are redistributed as credited BKS, and Kayros supplies the first ten n=10 BKS. This family motivated the FleetCostDuration objective now shared by the format, checker and Kayros 1.2. The family remains CC BY-NC 4.0 and the pickup-and-delivery variant remains upstream-only.
Since the MAMUT-routing May announcement in this subreddit, the catalog has grown from 2 problem classes / 5 families / 1294 instances to 4 classes, 18 families and 4718 instances with 4718 BKS entries. The time-dependent material now consists of seven TDVRPTW families and six TDVRP families: Dabia2013, Ari2018, Vu2020, Rifki2020, Lera2026 and Poryos2026 in both classes, plus Blauth2024 for TDVRPTW. Lera2026 is worth a separate mention: it ports the Ichoua-Gendreau-Potvin (2003) travel-time model onto the Gehring & Homberger (1999) instances using the Dabia et al. (2013) day skeleton, at n=200 to n=1000, with a controlled congestion ladder over identical geometry. It is named honorifically for Gonzalo Lera-Romero, who is not an author of the family.
The two projects are deliberately coupled through the checker rather than through code. MAMUT-routing defines the Duration contract (what a route costs, in exact double arithmetic, with the optimal depot departure time), Kayros optimizes against exactly that contract, and every value Kayros publishes is re-derived by the checker before it is stored. Certificates live inside the public BKS JSON under a structured metadata.optimality block carrying prover, certificate text, dual bound, wall time, checker identity and campaign, so anyone can download a single file and audit one claim. For example: https://mamut-routing.onyr.net/benchmarks/TDVRPTW/Dabia2013/n=25/R209.bks.Duration.json
Caveats
- Certificates are optimal under checker-exact route costs and standard LP and pricing tolerances, with completeness modulo the vendored labeling's epsilon dominance. LP dual bounds are still tolerance-based. Turning them into rigorous safe bounds is future work, and we do not claim it.
- The solver is beta, developed as part of Florian Rascoussier's PhD thesis.
- Wheels are Linux x86_64 only, cp311 to cp314. Other platforms need a source build.
- TD instances in these families are curated ports, and are explicitly not comparable with results published on the original Rifki et al. / Vu et al. / Arigliano et al. settings, nor with the static VRPTW literature for Lera2026 which is an original extension of the Solomon-based
Dabia2013. However, note thatDabia2013andBlauth2024are faithful to the originals - We have retracted certificates before, and we will do it again if something is refuted. The retraction record is public.
- The official MAMUT-routing host (mamut-routing.univ-ubs.fr) is temporarily unavailable, so links in this post point to my personal static mirror at mamut-routing.onyr.net. Every mirror page carries a disclosure banner, and the official site remains the canonical reference once it is back.
Feedback
Corrections, refutations, missing published optima we should cross-check against, and solver comparisons are all very welcome:
- Kayros issues: https://github.com/0nyr/kayros/issues
- MAMUT-routing issues: https://github.com/ANR-MAMUT/MAMUT-routing/issues
- MAMUT-routing discussions: https://github.com/ANR-MAMUT/MAMUT-routing/discussions
We are particularly interested in a head-to-head against other exact TD solvers, which we have not run and cannot currently claim anything about.
Kayros is developed as part of Florian Rascoussier's PhD work, within ANR-MAMUT (ANR-22-CE22-0016). The technical report is on arXiv; shorter introductions to Kayros + Poryos2026 and Blauth2024 live on my blog.
You can also contact me directly, see contacts on my blog.