diff --git a/CHANGELOG.md b/CHANGELOG.md index f3a3466..df5e49d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ and published versions will follow [Semantic Versioning](https://semver.org/). ## [Unreleased] +## [0.2.0-alpha.1] - 2026-09-23 + +This alpha adds host-orchestrated GPU-selected 2-opt search. The existing PTX +and CUDA kernel ABI are unchanged; no search-level speedup is claimed. + ### Added - Host-orchestrated GPU-selected 2-opt search for one route or every route in a @@ -49,6 +54,7 @@ and kernel compiler workspace are not published. - The supported input model is CVRP; Solomon time windows are parsed but not enforced by the current construction or local-search routines. -[Unreleased]: https://github.com/pedrozaz/vrp-gpu/compare/v0.1.1-alpha...develop +[Unreleased]: https://github.com/pedrozaz/vrp-gpu/compare/v0.2.0-alpha.1...develop +[0.2.0-alpha.1]: https://github.com/pedrozaz/vrp-gpu/compare/v0.1.1-alpha...v0.2.0-alpha.1 [0.1.1-alpha]: https://github.com/pedrozaz/vrp-gpu/compare/v0.1.0-alpha.1...v0.1.1-alpha [0.1.0-alpha.1]: https://github.com/pedrozaz/vrp-gpu/releases/tag/v0.1.0-alpha.1 diff --git a/Cargo.lock b/Cargo.lock index 4fe1b56..74b40c3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -29,21 +29,21 @@ dependencies = [ [[package]] name = "vrp-gpu" -version = "0.1.1-alpha" +version = "0.2.0-alpha.1" dependencies = [ "cudarc", ] [[package]] name = "vrp-gpu-bench" -version = "0.1.1-alpha" +version = "0.2.0-alpha.1" dependencies = [ "vrp-gpu", ] [[package]] name = "vrp-gpu-cli" -version = "0.1.1-alpha" +version = "0.2.0-alpha.1" dependencies = [ "vrp-gpu", ] diff --git a/Cargo.toml b/Cargo.toml index 433683f..349b30a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,7 +8,7 @@ members = [ exclude = ["crates/vrp-gpu-kernel"] [workspace.package] -version = "0.1.1-alpha" +version = "0.2.0-alpha.1" edition = "2024" rust-version = "1.88" authors = ["Guilherme Pedroza"] @@ -16,7 +16,7 @@ license = "Apache-2.0" repository = "https://github.com/pedrozaz/vrp-gpu" [workspace.dependencies] -vrp-gpu = { version = "0.1.1-alpha", path = "crates/vrp-gpu" } +vrp-gpu = { version = "0.2.0-alpha.1", path = "crates/vrp-gpu" } [workspace.lints.rust] missing_docs = "warn" diff --git a/README.md b/README.md index fbee018..18ce097 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,14 @@ VRP-GPU is an experimental Rust library for capacitated vehicle routing (CVRP). It parses Solomon-style instances, builds routes with a greedy nearest-neighbor -heuristic, and provides CPU 2-opt local search. The published `gpu` feature -evaluates CUDA 2-opt candidates and selects one improving move; the development -branch also has host-orchestrated GPU-selected search. Neither is a GPU-only -end-to-end solver. The CPU implementation is the correctness reference. +heuristic, and provides CPU 2-opt local search. The optional `gpu` feature +evaluates CUDA 2-opt candidates and supports host-orchestrated, GPU-selected +search over routes and solutions. It is not a GPU-only end-to-end solver. The +CPU implementation is the correctness reference. -> **Published alpha:** [`vrp-gpu 0.1.1-alpha`](https://crates.io/crates/vrp-gpu/0.1.1-alpha). +> **Published alpha:** [`vrp-gpu 0.2.0-alpha.1`](https://crates.io/crates/vrp-gpu/0.2.0-alpha.1). > Public APIs may change before the first stable release. See the -> [API documentation](https://docs.rs/vrp-gpu/0.1.1-alpha/vrp_gpu/) for this +> [API documentation](https://docs.rs/vrp-gpu/0.2.0-alpha.1/vrp_gpu/) for this > published version. ## Workspace @@ -34,7 +34,7 @@ To use the published alpha, specify its prerelease version: ```toml [dependencies] -vrp-gpu = "0.1.1-alpha" +vrp-gpu = "0.2.0-alpha.1" ``` To try changes that have not been published, pin a tested repository commit: @@ -44,11 +44,12 @@ To try changes that have not been published, pin a tested repository commit: vrp-gpu = { git = "https://github.com/pedrozaz/vrp-gpu", rev = "" } ``` -Enable CUDA candidate evaluation with the opt-in `gpu` feature: +Enable CUDA candidate evaluation and GPU-selected search with the opt-in +`gpu` feature: ```toml [dependencies] -vrp-gpu = { version = "0.1.1-alpha", features = ["gpu"] } +vrp-gpu = { version = "0.2.0-alpha.1", features = ["gpu"] } ``` The default feature set is CPU-only. See the @@ -56,10 +57,12 @@ The default feature set is CPU-only. See the public feature contract. The current internal CLI prints a placeholder message; use the library API for actual routing work. -The CUDA API currently creates a context and transfers data for each nontrivial -call. In the [recorded CPU/GPU validation](docs/benchmarks/2026-09-22-cpu-gpu.md), -its end-to-end latency was higher than the CPU reference for every measured -route with at least two customers. No GPU speedup is claimed for this alpha. +Each nontrivial CUDA selection currently creates a context and transfers data; +iterative search repeats that overhead. The +[recorded CPU/GPU validation](docs/benchmarks/2026-09-22-cpu-gpu.md) measured +the earlier single-move API, which was slower than the CPU reference for every +measured route with at least two customers. Search-level performance has not +been measured. No GPU speedup is claimed for this alpha. ## Compatibility diff --git a/crates/vrp-gpu/Cargo.toml b/crates/vrp-gpu/Cargo.toml index 1f0cefe..d25a9c0 100644 --- a/crates/vrp-gpu/Cargo.toml +++ b/crates/vrp-gpu/Cargo.toml @@ -6,7 +6,7 @@ rust-version.workspace = true license.workspace = true authors.workspace = true repository.workspace = true -description = "Experimental CVRP library with CPU 2-opt and optional CUDA move evaluation" +description = "Experimental CVRP library with CPU 2-opt and optional CUDA-selected local search" documentation = "https://docs.rs/vrp-gpu" readme = "README.md" keywords = ["vrp", "cuda", "gpu", "routing", "optimization"] diff --git a/crates/vrp-gpu/README.md b/crates/vrp-gpu/README.md index 622d9c6..e3a4936 100644 --- a/crates/vrp-gpu/README.md +++ b/crates/vrp-gpu/README.md @@ -2,15 +2,14 @@ `vrp-gpu` provides CVRP data structures, CPU reference heuristics and optional CUDA evaluation of 2-opt moves. It parses Solomon-style text, constructs routes -with a greedy nearest-neighbor heuristic, and improves routes on the CPU. -The published GPU API computes candidate deltas or selects a single move. The -development branch also provides host-orchestrated GPU-selected 2-opt search -for routes and solutions; this new API is not in the published `0.1.1-alpha`. +with a greedy nearest-neighbor heuristic, and improves routes on the CPU. The +GPU API computes candidate deltas, selects individual moves, or runs +host-orchestrated GPU-selected 2-opt search for routes and solutions. The current alpha is -[`0.1.1-alpha`](https://crates.io/crates/vrp-gpu/0.1.1-alpha). +[`0.2.0-alpha.1`](https://crates.io/crates/vrp-gpu/0.2.0-alpha.1). The API may change before a stable release. See the -[documentation for that version](https://docs.rs/vrp-gpu/0.1.1-alpha/vrp_gpu/). +[documentation for that version](https://docs.rs/vrp-gpu/0.2.0-alpha.1/vrp_gpu/). ## Features @@ -28,7 +27,7 @@ To use the published alpha, specify its prerelease version: ```toml [dependencies] -vrp-gpu = "0.1.1-alpha" +vrp-gpu = "0.2.0-alpha.1" ``` For changes not yet published, pin a tested Git revision: @@ -81,7 +80,7 @@ To use the optional GPU API in the published alpha, enable the feature: ```toml [dependencies] -vrp-gpu = { version = "0.1.1-alpha", features = ["gpu"] } +vrp-gpu = { version = "0.2.0-alpha.1", features = ["gpu"] } ``` `gpu::evaluate_two_opt_deltas` returns a row-major `n × n` matrix with computed @@ -94,9 +93,9 @@ invalid input, size overflow or CUDA driver failure. Empty and singleton routes return without creating a CUDA context. A returned move is only a proposal: apply it with `cpu::apply_two_opt` if your application accepts it. -## Development-only GPU search API +## GPU search API -On the development branch, `gpu::two_opt_route` repeatedly selects and applies +`gpu::two_opt_route` repeatedly selects and applies best-improvement moves to one route. `gpu::two_opt` does the same independently for each route in a solution. Both return `GpuSearchReport` with accepted move count and distance improvement computed by `f64` accumulation of the `f32` @@ -105,7 +104,7 @@ validation, CUDA, or selected-move consistency error leaves the input unchanged. A solution search does not itself establish fleet, capacity, or customer-coverage feasibility; check `Solution::is_feasible` when needed. -The following example uses the development-branch search API. It compiles +The following example uses the search API. It compiles without running in rustdoc because execution requires a compatible NVIDIA GPU and driver: @@ -179,8 +178,9 @@ each iteration; there is no reusable device session. The checked-in artifact targets `sm_120` and has been hardware-validated on an NVIDIA GeForce RTX 5060 Ti. Other devices have no compatibility claim. The [recorded validation](https://github.com/pedrozaz/vrp-gpu/blob/develop/docs/benchmarks/2026-09-22-cpu-gpu.md) -found this end-to-end GPU API slower than the CPU reference for all measured -nontrivial routes; no speedup is claimed. See the [input and algorithm guide](https://github.com/pedrozaz/vrp-gpu/blob/develop/docs/user-guide.md) +found the single-move GPU API slower than the CPU reference for all measured +nontrivial routes. Search-level latency has not been measured; no speedup is +claimed. See the [input and algorithm guide](https://github.com/pedrozaz/vrp-gpu/blob/develop/docs/user-guide.md) for exact model and numerical contracts. ## Minimum supported Rust version