euclimix 0.1.0__tar.gz

euclimix-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md pyproject.toml
+recursive-include src/euclimix *.py *.typed *.cpp *.cu *.h CMakeLists.txt
+recursive-include docs *.md *.json
+recursive-include examples *.py *.cpp
+recursive-include tests *.py *.cu *.cuh *.cpp *.md
+

euclimix-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: euclimix
+Version: 0.1.0
+Summary: Mixed-precision squared Euclidean distances with selective CUDA recomputation
+Author: Xinye Chen
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: torch<3,>=2.11
+Requires-Dist: ninja>=1.11
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-cov>=4.1; extra == "test"
+Requires-Dist: numpy>=1.26; extra == "test"
+Provides-Extra: build
+Requires-Dist: build>=1.2; extra == "build"
+
+# euclimix
+
+[![CI](https://img.shields.io/github/actions/workflow/status/inEXASCALE/euclid-cuda/cpu.yml?branch=main&label=CI&logo=githubactions&logoColor=white&style=flat-square)](https://github.com/inEXASCALE/euclid-cuda/actions/workflows/cpu.yml)
+[![CUDA tests](https://img.shields.io/github/actions/workflow/status/inEXASCALE/euclid-cuda/gpu.yml?branch=main&label=CUDA%20tests&logo=nvidia&logoColor=white&style=flat-square)](https://github.com/inEXASCALE/euclid-cuda/actions/workflows/gpu.yml)
+[![Python coverage gate: 100%](https://img.shields.io/badge/Python%20coverage%20gate-100%25-2C974B?logo=pytest&logoColor=white&style=flat-square)](docs/validation.md#python-tests)
+
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white&style=flat-square)](pyproject.toml)
+[![PyTorch 2.11+](https://img.shields.io/badge/PyTorch-2.11%2B-EE4C2C?logo=pytorch&logoColor=white&style=flat-square)](https://pytorch.org/)
+[![CUDA 12.8+](https://img.shields.io/badge/CUDA-12.8%2B-76B900?logo=nvidia&logoColor=white&style=flat-square)](https://developer.nvidia.com/cuda-toolkit)
+[![arXiv:2407.12208](https://img.shields.io/badge/arXiv-2407.12208-B31B1B?logo=arxiv&logoColor=white&style=flat-square)](#citation)
+
+Mixed-precision Euclidean distances on NVIDIA GPUs, with Python/pybind11 and
+C++/CUDA interfaces. Low-precision expanded distances are combined with
+selective higher-precision recomputation.
+
+## Installation
+
+Requirements: Linux, Python 3.11+, CUDA-enabled PyTorch 2.11+, CUDA toolkit
+12.8+ with `nvcc`, and an Ampere or newer GPU (SM80+). A compatible C++17
+compiler is required; newer LibTorch versions may require C++20.
+The PyTorch CUDA wheel provides runtime libraries, not the CUDA compiler.
+cuDNN is not required.
+
+Example with CUDA 12.8:
+
+```bash
+git clone https://github.com/inEXASCALE/euclid-cuda.git
+cd euclid-cuda
+conda create -n euclimix python=3.12 -y
+conda activate euclimix
+python -m pip install torch==2.11.0 --index-url https://download.pytorch.org/whl/cu128
+python -m pip install .
+python -c 'import euclimix; euclimix.build_cuda()'
+```
+
+Set `CUDA_HOME` if the toolkit is not detected. Extensions compile on first
+use and are cached by PyTorch. Set `TORCH_CUDA_ARCH_LIST` for the target GPU
+(for example, `8.0` for A100), `MAX_JOBS` to limit build parallelism, and
+`EUCLIMIX_BUILD_VERBOSE=1` for compiler output. Build and warm up the functions
+before timing them.
+
+## Python interface
+
+### Squared and Euclidean distances
+
+```python
+import torch
+from euclimix import pairwise_squared_distances, pairwise_distances
+
+X = torch.tensor([[0., 0.], [3., 4.]], device='cuda', dtype=torch.float32)
+
+squared = pairwise_squared_distances(X)
+distances = pairwise_distances(X)
+
+print(squared.cpu())    # tensor([[ 0., 25.], [25.,  0.]])
+print(distances.cpu())  # tensor([[0., 5.], [5., 0.]])
+```
+
+Omitting `Y` computes all distances within `X`. Pass a second matrix to
+compute an `(n_samples_X, n_samples_Y)` result.
+
+### Precision and recomputation statistics
+
+```python
+import torch
+from euclimix import pairwise_squared_distances
+
+X = torch.randn(1024, 128, device='cuda', dtype=torch.float32)
+Y = torch.randn(512, 128, device='cuda', dtype=torch.float32)
+
+result = pairwise_squared_distances(
+    X, Y, precision='fp16', correction='fp64', rho=5.0, return_info=True,
+)
+
+print(result.distances.shape)      # torch.Size([1024, 512])
+print(result.distances.dtype)      # torch.float32
+print(result.fallback_count)
+print(f'Recomputed: {result.fallback_fraction:.2%}')
+```
+
+### Storage and threshold selection
+
+```python
+import torch
+from euclimix import controlled_squared_distances, direct_squared_distances
+
+X = torch.randn(256, 128, device='cuda', dtype=torch.float32)
+Y = torch.randn(128, 128, device='cuda', dtype=torch.float32)
+
+result = controlled_squared_distances(
+    X, Y, precision='bf16', storage='fp32', test='extended', return_info=True,
+)
+reference = direct_squared_distances(X, Y, precision='fp64')
+max_absolute_error = (result.distances.double() - reference).abs().max()
+
+print(result.model)
+print(result.fallback_fraction)
+print(max_absolute_error.item())
+```
+
+Use `storage='low'` to store intermediates in the input format and
+`test='original'` to select the empirical threshold. The FP64 direct
+reference retains FP64 output.
+
+| Function | Result | Implementation |
+|---|---|---|
+| `pairwise_squared_distances` | FP32 squared distances | Expanded formula, Original test, index-list recomputation |
+| `controlled_squared_distances` | FP32 squared distances | Configurable storage and Original/Extended test, mask-based recomputation |
+| `direct_squared_distances` | FP32 or FP64 squared distances | Direct subtraction and FMA accumulation |
+| `pairwise_distances` | FP32 Euclidean distances | Square root of `pairwise_squared_distances` |
+
+Inputs must be finite, dense FP32 CUDA matrices on the same device. Omit `Y`
+to compare `X` with itself. Noncontiguous inputs and negative views are
+materialized. Empty row sets are supported; zero features and more than
+`2**31-1` pairs are rejected. Autograd and CUDA graph capture are unsupported.
+
+FP16/BF16 cross products use FP32 accumulation. FP32/FP64 recomputation reads
+the original FP32 coordinates; mixed outputs are stored in FP32. The
+`correction='same'` option uses quantized coordinates and low-format arithmetic,
+which can lose accuracy or overflow. Finite inputs can also produce squared
+distances outside the FP32 output range.
+
+The Extended error bound assumes a bound on the inner-product arithmetic;
+its cuBLAS application is conditional on that assumption. A relative-error
+bound for distances does not ensure identical nearest-center assignments.
+See [Numerical implementation](docs/implementation.md) for the precision paths
+and threshold definitions.
+
+Input validation and reading fallback statistics synchronize with the GPU.
+Native kernels use the current CUDA stream. Callers using multiple streams
+must establish producer/consumer dependencies with events or `wait_stream`.
+The FP32 index-list path follows PyTorch's TF32/matrix-multiplication policy;
+autocast does not override explicit native precision choices.
+
+## C++/CUDA interface
+
+The native API uses LibTorch CUDA tensors and the types in
+`euclimix/distance.h`. See [examples/native.cpp](examples/native.cpp).
+
+```cpp
+#include <euclimix/distance.h>
+
+euclimix::DistanceResult distances(torch::Tensor X, torch::Tensor Y) {
+    euclimix::PaperOptions options;
+    options.precision = euclimix::InputPrecision::FP16;
+    options.correction = euclimix::Correction::FP64;
+    options.rho = 5.0;
+    return euclimix::paper_squared_distances(X, Y, options);
+}
+```
+
+Build the native library and examples:
+
+```bash
+cmake -S src/euclimix/csrc -B .native-build \
+  -DCMAKE_PREFIX_PATH="$(python -c 'import torch; print(torch.utils.cmake_prefix_path)')" \
+  -DCMAKE_CUDA_ARCHITECTURES=80 -DEUCLIMIX_BUILD_EXAMPLE=ON
+cmake --build .native-build -j2
+.native-build/euclimix_native_example
+.native-build/euclimix_state_example
+```
+
+Native inputs must be contiguous with negative views resolved. The CMake
+library can be used without Python or pybind11.
+
+## Testing
+
+```bash
+python -m pip install -e '.[test,build]'
+python -m pytest -m 'not cuda' --cov=euclimix --cov-branch --cov-report=term-missing
+EUCLIMIX_REQUIRE_CUDA=1 python -m pytest -m cuda
+EUCLIMIX_REQUIRE_CUDA=1 EUCLIMIX_COMPARE_PAPER=1 python -m pytest -m cuda
+```
+
+CPU CI requires 100% Python statement and branch coverage. CUDA integration
+tests require a GPU; the GPU workflow uses a self-hosted Linux runner labeled
+`self-hosted, linux, x64, gpu`. Python coverage does not measure CUDA code.
+See [Testing](docs/validation.md) for device-memory checks and runner setup.
+
+Reference CUDA sources in `tests/reference` are used for regression tests.
+Their source hashes are recorded in [paper_sources.json](docs/paper_sources.json).
+
+## Citation
+
+If you use euclimix in your research, please cite the accompanying
+[paper](https://arxiv.org/abs/2407.12208):
+
+```bibtex
+@misc{carson2024computing,
+  title         = {Computing $k$-means in mixed precision},
+  author        = {Erin Carson and Xinye Chen and Xiaobo Liu},
+  year          = {2024},
+  eprint        = {2407.12208},
+  archivePrefix = {arXiv},
+  primaryClass  = {math.NA},
+  doi           = {10.48550/arXiv.2407.12208},
+  url           = {https://arxiv.org/abs/2407.12208}
+}
+```

euclimix-0.1.0/README.md

@@ -0,0 +1,199 @@
+# euclimix
+
+[![CI](https://img.shields.io/github/actions/workflow/status/inEXASCALE/euclid-cuda/cpu.yml?branch=main&label=CI&logo=githubactions&logoColor=white&style=flat-square)](https://github.com/inEXASCALE/euclid-cuda/actions/workflows/cpu.yml)
+[![CUDA tests](https://img.shields.io/github/actions/workflow/status/inEXASCALE/euclid-cuda/gpu.yml?branch=main&label=CUDA%20tests&logo=nvidia&logoColor=white&style=flat-square)](https://github.com/inEXASCALE/euclid-cuda/actions/workflows/gpu.yml)
+[![Python coverage gate: 100%](https://img.shields.io/badge/Python%20coverage%20gate-100%25-2C974B?logo=pytest&logoColor=white&style=flat-square)](docs/validation.md#python-tests)
+
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white&style=flat-square)](pyproject.toml)
+[![PyTorch 2.11+](https://img.shields.io/badge/PyTorch-2.11%2B-EE4C2C?logo=pytorch&logoColor=white&style=flat-square)](https://pytorch.org/)
+[![CUDA 12.8+](https://img.shields.io/badge/CUDA-12.8%2B-76B900?logo=nvidia&logoColor=white&style=flat-square)](https://developer.nvidia.com/cuda-toolkit)
+[![arXiv:2407.12208](https://img.shields.io/badge/arXiv-2407.12208-B31B1B?logo=arxiv&logoColor=white&style=flat-square)](#citation)
+
+Mixed-precision Euclidean distances on NVIDIA GPUs, with Python/pybind11 and
+C++/CUDA interfaces. Low-precision expanded distances are combined with
+selective higher-precision recomputation.
+
+## Installation
+
+Requirements: Linux, Python 3.11+, CUDA-enabled PyTorch 2.11+, CUDA toolkit
+12.8+ with `nvcc`, and an Ampere or newer GPU (SM80+). A compatible C++17
+compiler is required; newer LibTorch versions may require C++20.
+The PyTorch CUDA wheel provides runtime libraries, not the CUDA compiler.
+cuDNN is not required.
+
+Example with CUDA 12.8:
+
+```bash
+git clone https://github.com/inEXASCALE/euclid-cuda.git
+cd euclid-cuda
+conda create -n euclimix python=3.12 -y
+conda activate euclimix
+python -m pip install torch==2.11.0 --index-url https://download.pytorch.org/whl/cu128
+python -m pip install .
+python -c 'import euclimix; euclimix.build_cuda()'
+```
+
+Set `CUDA_HOME` if the toolkit is not detected. Extensions compile on first
+use and are cached by PyTorch. Set `TORCH_CUDA_ARCH_LIST` for the target GPU
+(for example, `8.0` for A100), `MAX_JOBS` to limit build parallelism, and
+`EUCLIMIX_BUILD_VERBOSE=1` for compiler output. Build and warm up the functions
+before timing them.
+
+## Python interface
+
+### Squared and Euclidean distances
+
+```python
+import torch
+from euclimix import pairwise_squared_distances, pairwise_distances
+
+X = torch.tensor([[0., 0.], [3., 4.]], device='cuda', dtype=torch.float32)
+
+squared = pairwise_squared_distances(X)
+distances = pairwise_distances(X)
+
+print(squared.cpu())    # tensor([[ 0., 25.], [25.,  0.]])
+print(distances.cpu())  # tensor([[0., 5.], [5., 0.]])
+```
+
+Omitting `Y` computes all distances within `X`. Pass a second matrix to
+compute an `(n_samples_X, n_samples_Y)` result.
+
+### Precision and recomputation statistics
+
+```python
+import torch
+from euclimix import pairwise_squared_distances
+
+X = torch.randn(1024, 128, device='cuda', dtype=torch.float32)
+Y = torch.randn(512, 128, device='cuda', dtype=torch.float32)
+
+result = pairwise_squared_distances(
+    X, Y, precision='fp16', correction='fp64', rho=5.0, return_info=True,
+)
+
+print(result.distances.shape)      # torch.Size([1024, 512])
+print(result.distances.dtype)      # torch.float32
+print(result.fallback_count)
+print(f'Recomputed: {result.fallback_fraction:.2%}')
+```
+
+### Storage and threshold selection
+
+```python
+import torch
+from euclimix import controlled_squared_distances, direct_squared_distances
+
+X = torch.randn(256, 128, device='cuda', dtype=torch.float32)
+Y = torch.randn(128, 128, device='cuda', dtype=torch.float32)
+
+result = controlled_squared_distances(
+    X, Y, precision='bf16', storage='fp32', test='extended', return_info=True,
+)
+reference = direct_squared_distances(X, Y, precision='fp64')
+max_absolute_error = (result.distances.double() - reference).abs().max()
+
+print(result.model)
+print(result.fallback_fraction)
+print(max_absolute_error.item())
+```
+
+Use `storage='low'` to store intermediates in the input format and
+`test='original'` to select the empirical threshold. The FP64 direct
+reference retains FP64 output.
+
+| Function | Result | Implementation |
+|---|---|---|
+| `pairwise_squared_distances` | FP32 squared distances | Expanded formula, Original test, index-list recomputation |
+| `controlled_squared_distances` | FP32 squared distances | Configurable storage and Original/Extended test, mask-based recomputation |
+| `direct_squared_distances` | FP32 or FP64 squared distances | Direct subtraction and FMA accumulation |
+| `pairwise_distances` | FP32 Euclidean distances | Square root of `pairwise_squared_distances` |
+
+Inputs must be finite, dense FP32 CUDA matrices on the same device. Omit `Y`
+to compare `X` with itself. Noncontiguous inputs and negative views are
+materialized. Empty row sets are supported; zero features and more than
+`2**31-1` pairs are rejected. Autograd and CUDA graph capture are unsupported.
+
+FP16/BF16 cross products use FP32 accumulation. FP32/FP64 recomputation reads
+the original FP32 coordinates; mixed outputs are stored in FP32. The
+`correction='same'` option uses quantized coordinates and low-format arithmetic,
+which can lose accuracy or overflow. Finite inputs can also produce squared
+distances outside the FP32 output range.
+
+The Extended error bound assumes a bound on the inner-product arithmetic;
+its cuBLAS application is conditional on that assumption. A relative-error
+bound for distances does not ensure identical nearest-center assignments.
+See [Numerical implementation](docs/implementation.md) for the precision paths
+and threshold definitions.
+
+Input validation and reading fallback statistics synchronize with the GPU.
+Native kernels use the current CUDA stream. Callers using multiple streams
+must establish producer/consumer dependencies with events or `wait_stream`.
+The FP32 index-list path follows PyTorch's TF32/matrix-multiplication policy;
+autocast does not override explicit native precision choices.
+
+## C++/CUDA interface
+
+The native API uses LibTorch CUDA tensors and the types in
+`euclimix/distance.h`. See [examples/native.cpp](examples/native.cpp).
+
+```cpp
+#include <euclimix/distance.h>
+
+euclimix::DistanceResult distances(torch::Tensor X, torch::Tensor Y) {
+    euclimix::PaperOptions options;
+    options.precision = euclimix::InputPrecision::FP16;
+    options.correction = euclimix::Correction::FP64;
+    options.rho = 5.0;
+    return euclimix::paper_squared_distances(X, Y, options);
+}
+```
+
+Build the native library and examples:
+
+```bash
+cmake -S src/euclimix/csrc -B .native-build \
+  -DCMAKE_PREFIX_PATH="$(python -c 'import torch; print(torch.utils.cmake_prefix_path)')" \
+  -DCMAKE_CUDA_ARCHITECTURES=80 -DEUCLIMIX_BUILD_EXAMPLE=ON
+cmake --build .native-build -j2
+.native-build/euclimix_native_example
+.native-build/euclimix_state_example
+```
+
+Native inputs must be contiguous with negative views resolved. The CMake
+library can be used without Python or pybind11.
+
+## Testing
+
+```bash
+python -m pip install -e '.[test,build]'
+python -m pytest -m 'not cuda' --cov=euclimix --cov-branch --cov-report=term-missing
+EUCLIMIX_REQUIRE_CUDA=1 python -m pytest -m cuda
+EUCLIMIX_REQUIRE_CUDA=1 EUCLIMIX_COMPARE_PAPER=1 python -m pytest -m cuda
+```
+
+CPU CI requires 100% Python statement and branch coverage. CUDA integration
+tests require a GPU; the GPU workflow uses a self-hosted Linux runner labeled
+`self-hosted, linux, x64, gpu`. Python coverage does not measure CUDA code.
+See [Testing](docs/validation.md) for device-memory checks and runner setup.
+
+Reference CUDA sources in `tests/reference` are used for regression tests.
+Their source hashes are recorded in [paper_sources.json](docs/paper_sources.json).
+
+## Citation
+
+If you use euclimix in your research, please cite the accompanying
+[paper](https://arxiv.org/abs/2407.12208):
+
+```bibtex
+@misc{carson2024computing,
+  title         = {Computing $k$-means in mixed precision},
+  author        = {Erin Carson and Xinye Chen and Xiaobo Liu},
+  year          = {2024},
+  eprint        = {2407.12208},
+  archivePrefix = {arXiv},
+  primaryClass  = {math.NA},
+  doi           = {10.48550/arXiv.2407.12208},
+  url           = {https://arxiv.org/abs/2407.12208}
+}
+```

euclimix-0.1.0/docs/implementation.md

@@ -0,0 +1,66 @@
+# Numerical implementation
+
+The mixed-precision functions evaluate the expanded squared-distance formula,
+test each result, and recompute rejected entries using the direct formula.
+
+## Index-list implementation
+
+`pairwise_squared_distances` supports FP16, BF16 and FP32 default paths.
+FP16/BF16 inputs are quantized from the original FP32 coordinates. Squared
+norms accumulate in FP32 and are stored in the selected format. Cross
+products use cuBLAS GemmEx with FP32 compute and low-format output. The FP32
+path uses LibTorch `mm` and its matrix-multiplication policy.
+
+Distance formation, clamping to zero and threshold comparison use FP32.
+The Original test recomputes distances at or below `rho * c(r) * (p + q)`,
+where `p` and `q` are stored squared norms and `r` is the feature count:
+
+| Precision / correction | `c(r)` |
+|---|---|
+| FP16 | `(2*r + 4) * 2**-11` |
+| BF16 | `(2*r + 4) * 2**-7` |
+| FP32 / FP32 or same | `(2*r + 4) * 2**-23` |
+| FP32 / FP64 | `2*r * 2**-23` |
+
+These are empirical coefficients. The BF16 coefficient uses `2**-7`,
+whereas BF16 unit roundoff is `2**-8`.
+
+Rejected entries are appended to an index list and recomputed by a separate
+kernel. FP32/FP64 correction uses original FP32 coordinates; `same` uses
+quantized coordinates and low-format arithmetic. Mixed outputs are FP32,
+including after FP64 correction. Nonfinite expanded results or thresholds
+also trigger recomputation.
+
+## Mask-based implementation
+
+`controlled_squared_distances` supports FP16/BF16 inputs, low/FP32
+intermediate storage and Original/Extended tests. Norms use sequential FP32
+FMA. Cross products use either cuBLAS or coordinate-order FP32 FMA.
+
+The Extended bound includes input-conversion residuals, inner-product
+arithmetic, intermediate storage and gradual underflow. Bounds and thresholds
+are evaluated conservatively using directed FP64 rounding. The test accepts
+a finite squared distance `d` only when `d > upward_round(rho * B)`.
+Under the inner-product error assumption, accepted distances have relative
+error at most `1/(rho-1)`. For cuBLAS, the coefficient is an assumption about
+the library reduction; FP32 compute alone does not establish it.
+
+Both tests compute diagnostic bounds. Rejected entries are recomputed by
+scanning a mask. FP32/FP64 correction reads original FP32 inputs, with FP32
+output in the Python interface. The native interface also supports FP64 output.
+The accepted-path bound does not cover rounding after direct recomputation.
+
+## Execution
+
+All native calls use a CUDA device guard and the current PyTorch stream.
+Input storage is recorded on that stream. PyTorch configures the cuBLAS
+handle's stream and workspace; euclimix preserves them and restores modified
+math/pointer modes. Rebinding the stream would reset the workspace, as
+documented by [cuBLAS](https://docs.nvidia.com/cuda/archive/12.8.0/cublas/index.html#cublassetstream).
+
+The index-list extension uses `--use_fast_math`. The mask-based extension
+uses `--ftz=false --fmad=false --prec-div=true --prec-sqrt=true`. Separate
+modules keep these compiler settings independent. Temporary buffers and
+outputs are managed by LibTorch tensors.
+
+Algorithm and analysis: [arXiv:2407.12208](https://arxiv.org/abs/2407.12208).

euclimix-0.1.0/docs/paper_sources.json

@@ -0,0 +1,100 @@
+{
+  "paper_commit": "eb195775a59930c146bbbcf283f85608585333b0",
+  "original_files": [
+    {
+      "file": "tests/reference/center_kernels.cu",
+      "paper_file": "exps/csrc/center_kernels.cu",
+      "sha256": "16ac5f909f07d6c154a47b035fb2ee36d51fd925b017e3d0412381b21cbb3d56"
+    },
+    {
+      "file": "tests/reference/center_kernels.cuh",
+      "paper_file": "exps/csrc/center_kernels.cuh",
+      "sha256": "13e15ea723e358e3bcab28a12394e95889137fd17e6cd1d3f946f503641c9be4"
+    },
+    {
+      "file": "tests/reference/euclidean_cuda.cpp",
+      "paper_file": "exps/csrc/euclidean_cuda.cpp",
+      "sha256": "bb5e2c338bdd1e4e350427eecc054dcd5b16bd8bc34f7319ad1f7d1b4cf69314"
+    },
+    {
+      "file": "tests/reference/euclidean_cuda_advanced.cpp",
+      "paper_file": "exps/csrc/euclidean_cuda_advanced.cpp",
+      "sha256": "533f534a1eb19646ce61508a7fb6ae2b1e3ad16caa17e744d88ea0119a51cf1c"
+    },
+    {
+      "file": "tests/reference/euclidean_cuda_mix.cpp",
+      "paper_file": "exps/csrc/euclidean_cuda_mix.cpp",
+      "sha256": "1d1f8d62a2e3a68c4ea7e05992f793bf12b6d6b7577947e047d0cb3ca5933061"
+    },
+    {
+      "file": "tests/reference/euclidean_cuda_tiled.cpp",
+      "paper_file": "exps/csrc/euclidean_cuda_tiled.cpp",
+      "sha256": "f00f3a9ca93a6467bd25e532b8ba8f48c43f024a73ba5cc93fda3eb07d025c1f"
+    },
+    {
+      "file": "tests/reference/euclidean_cuda_uniform.cpp",
+      "paper_file": "exps/csrc/euclidean_cuda_uniform.cpp",
+      "sha256": "93e2bcf5fe4db75a4c57ad16ac799db61f6d1082627d21857a10d138057ae8a1"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels.cu",
+      "paper_file": "exps/csrc/euclidean_kernels.cu",
+      "sha256": "49978f3e11a8a5099bea80779d6724680db20d4385b8048f0559b2137dfd443e"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels.cuh",
+      "paper_file": "exps/csrc/euclidean_kernels.cuh",
+      "sha256": "fac538925d7f057170548a656eee6b7f022e304a574847e7ec2f48d826d27375"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels_advanced.cu",
+      "paper_file": "exps/csrc/euclidean_kernels_advanced.cu",
+      "sha256": "0ade485978bfa3ef2ab57f617bae3bc3ba19b949cf0d0fc40037b4f165bdd145"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels_advanced.cuh",
+      "paper_file": "exps/csrc/euclidean_kernels_advanced.cuh",
+      "sha256": "d8eb4b6f4392599fd0b03c4ebd37f4f2b57deafabaa066ebddd3a4bc2da5d77d"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels_mix.cu",
+      "paper_file": "exps/csrc/euclidean_kernels_mix.cu",
+      "sha256": "b8632295983c8d3a053f3e644005a12dc45a1d4187c094fd33c8eb60bb954b92"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels_mix.cuh",
+      "paper_file": "exps/csrc/euclidean_kernels_mix.cuh",
+      "sha256": "8f6b40e436a533deb80329f9aace4c1c8a4e8a5fc93fb4ff8ab5fa963df36194"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels_tiled.cu",
+      "paper_file": "exps/csrc/euclidean_kernels_tiled.cu",
+      "sha256": "aa181dd1f340ba1b5d4bf589b27afba1be46b9d2530a0449cfad7623dc16c74c"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels_tiled.cuh",
+      "paper_file": "exps/csrc/euclidean_kernels_tiled.cuh",
+      "sha256": "c3effae1d0181406f8ef9f72640f74c1f32b8af4df5a8499a90f70a6b35ee2a3"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels_tiled_tc.cu",
+      "paper_file": "exps/csrc/euclidean_kernels_tiled_tc.cu",
+      "sha256": "fba17ae0715e6316a3f512b78ad87e917fe17d365ca8f268ffa48df43237dae0"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels_uniform.cu",
+      "paper_file": "exps/csrc/euclidean_kernels_uniform.cu",
+      "sha256": "d95233345b911d95ad3e4d659114252fb4d3a8e041eb713408c3c66ecf547778"
+    },
+    {
+      "file": "tests/reference/euclidean_kernels_uniform.cuh",
+      "paper_file": "exps/csrc/euclidean_kernels_uniform.cuh",
+      "sha256": "7d4bc4c2a6cad6c08783c0dd8b8d5be964f34182cde05b96acb107438387c04a"
+    }
+  ],
+  "controlled_source": {
+    "paper_file": "exps/reviewer_experiments/csrc/reviewer_distance.cu",
+    "sha256": "aa289df82785abbfdff4065a3acef64bf056c92c71feebc69c8f9462c0d0a678"
+  },
+  "repository": "https://github.com/chenxinye/mp_kmeans_paper"
+}

euclimix-0.1.0/docs/validation.md

@@ -0,0 +1,61 @@
+# Testing
+
+Install test and build dependencies:
+
+```bash
+python -m pip install -e '.[test,build]'
+```
+
+## Python tests
+
+```bash
+python -m pytest -m 'not cuda' --cov=euclimix --cov-branch \
+  --cov-report=term-missing --cov-report=xml
+```
+
+CI requires 100% Python statement and branch coverage. Unit tests cover
+input validation, dispatch, extension loading and result statistics. Native
+entry points are stubbed in these tests; CUDA arithmetic is tested separately.
+
+## CUDA tests
+
+Use a supported NVIDIA GPU, a compatible host compiler and the CUDA toolkit:
+
+```bash
+export TORCH_CUDA_ARCH_LIST=8.0  # A100
+export MAX_JOBS=2
+python -c 'import euclimix; euclimix.build_cuda()'
+EUCLIMIX_REQUIRE_CUDA=1 python -m pytest -m cuda
+```
+
+Tests cover precision/correction modes, storage, threshold selection, near
+pairs, overflow, underflow, tensor views, autocast and nondefault streams.
+FP32 matrix-multiplication tests disable TF32 temporarily and restore the
+previous policy. The device-guard test requires two GPUs.
+
+Compare with the reference CUDA implementation:
+
+```bash
+EUCLIMIX_REQUIRE_CUDA=1 EUCLIMIX_COMPARE_PAPER=1 python -m pytest -m cuda
+```
+
+Check device memory accesses:
+
+```bash
+EUCLIMIX_REQUIRE_CUDA=1 compute-sanitizer --tool memcheck --error-exitcode=1 \
+  python -m pytest -m cuda tests/test_cuda.py
+```
+
+The native CMake examples in the README check the C++ interface and cuBLAS
+mode/stream preservation. Source checksums for the regression fixtures are
+stored in `docs/paper_sources.json`.
+
+## CI
+
+The CPU workflow runs on pushes and pull requests, builds and installs a
+wheel, and uploads test and coverage reports. The GPU workflow is manually
+dispatched on a self-hosted Linux runner labeled `self-hosted, linux, x64, gpu`.
+It requires CUDA 12.8, CMake 3.24+, compute-sanitizer and a compatible compiler.
+
+`EUCLIMIX_REQUIRE_CUDA=1` makes a missing GPU an error. Python coverage does
+not measure CUDA code.

euclimix-0.1.0/examples/native.cpp

@@ -0,0 +1,12 @@
+// Include this header from an application linked with the CMake euclimix target.
+#include <euclimix/distance.h>
+
+euclimix::DistanceResult example(torch::Tensor x, torch::Tensor y) {
+    // Original FP32 CUDA coordinates, contiguous on one device.
+    // FP16 expanded path, Original criterion, direct FP64 correction.
+    euclimix::PaperOptions options;
+    options.precision = euclimix::InputPrecision::FP16;
+    options.correction = euclimix::Correction::FP64;
+    return euclimix::paper_squared_distances(x, y, options);
+}
+

euclimix-0.1.0/examples/python_api.py

@@ -0,0 +1,15 @@
+"""Small CUDA example, including a direct FP64 reference."""
+
+import torch
+
+from euclimix import controlled_squared_distances, direct_squared_distances, pairwise_squared_distances
+
+X = torch.tensor([[0., 0.], [3., 4.]], device="cuda")
+index_list = pairwise_squared_distances(X, return_info=True)
+extended = controlled_squared_distances(X, return_info=True)
+reference = direct_squared_distances(X)
+print("Squared distances:", index_list.distances)
+print("Extended squared distances:", extended.distances)
+print("Direct FP64 reference:", reference)
+print("Recomputation fraction:", index_list.fallback_fraction)
+