kayros 0.1.0__tar.gz

kayros-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# scikit-build-core / CMake
+_skbuild/
+CMakeCache.txt
+CMakeFiles/
+compile_commands.json
+
+# Compiled extensions
+*.so
+*.pyd
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Nix
+result
+result-*

kayros-0.1.0/CITATION.cff

@@ -0,0 +1,39 @@
+cff-version: 1.2.0
+title: KAYROS
+message: >-
+  If you use KAYROS, please cite it using the metadata
+  from this file.
+type: software
+authors:
+  - given-names: Florian
+    family-names: Rascoussier
+    alias: Onyr
+    affiliation: IMT Atlantique; INSA Lyon
+    orcid: "https://orcid.org/0009-0005-3253-9814"
+url: "https://github.com/0nyr/kayros"
+repository-code: "https://github.com/0nyr/kayros"
+abstract: >-
+  KAYROS is an exact and anytime solver for duration-minimization
+  time-dependent vehicle routing problems, including TDVRPTW and TDVRP.
+  It combines a C++23 and pybind11 optimization core with an exact
+  non-decreasing continuous piecewise-linear arrival-time engine,
+  checker-refereed route pricing, greedy construction, and a
+  time-dependent ant colony optimization heuristic for the canonical
+  MAMUT-routing benchmark families.
+keywords:
+  - time-dependent vehicle routing problem
+  - TDVRPTW
+  - TDVRP
+  - vehicle routing problem
+  - anytime optimization
+  - ant colony optimization
+  - route duration
+  - piecewise-linear functions
+  - NDCPWLF
+  - solution validation
+  - operations research
+  - combinatorial optimization
+  - routing
+  - research software
+license: MIT
+version: "0.0.1.dev0"

kayros-0.1.0/CMakeLists.txt

@@ -0,0 +1,37 @@
+cmake_minimum_required(VERSION 3.26)
+project(kayros LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# Local-benchmarking builds only: never enabled for shipped wheels/sdists.
+option(KAYROS_NATIVE "Build with -march=native (local benchmarking only)" OFF)
+# CPLEX-based Lera-Romero BPC component: requires a local CPLEX install.
+# The default build must stay free of any proprietary dependency.
+option(KAYROS_WITH_LERA "Build the CPLEX-based exact BPC component" OFF)
+
+find_package(pybind11 CONFIG REQUIRED)
+
+pybind11_add_module(_core
+    cpp/bindings/module.cpp
+    cpp/pwlf/pwlf.cpp
+    cpp/core/route_eval.cpp
+    cpp/heuristics/greedy_makespan.cpp
+    cpp/heuristics/aco.cpp
+)
+target_include_directories(_core PRIVATE cpp)
+target_compile_definitions(_core PRIVATE KAYROS_VERSION="${SKBUILD_PROJECT_VERSION_FULL}")
+# Bit-identical agreement with the Python reference checker requires plain
+# IEEE-754 double arithmetic: no FMA contraction, ever.
+target_compile_options(_core PRIVATE -ffp-contract=off)
+
+if(KAYROS_NATIVE)
+    target_compile_options(_core PRIVATE -march=native)
+endif()
+
+if(KAYROS_WITH_LERA)
+    message(FATAL_ERROR "KAYROS_WITH_LERA is a placeholder: the Lera BPC component lands at milestone M3.7.")
+endif()
+
+install(TARGETS _core DESTINATION kayros)

kayros-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Rascoussier (Onyr)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kayros-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.1
+Name: kayros
+Version: 0.1.0
+Summary: KAYROS — exact & anytime solver for duration-minimization time-dependent vehicle routing (TDVRPTW / TDVRP)
+Author-Email: "Florian Rascoussier (Onyr)" <rascoussier.florian@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Project-URL: Homepage, https://github.com/0nyr/kayros
+Project-URL: Issues, https://github.com/0nyr/kayros/issues
+Project-URL: Benchmarks, https://github.com/ANR-MAMUT/MAMUT-routing
+Requires-Python: >=3.11
+Requires-Dist: mamut-routing-lib>=0.2.0
+Provides-Extra: lera
+Description-Content-Type: text/markdown
+
+# KAYROS
+
+**KAYROS** is an exact & anytime solver for **duration-minimization time-dependent vehicle routing** problems — TDVRPTW (with time windows) and TDVRP — benchmarked on the canonical [MAMUT-routing](https://github.com/ANR-MAMUT/MAMUT-routing) TD instance families.
+
+> Status: **alpha**. v0.1.0 ships an anytime time-dependent Ant Colony Optimization heuristic on an exact non-decreasing continuous piecewise-linear (NDCPWLF) arrival-time engine, benchmarked on all four MAMUT TD families (it seeded the store's initial best-known solutions at scale). The time-dependent local-search layer is next. See the roadmap below.
+
+## Design principles
+
+- **One command install, no proprietary dependency.** The default build is pure open source (C++23 + pybind11). The optional exact branch-price-and-cut component of Lera-Romero et al. (requires CPLEX) is strictly opt-in (`-DKAYROS_WITH_LERA=ON`, source build only) and never ships in wheels.
+- **Exact arithmetic, checker-refereed.** Route durations are computed on NDCPWLF arrival-time functions with exact doubles — no epsilon comparisons. Every solution kayros reports is priced by the reference checker of [`mamut-routing-lib`](https://github.com/ANR-MAMUT/MAMUT-routing); the checker's value is the value.
+- **POD core.** The C++ core is plain structs, flat arrays and free functions — optimization-kernel style, no framework.
+
+## Install
+
+```sh
+pip install kayros
+```
+
+This pulls everything, including the benchmark loaders and the reference checker ([`mamut-routing-lib`](https://pypi.org/project/mamut-routing-lib/)). For development:
+
+```sh
+git clone https://github.com/0nyr/kayros && cd kayros
+pip install -e . --group dev    # pip >= 25.1 (or: uv pip install -e . --group dev)
+```
+
+Requirements: Python ≥ 3.11; building from source (sdist or checkout) additionally needs a C++23 compiler and CMake ≥ 3.26 (fetched automatically by the build backend when missing).
+
+## Usage
+
+```python
+import kayros
+
+# Any MAMUT-routing TD instance (.vrp.json with its .atf.json sidecar next to it)
+instance_path = "benchmarks/TDVRPTW/Dabia2013/n=25/C101.vrp.json"
+solution = kayros.solve(instance_path, time_limit=10.0, seed=42)
+print(solution.duration, solution.num_routes, solution.status)
+
+# Anytime: react to every new incumbent while the solve keeps running
+def on_incumbent(incumbent, routes):
+    print(f"[{incumbent.seconds:7.2f}s] {incumbent.value:.6f} ({incumbent.origin})")
+
+solution = kayros.solve(instance_path, time_limit=60.0, on_incumbent=on_incumbent)
+
+# Feed the MAMUT BKS pipeline: solution.to_benchmark_solution() returns the
+# artifact accepted by mamut_routing_lib.td.bks.save_td_solution_as_bks_if_improved.
+```
+
+`solution.duration` is always the value computed by the reference checker (`mamut_routing_lib.td.check_td_solution`) — never an internal approximation.
+
+## Roadmap (stage 1)
+
+- [x] M3.0 — package scaffold, CI, PyPI wiring
+- [x] M3.1 — NDCPWLF composition engine + POD instance/route core
+- [x] M3.2 — exact equivalence gate against the reference checker (Dabia2013): 513 tests, 336 instances, zero divergences
+- [x] M3.3 — `kayros.solve()`: greedy construction + TD-ACO
+- [x] M3.4 — all four MAMUT TD families × {TDVRPTW, TDVRP}
+- [x] M3.5 — large-scale runs on Grid'5000: seeded the initial best-known solutions for all 1352 MAMUT TD instances
+- [x] M3.6 — anytime API (`on_incumbent`, time budgets) + **v0.1.0 on PyPI**
+- [ ] M3.7 — time-dependent local search layer (LCA-BST move evaluation, Blauth et al. 2024)
+- Later: optional exact BPC (`kayros[lera]`)
+
+## Provenance
+
+KAYROS is developed by [Florian Rascoussier (Onyr)](https://github.com/0nyr) as part of a PhD in operations research (IMT Atlantique / INSA Lyon), under the supervision of Romain Billot, Christine Solnon and Lina Fahed. The NDCPWLF composition engine follows Visser & Spliet (2020)'s move-evaluation theorems; the TD-ACO is a rewrite of the author's heuristic layer originally built on the TDVRPTW solver of Lera-Romero, Rönnqvist & Ljungqvist (2020, MIT-licensed). MIT license.

kayros-0.1.0/README.md

@@ -0,0 +1,64 @@
+# KAYROS
+
+**KAYROS** is an exact & anytime solver for **duration-minimization time-dependent vehicle routing** problems — TDVRPTW (with time windows) and TDVRP — benchmarked on the canonical [MAMUT-routing](https://github.com/ANR-MAMUT/MAMUT-routing) TD instance families.
+
+> Status: **alpha**. v0.1.0 ships an anytime time-dependent Ant Colony Optimization heuristic on an exact non-decreasing continuous piecewise-linear (NDCPWLF) arrival-time engine, benchmarked on all four MAMUT TD families (it seeded the store's initial best-known solutions at scale). The time-dependent local-search layer is next. See the roadmap below.
+
+## Design principles
+
+- **One command install, no proprietary dependency.** The default build is pure open source (C++23 + pybind11). The optional exact branch-price-and-cut component of Lera-Romero et al. (requires CPLEX) is strictly opt-in (`-DKAYROS_WITH_LERA=ON`, source build only) and never ships in wheels.
+- **Exact arithmetic, checker-refereed.** Route durations are computed on NDCPWLF arrival-time functions with exact doubles — no epsilon comparisons. Every solution kayros reports is priced by the reference checker of [`mamut-routing-lib`](https://github.com/ANR-MAMUT/MAMUT-routing); the checker's value is the value.
+- **POD core.** The C++ core is plain structs, flat arrays and free functions — optimization-kernel style, no framework.
+
+## Install
+
+```sh
+pip install kayros
+```
+
+This pulls everything, including the benchmark loaders and the reference checker ([`mamut-routing-lib`](https://pypi.org/project/mamut-routing-lib/)). For development:
+
+```sh
+git clone https://github.com/0nyr/kayros && cd kayros
+pip install -e . --group dev    # pip >= 25.1 (or: uv pip install -e . --group dev)
+```
+
+Requirements: Python ≥ 3.11; building from source (sdist or checkout) additionally needs a C++23 compiler and CMake ≥ 3.26 (fetched automatically by the build backend when missing).
+
+## Usage
+
+```python
+import kayros
+
+# Any MAMUT-routing TD instance (.vrp.json with its .atf.json sidecar next to it)
+instance_path = "benchmarks/TDVRPTW/Dabia2013/n=25/C101.vrp.json"
+solution = kayros.solve(instance_path, time_limit=10.0, seed=42)
+print(solution.duration, solution.num_routes, solution.status)
+
+# Anytime: react to every new incumbent while the solve keeps running
+def on_incumbent(incumbent, routes):
+    print(f"[{incumbent.seconds:7.2f}s] {incumbent.value:.6f} ({incumbent.origin})")
+
+solution = kayros.solve(instance_path, time_limit=60.0, on_incumbent=on_incumbent)
+
+# Feed the MAMUT BKS pipeline: solution.to_benchmark_solution() returns the
+# artifact accepted by mamut_routing_lib.td.bks.save_td_solution_as_bks_if_improved.
+```
+
+`solution.duration` is always the value computed by the reference checker (`mamut_routing_lib.td.check_td_solution`) — never an internal approximation.
+
+## Roadmap (stage 1)
+
+- [x] M3.0 — package scaffold, CI, PyPI wiring
+- [x] M3.1 — NDCPWLF composition engine + POD instance/route core
+- [x] M3.2 — exact equivalence gate against the reference checker (Dabia2013): 513 tests, 336 instances, zero divergences
+- [x] M3.3 — `kayros.solve()`: greedy construction + TD-ACO
+- [x] M3.4 — all four MAMUT TD families × {TDVRPTW, TDVRP}
+- [x] M3.5 — large-scale runs on Grid'5000: seeded the initial best-known solutions for all 1352 MAMUT TD instances
+- [x] M3.6 — anytime API (`on_incumbent`, time budgets) + **v0.1.0 on PyPI**
+- [ ] M3.7 — time-dependent local search layer (LCA-BST move evaluation, Blauth et al. 2024)
+- Later: optional exact BPC (`kayros[lera]`)
+
+## Provenance
+
+KAYROS is developed by [Florian Rascoussier (Onyr)](https://github.com/0nyr) as part of a PhD in operations research (IMT Atlantique / INSA Lyon), under the supervision of Romain Billot, Christine Solnon and Lina Fahed. The NDCPWLF composition engine follows Visser & Spliet (2020)'s move-evaluation theorems; the TD-ACO is a rewrite of the author's heuristic layer originally built on the TDVRPTW solver of Lera-Romero, Rönnqvist & Ljungqvist (2020, MIT-licensed). MIT license.

kayros-0.1.0/cpp/bindings/module.cpp

@@ -0,0 +1,215 @@
+#include <pybind11/functional.h>
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+#include <optional>
+#include <stdexcept>
+#include <tuple>
+#include <utility>
+#include <vector>
+
+#include "core/instance.h"
+#include "heuristics/heuristics.h"
+#include "pwlf/pwlf.h"
+
+namespace py = pybind11;
+
+#ifndef KAYROS_VERSION
+#define KAYROS_VERSION "0.0.0"
+#endif
+
+namespace {
+
+kayros::Pwlf make_pwlf(std::vector<double> xs, std::vector<double> ys) {
+    if (xs.size() != ys.size()) {
+        throw std::invalid_argument("xs and ys must have the same length");
+    }
+    return {std::move(xs), std::move(ys)};
+}
+
+using ArcSpec = std::tuple<std::int32_t, std::int32_t, std::vector<double>,
+                           std::vector<double>>;
+
+kayros::Instance make_instance(
+    std::int32_t num_customers, std::optional<std::int32_t> num_vehicles,
+    std::int64_t vehicle_capacity, std::pair<double, double> horizon,
+    std::optional<std::vector<std::pair<double, double>>> time_windows,
+    std::vector<std::int64_t> demands, std::vector<double> service_times,
+    const std::vector<ArcSpec>& arcs) {
+    kayros::Instance inst;
+    inst.num_customers = num_customers;
+    inst.num_vehicles = num_vehicles.value_or(-1);
+    inst.vehicle_capacity = vehicle_capacity;
+    inst.horizon_start = horizon.first;
+    inst.horizon_end = horizon.second;
+    const std::int64_t nv = inst.num_vertices();
+    const std::size_t expected = static_cast<std::size_t>(nv);
+    if (demands.size() != expected || service_times.size() != expected) {
+        throw std::invalid_argument(
+            "demands and service_times must have num_customers + 1 entries");
+    }
+    inst.demands = std::move(demands);
+    inst.service_times = std::move(service_times);
+    if (time_windows.has_value()) {
+        if (time_windows->size() != expected) {
+            throw std::invalid_argument(
+                "time_windows must have num_customers + 1 entries");
+        }
+        inst.has_time_windows = true;
+        inst.tw_earliest.reserve(expected);
+        inst.tw_latest.reserve(expected);
+        for (const auto& [earliest, latest] : *time_windows) {
+            inst.tw_earliest.push_back(earliest);
+            inst.tw_latest.push_back(latest);
+        }
+    }
+
+    const std::int64_t num_arcs = nv * nv;
+    std::vector<std::int64_t> lengths(static_cast<std::size_t>(num_arcs), 0);
+    std::int64_t total = 0;
+    for (const auto& [i, j, xs, ys] : arcs) {
+        if (i < 0 || i >= nv || j < 0 || j >= nv || i == j) {
+            throw std::invalid_argument("invalid arc endpoints");
+        }
+        if (xs.size() != ys.size() || xs.size() < 2) {
+            throw std::invalid_argument("arc ATF must have >= 2 breakpoints");
+        }
+        const std::int64_t a = static_cast<std::int64_t>(i) * nv + j;
+        if (lengths[static_cast<std::size_t>(a)] != 0) {
+            throw std::invalid_argument("duplicate arc");
+        }
+        lengths[static_cast<std::size_t>(a)] =
+            static_cast<std::int64_t>(xs.size());
+        total += static_cast<std::int64_t>(xs.size());
+    }
+    inst.atf_offset.assign(static_cast<std::size_t>(num_arcs) + 1, 0);
+    for (std::int64_t a = 0; a < num_arcs; ++a) {
+        inst.atf_offset[static_cast<std::size_t>(a) + 1] =
+            inst.atf_offset[static_cast<std::size_t>(a)] +
+            lengths[static_cast<std::size_t>(a)];
+    }
+    inst.atf_xs.assign(static_cast<std::size_t>(total), 0.0);
+    inst.atf_ys.assign(static_cast<std::size_t>(total), 0.0);
+    for (const auto& [i, j, xs, ys] : arcs) {
+        const std::int64_t a = static_cast<std::int64_t>(i) * nv + j;
+        const std::int64_t b = inst.atf_offset[static_cast<std::size_t>(a)];
+        std::copy(xs.begin(), xs.end(),
+                  inst.atf_xs.begin() + static_cast<std::ptrdiff_t>(b));
+        std::copy(ys.begin(), ys.end(),
+                  inst.atf_ys.begin() + static_cast<std::ptrdiff_t>(b));
+    }
+    return inst;
+}
+
+}  // namespace
+
+PYBIND11_MODULE(_core, m) {
+    m.doc() =
+        "kayros compiled core: NDCPWLF engine, POD instance/route model, "
+        "heuristics";
+    m.attr("__version__") = KAYROS_VERSION;
+
+    // --- pwlf primitives (exposed for the checker-equivalence test suite) ---
+    m.def("pwlf_identity", [](double low, double high) {
+        kayros::Pwlf f = kayros::identity(low, high);
+        return py::make_tuple(std::move(f.xs), std::move(f.ys));
+    });
+    m.def("pwlf_evaluate", [](std::vector<double> xs, std::vector<double> ys,
+                              double x) {
+        const kayros::Pwlf f = make_pwlf(std::move(xs), std::move(ys));
+        return kayros::evaluate(kayros::view(f), x);
+    });
+    m.def("pwlf_compose", [](std::vector<double> f_xs, std::vector<double> f_ys,
+                             std::vector<double> g_xs,
+                             std::vector<double> g_ys) {
+        const kayros::Pwlf f = make_pwlf(std::move(f_xs), std::move(f_ys));
+        const kayros::Pwlf g = make_pwlf(std::move(g_xs), std::move(g_ys));
+        kayros::Pwlf h = kayros::compose(kayros::view(f), kayros::view(g));
+        return py::make_tuple(std::move(h.xs), std::move(h.ys));
+    });
+    m.def("pwlf_min_shifted_image",
+          [](std::vector<double> xs, std::vector<double> ys) {
+              const kayros::Pwlf f = make_pwlf(std::move(xs), std::move(ys));
+              const kayros::MinShift s = kayros::min_shifted_image(kayros::view(f));
+              return py::make_tuple(s.value, s.argmin_x);
+          });
+    m.def("pwlf_make_theta",
+          [](double earliest, double latest, double service_time) {
+              kayros::Pwlf f = kayros::make_theta(earliest, latest, service_time);
+              return py::make_tuple(std::move(f.xs), std::move(f.ys));
+          });
+
+    // --- instance + route evaluation ---
+    py::class_<kayros::Instance>(m, "Instance")
+        .def(py::init(&make_instance), py::arg("num_customers"),
+             py::arg("num_vehicles"), py::arg("vehicle_capacity"),
+             py::arg("horizon"), py::arg("time_windows"), py::arg("demands"),
+             py::arg("service_times"), py::arg("arcs"))
+        .def_readonly("num_customers", &kayros::Instance::num_customers)
+        .def_readonly("num_vehicles", &kayros::Instance::num_vehicles)
+        .def_readonly("vehicle_capacity", &kayros::Instance::vehicle_capacity)
+        .def_readonly("has_time_windows", &kayros::Instance::has_time_windows)
+        .def("evaluate_route",
+             [](const kayros::Instance& inst,
+                const std::vector<std::int32_t>& route) {
+                 const kayros::RouteEval r = kayros::evaluate_route(
+                     inst, route.data(),
+                     static_cast<std::int64_t>(route.size()));
+                 return py::make_tuple(r.feasible, r.duration, r.departure);
+             })
+        .def("route_ready_time_function",
+             [](const kayros::Instance& inst,
+                const std::vector<std::int32_t>& route) {
+                 kayros::Pwlf d = kayros::route_ready_time_function(
+                     inst, route.data(),
+                     static_cast<std::int64_t>(route.size()));
+                 return py::make_tuple(std::move(d.xs), std::move(d.ys));
+             });
+
+    // --- heuristics ---
+    py::class_<kayros::AcoParams>(m, "AcoParams")
+        .def(py::init<>())
+        .def_readwrite("max_iterations", &kayros::AcoParams::max_iterations)
+        .def_readwrite("max_no_improvement", &kayros::AcoParams::max_no_improvement)
+        .def_readwrite("nb_ants", &kayros::AcoParams::nb_ants)
+        .def_readwrite("alpha", &kayros::AcoParams::alpha)
+        .def_readwrite("beta", &kayros::AcoParams::beta)
+        .def_readwrite("rho", &kayros::AcoParams::rho)
+        .def_readwrite("tau_min", &kayros::AcoParams::tau_min)
+        .def_readwrite("tau_0", &kayros::AcoParams::tau_0)
+        .def_readwrite("tau_max", &kayros::AcoParams::tau_max)
+        .def_readwrite("delta_pheromone_threshold",
+                       &kayros::AcoParams::delta_pheromone_threshold);
+
+    py::class_<kayros::Incumbent>(m, "Incumbent")
+        .def_readonly("value", &kayros::Incumbent::value)
+        .def_readonly("seconds", &kayros::Incumbent::seconds)
+        .def_readonly("iteration", &kayros::Incumbent::iteration)
+        .def_readonly("origin", &kayros::Incumbent::origin);
+
+    py::enum_<kayros::SolveStatus>(m, "SolveStatus")
+        .value("Finished", kayros::SolveStatus::Finished)
+        .value("Converged", kayros::SolveStatus::Converged)
+        .value("TimeLimit", kayros::SolveStatus::TimeLimit)
+        .value("Infeasible", kayros::SolveStatus::Infeasible);
+
+    py::class_<kayros::SolveResult>(m, "SolveResult")
+        .def_readonly("routes", &kayros::SolveResult::routes)
+        .def_readonly("value", &kayros::SolveResult::value)
+        .def_readonly("incumbents", &kayros::SolveResult::incumbents)
+        .def_readonly("status", &kayros::SolveResult::status)
+        .def_readonly("iterations_run", &kayros::SolveResult::iterations_run);
+
+    m.def("greedy_makespan", [](const kayros::Instance& inst) {
+        std::vector<std::vector<std::int32_t>> routes;
+        const bool ok = kayros::greedy_makespan(inst, routes);
+        return py::make_tuple(ok, std::move(routes));
+    });
+    m.def("solution_duration", &kayros::solution_duration);
+    // The callback caster re-acquires the GIL for each invocation, so the
+    // solve loop itself can keep running with the GIL released.
+    m.def("solve_aco", &kayros::solve_aco, py::arg("instance"),
+          py::arg("params"), py::arg("seed"), py::arg("time_limit_seconds"),
+          py::arg("on_incumbent") = kayros::IncumbentCallback{},
+          py::call_guard<py::gil_scoped_release>());
+}

kayros-0.1.0/cpp/core/instance.h

@@ -0,0 +1,60 @@
+#pragma once
+
+#include <cstdint>
+#include <vector>
+
+#include "pwlf/pwlf.h"
+
+namespace kayros {
+
+// TD instance in checker conventions: vertices 0..n with 0 = depot, customers
+// 1..n; complete arc set carrying arrival-time functions alpha_ij over the
+// horizon (arrival_at_j = alpha_ij(departure_from_i), FIFO by monotonicity).
+struct Instance {
+    std::int32_t num_customers = 0;   // n
+    std::int32_t num_vehicles = -1;   // fleet upper bound; -1 = unbounded
+    std::int64_t vehicle_capacity = 0;
+    double horizon_start = 0.0;
+    double horizon_end = 0.0;
+    bool has_time_windows = false;    // TDVRPTW when true, TDVRP otherwise
+    std::vector<std::int64_t> demands;    // size n+1, demands[0] = 0
+    std::vector<double> service_times;    // size n+1
+    std::vector<double> tw_earliest;      // size n+1 iff has_time_windows
+    std::vector<double> tw_latest;        // size n+1 iff has_time_windows
+
+    // Arc ATF pool: arc (i,j) owns the slice [atf_offset[a], atf_offset[a+1])
+    // of atf_xs/atf_ys, with a = i*(n+1)+j. Self-arcs have empty slices.
+    std::vector<std::int64_t> atf_offset;  // size (n+1)*(n+1)+1
+    std::vector<double> atf_xs;
+    std::vector<double> atf_ys;
+
+    std::int32_t num_vertices() const { return num_customers + 1; }
+
+    PwlfView arc(std::int32_t i, std::int32_t j) const {
+        const std::int64_t a =
+            static_cast<std::int64_t>(i) * num_vertices() + j;
+        const std::int64_t b = atf_offset[a];
+        const std::int64_t e = atf_offset[a + 1];
+        return {atf_xs.data() + b, atf_ys.data() + b, e - b};
+    }
+};
+
+struct RouteEval {
+    bool feasible = false;
+    double duration = 0.0;   // Delta*_r = min_t (delta_r(t) - t)
+    double departure = 0.0;  // earliest optimal depot departure t*_r
+};
+
+// Route ready-time function delta_r over feasible depot departure times.
+// Exact port of the checker's compute_route_ready_time_function: per vertex
+// acc <- theta_v ∘ alpha_{prev,v} ∘ acc, with the TDVRPTW depot TW restriction
+// at departure and on return. Returns the empty function when time-infeasible.
+// route points to customer ids in 1..n, depot excluded.
+Pwlf route_ready_time_function(const Instance& inst, const std::int32_t* route,
+                               std::int64_t len);
+
+// Optimal duration and earliest optimal departure (checker's compute_route_duration).
+RouteEval evaluate_route(const Instance& inst, const std::int32_t* route,
+                         std::int64_t len);
+
+}  // namespace kayros

kayros-0.1.0/cpp/core/queries.h

@@ -0,0 +1,48 @@
+#pragma once
+
+#include <cmath>
+#include <limits>
+
+#include "core/instance.h"
+
+namespace kayros {
+
+// Point queries used by construction heuristics. They mirror the checker's
+// composition semantics point-wise (theta_j ∘ alpha_ij at a single departure),
+// with plain max/+ arithmetic: guidance-exact, while final pricing always goes
+// through the compose-based evaluate_route (bit-identical to the checker).
+inline constexpr double kInfeasible = std::numeric_limits<double>::infinity();
+
+// Earliest feasible depot departure time (the checker's departure_low).
+inline double departure_low(const Instance& inst) {
+    double lo = inst.horizon_start;
+    if (inst.has_time_windows && inst.tw_earliest[0] > lo) lo = inst.tw_earliest[0];
+    return lo;
+}
+
+// Ready time at j (service completed) when leaving i at ready time t;
+// +inf when the move is time-window or horizon infeasible.
+inline double ready_next(const Instance& inst, std::int32_t i, std::int32_t j,
+                         double t) {
+    const PwlfView alpha = inst.arc(i, j);
+    if (alpha.n == 0 || t < alpha.xs[0] || t > alpha.xs[alpha.n - 1]) {
+        return kInfeasible;
+    }
+    const double arrival = evaluate(alpha, t);
+    if (inst.has_time_windows) {
+        if (arrival > inst.tw_latest[j]) return kInfeasible;
+        const double start = arrival > inst.tw_earliest[j] ? arrival : inst.tw_earliest[j];
+        return start + inst.service_times[j];
+    }
+    return arrival + inst.service_times[j];
+}
+
+// Can the vehicle return to the depot when leaving j at ready time t?
+inline bool depot_return_feasible(const Instance& inst, std::int32_t j, double t) {
+    const PwlfView alpha = inst.arc(j, 0);
+    if (alpha.n == 0 || t < alpha.xs[0] || t > alpha.xs[alpha.n - 1]) return false;
+    if (!inst.has_time_windows) return true;
+    return evaluate(alpha, t) <= inst.tw_latest[0];
+}
+
+}  // namespace kayros

kayros-0.1.0/cpp/core/route_eval.cpp

@@ -0,0 +1,56 @@
+#include <algorithm>
+
+#include "core/instance.h"
+
+namespace kayros {
+
+Pwlf route_ready_time_function(const Instance& inst, const std::int32_t* route,
+                               std::int64_t len) {
+    double dep_lo = inst.horizon_start;
+    double dep_hi = inst.horizon_end;
+    if (inst.has_time_windows) {
+        dep_lo = std::max(dep_lo, inst.tw_earliest[0]);
+        dep_hi = std::min(dep_hi, inst.tw_latest[0]);
+    }
+    if (dep_lo > dep_hi) return {};
+
+    Pwlf acc = identity(dep_lo, dep_hi);
+    std::int32_t prev = 0;
+    for (std::int64_t k = 0; k < len; ++k) {
+        const std::int32_t v = route[k];
+        acc = compose(inst.arc(prev, v), view(acc));
+        if (acc.xs.empty()) return acc;
+        const double service_time = inst.service_times[v];
+        Pwlf theta;
+        if (inst.has_time_windows) {
+            theta = make_theta(inst.tw_earliest[v], inst.tw_latest[v], service_time);
+        } else {
+            // TDVRP: pure service shift over the reachable arrival range.
+            const double upper = acc.ys.back();
+            theta = Pwlf{{0.0, upper}, {service_time, upper + service_time}};
+        }
+        acc = compose(view(theta), view(acc));
+        if (acc.xs.empty()) return acc;
+        prev = v;
+    }
+
+    acc = compose(inst.arc(prev, 0), view(acc));
+    if (acc.xs.empty()) return acc;
+    if (inst.has_time_windows) {
+        // Restrict the return arrival to the depot due date, without any
+        // waiting clamp: the route ends upon arrival.
+        const Pwlf clamp = identity(0.0, inst.tw_latest[0]);
+        acc = compose(view(clamp), view(acc));
+    }
+    return acc;
+}
+
+RouteEval evaluate_route(const Instance& inst, const std::int32_t* route,
+                         std::int64_t len) {
+    const Pwlf delta = route_ready_time_function(inst, route, len);
+    if (delta.xs.empty()) return {false, 0.0, 0.0};
+    const MinShift m = min_shifted_image(view(delta));
+    return {true, m.value, m.argmin_x};
+}
+
+}  // namespace kayros