linkcell 0.3.4__tar.gz → 0.3.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. {linkcell-0.3.4 → linkcell-0.3.5}/CHANGELOG.md +12 -0
  2. {linkcell-0.3.4 → linkcell-0.3.5}/Cargo.lock +2 -2
  3. {linkcell-0.3.4 → linkcell-0.3.5}/Cargo.toml +2 -2
  4. {linkcell-0.3.4 → linkcell-0.3.5}/PKG-INFO +28 -18
  5. {linkcell-0.3.4 → linkcell-0.3.5}/README.md +26 -16
  6. {linkcell-0.3.4 → linkcell-0.3.5}/cbindgen.toml +3 -0
  7. linkcell-0.3.5/docs/explanation/mic-and-cells.md +229 -0
  8. {linkcell-0.3.4 → linkcell-0.3.5}/docs/how-to/embed-c.md +1 -1
  9. linkcell-0.3.5/docs/reference/algorithm.md +135 -0
  10. {linkcell-0.3.4 → linkcell-0.3.5}/docs/reference/c-api.md +26 -0
  11. linkcell-0.3.5/examples/knn_hot.rs +158 -0
  12. {linkcell-0.3.4 → linkcell-0.3.5}/include/linkcell.h +39 -0
  13. {linkcell-0.3.4 → linkcell-0.3.5}/include/linkcell.hpp +57 -0
  14. linkcell-0.3.5/linkcell/__init__.py +12 -0
  15. {linkcell-0.3.4 → linkcell-0.3.5}/pyproject.toml +2 -2
  16. {linkcell-0.3.4 → linkcell-0.3.5}/python/Cargo.toml +1 -1
  17. {linkcell-0.3.4 → linkcell-0.3.5}/python/src/gpu.rs +13 -5
  18. {linkcell-0.3.4 → linkcell-0.3.5}/python/src/lib.rs +76 -10
  19. linkcell-0.3.5/src/bins.rs +342 -0
  20. {linkcell-0.3.4 → linkcell-0.3.5}/src/capi.rs +116 -0
  21. linkcell-0.3.5/src/knearest.rs +761 -0
  22. {linkcell-0.3.4 → linkcell-0.3.5}/src/lib.rs +25 -9
  23. linkcell-0.3.5/src/pairs.rs +270 -0
  24. {linkcell-0.3.4 → linkcell-0.3.5}/tests/abi.rs +96 -0
  25. {linkcell-0.3.4 → linkcell-0.3.5}/tests/agree.rs +208 -2
  26. {linkcell-0.3.4 → linkcell-0.3.5}/tests/python/test_knearest.py +1 -1
  27. linkcell-0.3.5/tests/python/test_pairs.py +70 -0
  28. linkcell-0.3.4/docs/explanation/mic-and-cells.md +0 -51
  29. linkcell-0.3.4/docs/reference/algorithm.md +0 -91
  30. linkcell-0.3.4/examples/knn_hot.rs +0 -43
  31. linkcell-0.3.4/linkcell/__init__.py +0 -11
  32. linkcell-0.3.4/src/knearest.rs +0 -526
  33. linkcell-0.3.4/src/pairs.rs +0 -244
  34. {linkcell-0.3.4 → linkcell-0.3.5}/.github/scripts/setup-msvc.ps1 +0 -0
  35. {linkcell-0.3.4 → linkcell-0.3.5}/.github/workflows/ci.yml +0 -0
  36. {linkcell-0.3.4 → linkcell-0.3.5}/.github/workflows/publish.yml +0 -0
  37. {linkcell-0.3.4 → linkcell-0.3.5}/.github/workflows/wheels.yml +0 -0
  38. {linkcell-0.3.4 → linkcell-0.3.5}/.gitignore +0 -0
  39. {linkcell-0.3.4 → linkcell-0.3.5}/CITATION.cff +0 -0
  40. {linkcell-0.3.4 → linkcell-0.3.5}/CMakeLists.txt +0 -0
  41. {linkcell-0.3.4 → linkcell-0.3.5}/LICENSE +0 -0
  42. {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/README.md +0 -0
  43. {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/linkcell-icon.svg +0 -0
  44. {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/linkcell-logo-dark.svg +0 -0
  45. {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/linkcell-logo-light.svg +0 -0
  46. {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/linkcell-mark.jpg +0 -0
  47. {linkcell-0.3.4 → linkcell-0.3.5}/changelog.d/.gitkeep +0 -0
  48. {linkcell-0.3.4 → linkcell-0.3.5}/changelog.d/README.md +0 -0
  49. {linkcell-0.3.4 → linkcell-0.3.5}/cmake/linkcell-gpu.pc.in +0 -0
  50. {linkcell-0.3.4 → linkcell-0.3.5}/cmake/linkcell.pc.in +0 -0
  51. {linkcell-0.3.4 → linkcell-0.3.5}/cmake/linkcellConfig.cmake.in +0 -0
  52. {linkcell-0.3.4 → linkcell-0.3.5}/docs/how-to/embed-cpp.md +0 -0
  53. {linkcell-0.3.4 → linkcell-0.3.5}/docs/how-to/embed-python.md +0 -0
  54. {linkcell-0.3.4 → linkcell-0.3.5}/docs/how-to/pkg-config.md +0 -0
  55. {linkcell-0.3.4 → linkcell-0.3.5}/docs/index.md +0 -0
  56. {linkcell-0.3.4 → linkcell-0.3.5}/docs/tutorials/two-points.md +0 -0
  57. {linkcell-0.3.4 → linkcell-0.3.5}/examples/meson.build +0 -0
  58. {linkcell-0.3.4 → linkcell-0.3.5}/examples/two_points.c +0 -0
  59. {linkcell-0.3.4 → linkcell-0.3.5}/examples/two_points.cpp +0 -0
  60. {linkcell-0.3.4 → linkcell-0.3.5}/include/linkcell_gpu.h +0 -0
  61. {linkcell-0.3.4 → linkcell-0.3.5}/include/linkcell_gpu.hpp +0 -0
  62. {linkcell-0.3.4 → linkcell-0.3.5}/meson.build +0 -0
  63. {linkcell-0.3.4 → linkcell-0.3.5}/meson_options.txt +0 -0
  64. {linkcell-0.3.4 → linkcell-0.3.5}/python/build.rs +0 -0
  65. {linkcell-0.3.4 → linkcell-0.3.5}/scripts/check-install.sh +0 -0
  66. {linkcell-0.3.4 → linkcell-0.3.5}/scripts/copy-cargo-artifacts.py +0 -0
  67. {linkcell-0.3.4 → linkcell-0.3.5}/scripts/regen-capi-headers.sh +0 -0
  68. {linkcell-0.3.4 → linkcell-0.3.5}/src/cell.rs +0 -0
  69. {linkcell-0.3.4 → linkcell-0.3.5}/src/error.rs +0 -0
  70. {linkcell-0.3.4 → linkcell-0.3.5}/src/gpu/capi.cpp +0 -0
  71. {linkcell-0.3.4 → linkcell-0.3.5}/src/gpu/gpulite_compat.hpp +0 -0
  72. {linkcell-0.3.4 → linkcell-0.3.5}/src/gpu/knearest.cpp +0 -0
  73. {linkcell-0.3.4 → linkcell-0.3.5}/subprojects/gpulite.wrap +0 -0
  74. {linkcell-0.3.4 → linkcell-0.3.5}/subprojects/packagefiles/gpulite/meson.build +0 -0
  75. {linkcell-0.3.4 → linkcell-0.3.5}/tests/cmake-consumer/CMakeLists.txt +0 -0
  76. {linkcell-0.3.4 → linkcell-0.3.5}/tests/cmake-consumer/gpu.cpp +0 -0
  77. {linkcell-0.3.4 → linkcell-0.3.5}/tests/gpu_agree.cpp +0 -0
  78. {linkcell-0.3.4 → linkcell-0.3.5}/tests/python/test_agree_vesin.py +0 -0
  79. {linkcell-0.3.4 → linkcell-0.3.5}/tests/python/test_knearest_cuda.py +0 -0
  80. {linkcell-0.3.4 → linkcell-0.3.5}/third_party/gpulite/LICENSE +0 -0
  81. {linkcell-0.3.4 → linkcell-0.3.5}/third_party/gpulite/README.md +0 -0
  82. {linkcell-0.3.4 → linkcell-0.3.5}/third_party/gpulite/gpulite/gpulite.hpp +0 -0
  83. {linkcell-0.3.4 → linkcell-0.3.5}/towncrier.toml +0 -0
@@ -10,6 +10,18 @@ by [towncrier](https://towncrier.readthedocs.io/).
10
10
 
11
11
  <!-- towncrier release notes start -->
12
12
 
13
+ ## [0.3.5] - 2026-10-04
14
+
15
+ ### Changed
16
+
17
+ - The cutoff list is on the C, C++, and Python APIs as `lc_pairs_within`, `linkcell::pairs_within`, and `linkcell.pairs_within`. Each row is an atom-image with the caller's shift `S`.
18
+ - The minimum-image note now covers closest-vector search, periodic Delaunay triangulations, the robotics kd-tree on a product of circles, tensor sketches, and crystal-graph construction. None of those replaces the cell walk on a filled cubic lattice.
19
+ - The minimum-image note now places the walk against Quentrec-Brot, Rapaport's cell shift, the Bentley-Weide-Yao cell technique, and the cutoff lists in LAMMPS, GROMACS, HOOMD, vesin, and freud. The host stop described there is the frontier plane.
20
+ - `knearest_into` stops when the k-th neighbour reaches the unvisited plane, including a neighbour that sits on that plane, and writes each packed row from the stack heap.
21
+ - `knearest` bins in a Minkowski-reduced basis and stores occupants in cell order. Shells stop on the perpendicular distance to the unvisited frontier, and a cell is skipped when its slab cannot beat the k-th neighbour. `pairs_within` uses the same bins and frontier, and still reports shifts in the caller's basis.
22
+ - k-nearest and cutoff walks grow one axis of the index box at a time, and a restricted triclinic cell is tilt-reduced before the walk. Orthorhombic films and LAMMPS tilts no longer take the cubic shell.
23
+
24
+
13
25
  ## [0.3.4] - 2026-09-27
14
26
 
15
27
  ### Added
@@ -79,7 +79,7 @@ checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
79
79
 
80
80
  [[package]]
81
81
  name = "linkcell"
82
- version = "0.3.4"
82
+ version = "0.3.5"
83
83
  dependencies = [
84
84
  "minimage",
85
85
  "rayon",
@@ -87,7 +87,7 @@ dependencies = [
87
87
 
88
88
  [[package]]
89
89
  name = "linkcell-python"
90
- version = "0.3.4"
90
+ version = "0.3.5"
91
91
  dependencies = [
92
92
  "cc",
93
93
  "dlpk",
@@ -1,9 +1,9 @@
1
1
  [package]
2
2
  name = "linkcell"
3
- version = "0.3.4"
3
+ version = "0.3.5"
4
4
  edition = "2021"
5
5
  rust-version = "1.70"
6
- description = "Periodic linked-cell k-nearest neighbour search for molecular simulations"
6
+ description = "Periodic linked-cell cutoff pairs and k-nearest neighbour search"
7
7
  license = "MIT"
8
8
  repository = "https://github.com/d-SEAMS/linkcell"
9
9
  homepage = "https://github.com/d-SEAMS/linkcell"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: linkcell
3
- Version: 0.3.4
3
+ Version: 0.3.5
4
4
  Classifier: Programming Language :: Rust
5
5
  Classifier: Programming Language :: Python :: 3
6
6
  Classifier: Programming Language :: Python :: 3.12
@@ -11,7 +11,7 @@ Requires-Dist: pytest>=8.0 ; extra == 'test'
11
11
  Requires-Dist: numpy>=1.26 ; extra == 'test'
12
12
  Provides-Extra: test
13
13
  License-File: LICENSE
14
- Summary: Periodic linked-cell k-nearest neighbour search
14
+ Summary: Periodic linked-cell cutoff pairs and k-nearest neighbour search
15
15
  Author-email: Rohit Goswami <rgoswami@ieee.org>
16
16
  License: MIT
17
17
  Requires-Python: >=3.12
@@ -26,14 +26,16 @@ Project-URL: Repository, https://github.com/d-SEAMS/linkcell
26
26
  <img src="assets/branding/linkcell-logo-light.svg" width="360" alt="linkcell">
27
27
  </p>
28
28
 
29
- Periodic **linked-cell k-nearest** neighbour search for molecular simulations.
29
+ Periodic linked-cell neighbour lists for molecular simulations.
30
30
 
31
- vesin builds cutoff pair lists. nanoflann builds Euclidean KD-trees without a
32
- minimum-image convention. This crate is the piece those two leave open: the
33
- linked-cell walk of Allen and Tildesley (*Computer Simulation of Liquids*),
34
- a k-heap per source, shells expanded until the k-th neighbour cannot sit
35
- outside the visited cube. The optional gpulite path runs that walk on a
36
- CUDA device (`linkcell::gpu::Workspace`); pair lists stay on the device.
31
+ `pairs_within` is the cutoff list: one row per atom-image, the caller's
32
+ shift `S`, and a squared distance strictly below the cutoff squared.
33
+ `knearest` is the k-nearest list. nanoflann builds Euclidean KD-trees
34
+ without a minimum-image convention. The walk is the linked-cell method
35
+ of Allen and Tildesley (*Computer Simulation of Liquids*). k-nearest
36
+ shells stop when the k-th neighbour reaches the unvisited plane. The
37
+ optional gpulite path runs that k-nearest walk on a CUDA device
38
+ (`linkcell::gpu::Workspace`).
37
39
 
38
40
  It is a LODE library. The Rust crate is the implementation. The C ABI
39
41
  (`lc_*`) is the hourglass waist, the same shape as
@@ -92,7 +94,7 @@ As a wrap, Meson exposes `linkcell_dep`:
92
94
  ```
93
95
  [wrap-git]
94
96
  url = https://github.com/d-SEAMS/linkcell.git
95
- revision = v0.3.4
97
+ revision = v0.3.5
96
98
  depth = 1
97
99
 
98
100
  [provide]
@@ -214,17 +216,25 @@ Rust API: [docs.rs/linkcell](https://docs.rs/linkcell). Map: [docs/index.md](doc
214
216
  origin. Orthorhombic boxes are `Cell::ortho` / `lc_cell_ortho`.
215
217
  Binning is in fractional space, so a sheared dump is not treated as
216
218
  orthogonal.
217
- - Points fold into the primary cell once. Each source then walks
218
- Chebyshev shells of neighbour cells. Pair distances are a Cartesian
219
- subtract plus that cell's lattice translation (`dist2_shifted` and
220
- `lattice_shift`), the vesin / LAMMPS ghost construction. Orthorhombic
221
- boxes use three independent wraps and skip the two Hinv matvecs.
219
+ - Points fold into the primary cell once. Each source then grows a
220
+ rectangular box of neighbour cells, one axis at a time. Pair
221
+ distances are a Cartesian subtract plus that cell's lattice
222
+ translation (`dist2_shifted` and `lattice_shift`), the vesin /
223
+ LAMMPS ghost construction. Orthorhombic boxes use three independent
224
+ wraps and skip the two Hinv matvecs. A restricted triclinic box is
225
+ tilt-reduced and uses a triangular shift.
222
226
  - One lattice shift per unique cell is wrong unless every wrap of that
223
227
  cell is visited. The walk visits integer cell offsets, so each wrap
224
228
  of a bin is a separate visit.
225
- - The search does not take a cutoff. A cell-size hint only sets the bin
226
- width. Shells grow until the k-heap is exact.
227
- - vesin remains the right library for a *cutoff* pair list.
229
+ - `knearest` does not take a cutoff. A cell-size hint only sets the bin
230
+ width. `knearest` stores each bin as a contiguous slice. An
231
+ orthorhombic cell is binned as stored, a restricted triclinic cell
232
+ is tilt-reduced, and a general orientation is Minkowski-reduced.
233
+ The box grows until the k-th neighbour is no farther than the
234
+ nearest unvisited face.
235
+ - A cutoff pair list is `pairs_within` / `lc_pairs_within` /
236
+ `linkcell.pairs_within`: atom-image rows with the caller's shift
237
+ `S`. `knearest` is the k-nearest list.
228
238
 
229
239
  ## License
230
240
 
@@ -4,14 +4,16 @@
4
4
  <img src="assets/branding/linkcell-logo-light.svg" width="360" alt="linkcell">
5
5
  </p>
6
6
 
7
- Periodic **linked-cell k-nearest** neighbour search for molecular simulations.
7
+ Periodic linked-cell neighbour lists for molecular simulations.
8
8
 
9
- vesin builds cutoff pair lists. nanoflann builds Euclidean KD-trees without a
10
- minimum-image convention. This crate is the piece those two leave open: the
11
- linked-cell walk of Allen and Tildesley (*Computer Simulation of Liquids*),
12
- a k-heap per source, shells expanded until the k-th neighbour cannot sit
13
- outside the visited cube. The optional gpulite path runs that walk on a
14
- CUDA device (`linkcell::gpu::Workspace`); pair lists stay on the device.
9
+ `pairs_within` is the cutoff list: one row per atom-image, the caller's
10
+ shift `S`, and a squared distance strictly below the cutoff squared.
11
+ `knearest` is the k-nearest list. nanoflann builds Euclidean KD-trees
12
+ without a minimum-image convention. The walk is the linked-cell method
13
+ of Allen and Tildesley (*Computer Simulation of Liquids*). k-nearest
14
+ shells stop when the k-th neighbour reaches the unvisited plane. The
15
+ optional gpulite path runs that k-nearest walk on a CUDA device
16
+ (`linkcell::gpu::Workspace`).
15
17
 
16
18
  It is a LODE library. The Rust crate is the implementation. The C ABI
17
19
  (`lc_*`) is the hourglass waist, the same shape as
@@ -70,7 +72,7 @@ As a wrap, Meson exposes `linkcell_dep`:
70
72
  ```
71
73
  [wrap-git]
72
74
  url = https://github.com/d-SEAMS/linkcell.git
73
- revision = v0.3.4
75
+ revision = v0.3.5
74
76
  depth = 1
75
77
 
76
78
  [provide]
@@ -192,17 +194,25 @@ Rust API: [docs.rs/linkcell](https://docs.rs/linkcell). Map: [docs/index.md](doc
192
194
  origin. Orthorhombic boxes are `Cell::ortho` / `lc_cell_ortho`.
193
195
  Binning is in fractional space, so a sheared dump is not treated as
194
196
  orthogonal.
195
- - Points fold into the primary cell once. Each source then walks
196
- Chebyshev shells of neighbour cells. Pair distances are a Cartesian
197
- subtract plus that cell's lattice translation (`dist2_shifted` and
198
- `lattice_shift`), the vesin / LAMMPS ghost construction. Orthorhombic
199
- boxes use three independent wraps and skip the two Hinv matvecs.
197
+ - Points fold into the primary cell once. Each source then grows a
198
+ rectangular box of neighbour cells, one axis at a time. Pair
199
+ distances are a Cartesian subtract plus that cell's lattice
200
+ translation (`dist2_shifted` and `lattice_shift`), the vesin /
201
+ LAMMPS ghost construction. Orthorhombic boxes use three independent
202
+ wraps and skip the two Hinv matvecs. A restricted triclinic box is
203
+ tilt-reduced and uses a triangular shift.
200
204
  - One lattice shift per unique cell is wrong unless every wrap of that
201
205
  cell is visited. The walk visits integer cell offsets, so each wrap
202
206
  of a bin is a separate visit.
203
- - The search does not take a cutoff. A cell-size hint only sets the bin
204
- width. Shells grow until the k-heap is exact.
205
- - vesin remains the right library for a *cutoff* pair list.
207
+ - `knearest` does not take a cutoff. A cell-size hint only sets the bin
208
+ width. `knearest` stores each bin as a contiguous slice. An
209
+ orthorhombic cell is binned as stored, a restricted triclinic cell
210
+ is tilt-reduced, and a general orientation is Minkowski-reduced.
211
+ The box grows until the k-th neighbour is no farther than the
212
+ nearest unvisited face.
213
+ - A cutoff pair list is `pairs_within` / `lc_pairs_within` /
214
+ `linkcell.pairs_within`: atom-image rows with the caller's shift
215
+ `S`. `knearest` is the k-nearest list.
206
216
 
207
217
  ## License
208
218
 
@@ -23,6 +23,8 @@ header = """
23
23
  * - lc_knearest writes into caller-owned out_nn (length n * k).
24
24
  * - lc_knearest_d2 also writes out_d2 (length n * k, unused NaN).
25
25
  * - lc_knearest_many is the frame-major batch (n_frames * n * k).
26
+ * - lc_pairs_within writes caller-owned i, j, shift, dist2 rows.
27
+ * Null outputs query the row count.
26
28
  * - lc_last_error returns a thread-local pointer. Do not free. The
27
29
  * pointer is invalid after the next lc_knearest on the same thread.
28
30
  * lc_version does not read or write the slot.
@@ -104,6 +106,7 @@ include = [
104
106
  "lc_knearest",
105
107
  "lc_knearest_d2",
106
108
  "lc_knearest_many",
109
+ "lc_pairs_within",
107
110
  "lc_last_error",
108
111
  "lc_version",
109
112
  ]
@@ -0,0 +1,229 @@
1
+ # Minimum image and linked cells
2
+
3
+ The production walk does not compute a fractional minimum image on
4
+ every pair. The Hinv formula `s = H^{-1} (r_j - r_i)`, wrap each
5
+ component to the central cell, then `r = H s`, is the brute-force
6
+ `Cell::dist2` path on a general box. The linked-cell search folds
7
+ once, then adds a lattice shift per neighbour cell.
8
+
9
+ ## Fold once, then shift
10
+
11
+ Every active point is wrapped into the primary cell (`fractional`
12
+ then `cartesian`) and binned there. After that, a neighbour in a
13
+ periodic image is the same point plus an integer combination of the
14
+ lattice vectors. vesin and LAMMPS call those copies ghosts.
15
+
16
+ `Cell::lattice_shift(na, nb, nc)` is that translation. The pair
17
+ loop is `dist2_shifted`: `|q + shift - p|^2`. No wrap, no `Hinv`,
18
+ one subtract. The device walk uses the same shift: `na a + nb b +
19
+ nc c`. Orthorhombic boxes keep the cheap path (`H` diagonal).
20
+
21
+ Orthorhombic boxes skip the two 3x3 matvecs everywhere they can:
22
+ `fractional` divides by the three widths, `lattice_shift` multiplies
23
+ those widths, and brute `dist2` is three independent wraps.
24
+
25
+ ## One shift per cell is wrong
26
+
27
+ The bins live in the primary cell. Cell `(ix + nx, iy, iz)` is the
28
+ same linked list as `(ix, iy, iz)`, but it is a different wrap:
29
+ `lattice_shift(1, 0, 0)`, not the identity.
30
+
31
+ If the walk records each unique bin once and applies a single
32
+ shift (the minimum image of the cell centre, or the first visit),
33
+ it drops the other images of those points. A pair close across a
34
+ face, edge, or corner can sit in a wrap that visit never reaches.
35
+
36
+ The walk in `knearest` therefore iterates integer cell offsets
37
+ `(dx, dy, dz)` and takes `div_euclid` for the shift. The same
38
+ primary bin is visited once per wrap the Chebyshev shell reaches.
39
+ That is the vesin-style construction: every wrap is a visit. One
40
+ shift per cell is correct only when every wrap is visited.
41
+
42
+ The offsets are taken in a Minkowski-reduced basis of the same
43
+ lattice, so a short vector such as `a - b` is a cell edge. Reduction
44
+ does not change which Cartesian images exist. It does not by itself
45
+ make the nearest image one of the 27 shifts: an unreduced dump can
46
+ need an original shift such as `(-7, 7, 0)`. The walk keeps expanding
47
+ shells until the k-th neighbour is no farther than the unvisited
48
+ frontier plane, or until the shell covers a space diagonal.
49
+ `pairs_within` does not reduce: its shift is the caller's `S`.
50
+
51
+ ## Cutoff pair lists
52
+
53
+ vesin answers "who is inside radius r". This crate answers "who are
54
+ the k nearest, with the periodic image". The search takes no
55
+ cutoff. `cell_hint` only sizes the bins. Shells grow until the
56
+ k-th neighbour is certified against the frontier plane. The device
57
+ walk still stops on the looser `reach * cell_min` bound, which is
58
+ that plane distance when the source sits on the outer face of its
59
+ cell.
60
+
61
+ nanoflann answers the same k question in Euclidean space without a
62
+ minimum-image convention. A periodic dump still needs the fold and
63
+ the wraps above.
64
+
65
+ ## What the literature actually specifies
66
+
67
+ The linked-cell search is Quentrec and Brot, *J. Comput. Phys.* **13**,
68
+ 430 (1973). Allen and Tildesley, *Computer Simulation of Liquids*, is
69
+ the textbook form: a linked list, a half stencil of 13 neighbour
70
+ cells, and a per-pair nearest integer. Rapaport, *The Art of
71
+ Molecular Dynamics Simulation* (Cambridge, 2nd ed., 2004), stores the
72
+ same cells and forms the pair as the Cartesian difference plus the
73
+ lattice shift of that neighbour cell. `dist2_shifted` is Rapaport's
74
+ pair, not Allen and Tildesley's `ANINT`.
75
+
76
+ Exact k-nearest neighbours, with no cutoff, are not in those books.
77
+ Bentley, Weide, and Yao, *ACM Trans. Math. Softw.* **6**, 563 (1980),
78
+ state the cell technique for that problem: bin a bounded distribution,
79
+ then expand square layers, and stop when every unsearched bin misses
80
+ the ball of the current neighbour. The Chebyshev shells and the
81
+ frontier plane are that test on a periodic lattice. A precomputed
82
+ stencil (LAMMPS `NStencil`, Allen and Tildesley's `MAP`) is the same
83
+ set when the radius is an input. A k-nearest radius is not known
84
+ until the heap fills, so the shell grows.
85
+
86
+ Nguyen and Stehlé, *ACM Trans. Algorithms* **5**, 46 (2009), produce
87
+ the Minkowski-reduced basis this walk bins in. Conway and Sloane,
88
+ *Proc. R. Soc. Lond. A* **436**, 55 (1992), prove a different fact:
89
+ every three-dimensional lattice has an obtuse superbase (Selling,
90
+ 1874), and the Voronoi vectors are then `{-1,0,1}` combinations of
91
+ that superbase. Nearest-integer rounding in a Minkowski basis is not
92
+ that certificate. The walk does not stop at 27 images.
93
+
94
+ Welling and Germano, *Comput. Phys. Commun.* **182**, 611 (2011),
95
+ compare the later cell-list variants on the same footing. Gonnet's
96
+ projection sort beats a plain cell list only above roughly 19
97
+ particles per cell. A filled cubic lattice has one particle per cell,
98
+ so the walk computes the distance instead of projecting.
99
+
100
+ The cells this crate is called on are not that cube. eOn and readcon
101
+ store orthorhombic CON frames, often a film plus vacuum. seams walks
102
+ LAMMPS dumps, including restricted triclinic ice (an `xy` tilt).
103
+ rgsaddle's band cell includes a hexagonal prism. Those are
104
+ orthorhombic or tilt-reduced restricted cells. The index box grows
105
+ only on the axis whose plane is still inside the k-th neighbour, so
106
+ a short face does not drag the long faces out to the same shell.
107
+
108
+ ## Codes that answer a different question
109
+
110
+ LAMMPS, GROMACS, HOOMD-blue, OpenMM, and NAMD build a cutoff list,
111
+ usually with a skin and a rebuild. A half stencil (Newton's third
112
+ law, GROMACS's 14 images, Allen and Tildesley's 13) stores each pair
113
+ once. That is wrong for k-nearest neighbours: `j` can be among the
114
+ `k` nearest of `i` while `i` is not among the `k` nearest of `j`.
115
+ GROMACS and OpenMM also require a tilt-reduced triclinic box and a
116
+ cutoff short enough that one image suffices. Copying that stop onto
117
+ an unreduced cell drops a closer shift.
118
+
119
+ vesin and ASE `neighbor_list` are cutoff cell lists. The stencil is
120
+ sized from the face distances, so a long cutoff walks past 27 images,
121
+ and the reported vector is `r_j - r_i + S H`. Sorting that list is a
122
+ k-nearest answer only when the cutoff already contains the k-th
123
+ neighbour. freud (`AABBQuery` / `LinkCell`, Ramasubramani et al.,
124
+ *Comput. Phys. Commun.* **254**, 107275, 2020) does take a neighbour
125
+ count on a triclinic box. The query grows a ball. It is the closest
126
+ peer, and it is still a ball of limited images, not this frontier
127
+ certificate. `scipy.spatial.cKDTree` with `boxsize` is exact on an
128
+ orthorhombic torus and has no triclinic metric.
129
+
130
+ A bounding-volume hierarchy (Howard, Anderson, Nikoubashman, Glotzer,
131
+ and Panagiotopoulos, *Comput. Phys. Commun.* **203**, 45, 2016) wins
132
+ for a cutoff when particle sizes differ. HOOMD's own comparison is
133
+ that the cell list wins when every particle has essentially the same
134
+ range. Verlet skins reuse a cutoff list across timesteps. This
135
+ search is one configuration and has no radius it may legally freeze.
136
+
137
+ ## Geometry, algebra, robotics, tensors, graphs
138
+
139
+ These are the places a molecular-dynamics reading does not look.
140
+ None of them replaces the cell walk on a filled cubic lattice. Two
141
+ of them are the exact certificates for the skewed cell, and they
142
+ answer a different query than "the k nearest sites."
143
+
144
+ **Closest lattice vector.** Agrell, Eriksson, Vardy, and Zeger,
145
+ *IEEE Trans. Inf. Theory* **48**, 2201 (2002), survey closest-point
146
+ search. Schnorr–Euchner enumeration walks lattice layers in order of
147
+ orthogonal distance and stops when the next layer is farther than the
148
+ best point already found. The layer index is not confined to
149
+ `{-1,0,1}`. Babai's nearest plane (*Combinatorica* **6**, 1, 1986)
150
+ keeps only one layer per dimension and can miss the same image a
151
+ 27-image loop misses. McKilliam, Grant, and Clarkson, *SIAM J.
152
+ Discrete Math.* **28**, 1405 (2014), start from the component-wise
153
+ floor in an obtuse superbasis and add a series of relevant vectors.
154
+ Every lattice of dimension less than 4 has such a superbasis, and
155
+ the series reaches a closest lattice point in at most as many steps
156
+ as the dimension. The vector it returns is the closest lattice point
157
+ to one displacement. It does not say which other site is the k-th
158
+ neighbour.
159
+ On the cubic hot path the closest coefficient is already inside the
160
+ first shell, so the certificate does not change the neighbour list
161
+ and does not remove any bin visits.
162
+
163
+ **Periodic Delaunay.** Caroli and Teillaud, ESA 2009, compute the
164
+ Delaunay triangulation of the cubic flat torus, keeping one copy of
165
+ each point once the complex is simplicial, and a finite-sheeted cover
166
+ otherwise. CGAL's `Periodic_3_Delaunay_triangulation_3` implements
167
+ that cubic torus and can return the nearest vertex. Osang,
168
+ Rouxel-Labbé, and Teillaud, ESA 2020, extend it to a general lattice
169
+ by reducing to an obtuse superbase and folding each point with a
170
+ closest-vector query. The dual is an exact 1-nearest structure. The
171
+ link of a vertex is not the 4 nearest neighbours: a site's fourth
172
+ neighbour need not be a Delaunay edge. Dickerson and Eppstein,
173
+ *Comput. Geom.* **5**, 277 (1996), recover the k nearest from a
174
+ Delaunay search in `O(k n log n)` in Euclidean space, with no
175
+ periodic quotient. Lee, *IEEE Trans. Comput.* **C-31**, 478 (1982),
176
+ builds the order-k Voronoi diagram in the plane. The proved cost of
177
+ the 3D periodic triangulation is the same `O(n^2)` worst case as a
178
+ Delaunay triangulation in `R^3`. A cell list on this sample is linear.
179
+ Callahan and Kosaraju, *J. ACM* **42**, 67 (1995), get all k-nearest
180
+ neighbours from a well-separated pair decomposition in Euclidean
181
+ space. A decomposition of one fundamental domain misses a pair that
182
+ is close only after a lattice translation. No tensor train, Gröbner
183
+ basis, or cylindrical algebraic decomposition turned up as the
184
+ decision procedure for this query. The identity that decides the
185
+ closest lattice vector in three dimensions is the obtuse superbase
186
+ already cited above.
187
+
188
+ **Robotics.** Yershova and LaValle, *IEEE Trans. Robot.* **23**, 151
189
+ (2007), extend Arya and Mount's kd-tree to a product of lines,
190
+ circles, and `RP^3`. On `(S^1)^3` the distance is the Euclidean
191
+ minimum image of an orthorhombic box, and a node is discarded only
192
+ when the circular distance to its rectangle is already worse than
193
+ the best point seen. The proof is for one neighbour. The same prune
194
+ is the wrong Euclidean distance on a skewed cell, because the metric
195
+ no longer splits across axes. Ichnowski and Alterovitz, WAFR 2014,
196
+ search `SO(3)` and `SE(3)` with four kd-trees on the quaternion
197
+ 3-sphere. That distance is a great-arc plus a translation, not
198
+ `R^3` modulo a lattice. OMPL's torus state space is the embedded
199
+ doughnut surface, and GNAT answers queries in the metric that
200
+ surface supplies. Cover trees and GNAT likewise answer queries in
201
+ the metric they are given. Neither constructs the lattice images of
202
+ a periodic box. Pan,
203
+ Lauterbach, and Manocha, IROS 2010, use locality-sensitive hashing,
204
+ which they state is approximate.
205
+
206
+ **Tensors.** Jégou, Douze, and Schmid, *IEEE TPAMI* **33**, 117
207
+ (2011), product-quantize a Cartesian product of subspaces. The
208
+ codes are approximate. Pham and Pagh, KDD 2013, sketch a polynomial
209
+ kernel. Novikov, Gneushev, Kadeishvili, and Oseledets, arXiv:2410.04462
210
+ (2024), use a tensor train as an approximate point-cloud index, with
211
+ no periodic cell. The orthorhombic minimum image is a sum of three
212
+ circular distances, which is why the ortho path never multiplies by
213
+ `H`. That is the product metric above, not a tensor decomposition.
214
+
215
+ **Graph construction.** Crystal networks take a cutoff ball, or k
216
+ neighbours from inside a ball. Xie and Grossman, *Phys. Rev. Lett.*
217
+ **120**, 145301 (2018), keep 12 neighbours inside a fixed radius, so
218
+ the 12th neighbour outside that ball is absent. ALIGNN grows the
219
+ radius until 12 neighbours exist and then keeps the whole shell.
220
+ fairchem's periodic radius graph repeats the lattice out to
221
+ `ceil(radius / face height)` and then caps the list. Park and
222
+ Wolverton, *Phys. Rev. Materials* **4**, 063801 (2020), connect
223
+ Voronoi neighbours instead. A Voronoi face can be longer than a
224
+ non-neighbour, so that graph is not the k nearest sites. Ruff,
225
+ Reiser, Stühmer, and Friederich, *Digital Discovery* **3**, 594
226
+ (2024), compare periodic k-nearest, radius, and Voronoi edges and
227
+ keep k = 24. NequIP, Allegro, and MACE consume a cutoff list. None
228
+ of these is an uncapped Euclidean k-nearest walk, and none of them
229
+ adds a bin test this search does not already apply.
@@ -20,7 +20,7 @@ the pointer.
20
20
  ```
21
21
  [wrap-git]
22
22
  url = https://github.com/d-SEAMS/linkcell.git
23
- revision = v0.3.4
23
+ revision = v0.3.5
24
24
  depth = 1
25
25
 
26
26
  [provide]
@@ -0,0 +1,135 @@
1
+ # Algorithm
2
+
3
+ Linked-cell k-nearest search in `src/knearest.rs`. Allen and
4
+ Tildesley linked cells, a k-heap per source, and a rectangular index
5
+ box that grows until the k-th neighbour cannot lie past an unvisited
6
+ face. The search takes no cutoff.
7
+
8
+ ## Inputs
9
+
10
+ - `xyz`: Cartesian points.
11
+ - `simbox`: periodic parallelepiped (`Cell` / `lc_cell`).
12
+ - `k`: neighbours per source. Must be at least 1.
13
+ - `mask`: optional. `false` / zero drops a point as source and as
14
+ candidate.
15
+ - `cell_hint`: target bin edge. `None` or `<= 0` uses 3.0, then the
16
+ value is clamped to the smallest perpendicular box width.
17
+
18
+ Each source keeps `min(k, n_active - 1)` neighbours. Packed outputs
19
+ fill unused slots with `-1`.
20
+
21
+ ## Fold and bin
22
+
23
+ 1. Take fractional coordinates in `[0, 1)` (`Cell::fractional`).
24
+ 2. Store the Cartesian image in the primary cell (`Cell::cartesian`).
25
+ 3. Bin in fractional space: `floor(s * n*)`, clamped to
26
+ `[0, n* - 1]`.
27
+ 4. Count occupants per bin, exclusive-scan the counts, and store the
28
+ active indices in cell order.
29
+
30
+ `nx, ny, nz` are `floor(width / edge)`, at least 1. `cell_min` is the
31
+ smallest of the three actual cell edges (perpendicular width over
32
+ count). Orthorhombic boxes wrap each lattice direction independently;
33
+ a sheared box uses `Hinv` only for this fold.
34
+
35
+ ## Shells
36
+
37
+ For each source, walk integer cell offsets `(dx, dy, dz)`. The first
38
+ visit is the 3×3×3 around the home bin. After that the index box
39
+ grows one axis at a time: an axis whose unvisited plane is already
40
+ farther than the k-th neighbour stays put, and a short face can take
41
+ another layer while the long faces do not. A cube shell is the case
42
+ where all three planes fail together. `max_reach` is the space
43
+ diagonal of the walk cell, in units of the shortest bin edge, and at
44
+ least half the longest bin count.
45
+
46
+ Each offset maps to:
47
+
48
+ - a primary bin, `rem_euclid` on the cell indices
49
+ - a lattice translation, `div_euclid` counts through
50
+ `Cell::lattice_shift`
51
+
52
+ The pair distance is `Cell::dist2_shifted`: Cartesian subtract of the
53
+ folded points plus that shift. The inner loop does not wrap with
54
+ `Hinv`.
55
+
56
+ The same primary bin can appear under more than one wrap. Each wrap
57
+ is a separate visit. Skipping those repeats (one shift per unique
58
+ bin) misses images. That construction, and the ortho cheap path, is
59
+ in [MIC and cells](../explanation/mic-and-cells.md).
60
+
61
+ ## Basis
62
+
63
+ An orthorhombic box is already the basis the shells walk.
64
+ A restricted triclinic box (LAMMPS dump bounds, a CON file with a
65
+ non-right angle, the cells seams and rgsaddle pass) is tilt-reduced
66
+ in place, GROMACS `correct_box`, and the shift is the triangular
67
+ product. A general orientation is Minkowski-reduced (Nguyen–Stehlé).
68
+ The basis spans the same Cartesian lattice. A 27-image check on that
69
+ basis can still miss a closer shift; the shell cap is the space
70
+ diagonal divided by the minimum cell height, and the frontier test
71
+ stops the walk once the k-th neighbour is certified.
72
+ `pairs_within` keeps the caller's basis, because the returned shift
73
+ `S` is an integer combination of that H. Its index box grows the
74
+ same way, one axis at a time, out to the cutoff. The C, C++, and
75
+ Python entries are that list (`lc_pairs_within`,
76
+ `linkcell::pairs_within`, `linkcell.pairs_within`). A cutoff
77
+ neighbour list is this call.
78
+
79
+ ## Heap and stop
80
+
81
+ A max-heap of size `k` stores `(dist2, index)`, ordered
82
+ lexicographically so an equal distance keeps the smaller index. For
83
+ `k <= 16` it lives on the stack. Occupants of a bin are a contiguous
84
+ slice. A cell is skipped when the perpendicular distance from the
85
+ source to that image's slab is already at least the worst heap entry.
86
+
87
+ After each shell, if the heap is full and the worst `dist2` is at
88
+ most the squared perpendicular distance to the nearest unvisited
89
+ lattice plane, the walk stops. Bins are half-open, so every unvisited
90
+ point lies strictly past that plane: a neighbour that sits on the
91
+ plane is still the nearest, and shrinking the plane would walk another
92
+ shell. The older `reach * cell_min` bound is that distance when the
93
+ source sits on the outer face of its cell; a source in the interior
94
+ stops sooner. The device walk still uses `reach * cell_min`, which is
95
+ a lower bound on the same plane, so it does not stop earlier.
96
+
97
+ `knearest` returns `Neighbors` rows (`indices`, `dist2`), nearest
98
+ first. `knearest_into` / `lc_knearest` write packed indices.
99
+ `knearest_into_d2` / `lc_knearest_d2` also write squared distances.
100
+ `knearest_into_many` / `lc_knearest_many` cover a frame-major batch.
101
+
102
+ `knearest_brute` is the all-pairs check used by tests and small
103
+ systems. It calls `Cell::dist2_euclidean` per pair: Smith half-edge
104
+ test, then a Minkowski-reduced 27-image. The 27-image of an
105
+ unreduced H misses lattice points such as `2(a-b)`. The fractional
106
+ wrap of a hex-prism body diagonal is not nearest. It is not the
107
+ production walk.
108
+
109
+ The citations are in [MIC and cells](../explanation/mic-and-cells.md).
110
+ The pair kernel is Rapaport's cell shift. The expanding shells are
111
+ Bentley, Weide, and Yao's cell technique. Schnorr–Euchner enumeration
112
+ and McKilliam, Grant, and Clarkson's obtuse-superbase search certify
113
+ the closest lattice vector; they do not list the k nearest sites.
114
+ A periodic Delaunay triangulation certifies the nearest site, not the
115
+ fourth. A kd-tree on a product of circles (Yershova and LaValle) is
116
+ exact for one neighbour on an orthorhombic torus. Crystal-graph
117
+ builders take a cutoff, or k neighbours inside a ball.
118
+
119
+ ## Parallel
120
+
121
+ The `parallel` Cargo feature (on by default) maps sources with
122
+ rayon. Each source owns its heap.
123
+
124
+ ## Device
125
+
126
+ `linkcell::gpu::Workspace` is the same walk on a CUDA device. Fold,
127
+ bin, then a tiled Hillis-Steele exclusive scan (CUB DeviceScan /
128
+ HOOMD cell offsets). Occupants are stored in cell-major order with
129
+ an O(1) home slot. The stencil is a precomputed Chebyshev shell
130
+ table (LAMMPS `NStencil`, HOOMD `d_cell_adj`), not a nested 3-D
131
+ loop. Eight threads share each source and stride occupants; after
132
+ each shell they merge heaps and apply the host stop. Output is
133
+ Cabana's 2-D packed `n * k` list. `knearest_into_many` covers every
134
+ frame that shares a cell. Fold uses `Hinv`; the pair shift is
135
+ `na a + nb b + nc c`. `k <= 16`.
@@ -51,6 +51,20 @@ int lc_knearest_many(const double *xyz, size_t n, size_t n_frames,
51
51
 
52
52
  `lc_knearest` is the one-frame, indices-only entry. Returns 0 on success, nonzero on failure.
53
53
 
54
+ ```c
55
+ int lc_pairs_within(const double *xyz, size_t n, const lc_cell *simbox,
56
+ double cutoff, const int *mask, double cell_hint,
57
+ int half, int *out_i, int *out_j, int *out_shift,
58
+ double *out_d2, size_t cap, size_t *out_count);
59
+ ```
60
+
61
+ A cutoff list is `lc_pairs_within`. Each row is one atom-image.
62
+ `out_shift[3 * t + 0..3]` is `(na, nb, nc)`, the vesin / tonari shift
63
+ `S` in the caller's basis. Squared distance is strictly below
64
+ `cutoff * cutoff`. `half` nonzero keeps one side of `(i, j, S)`.
65
+ Null `out_i`, `out_j`, `out_shift`, and `out_d2` query `*out_count`.
66
+ A short `cap` writes that count and returns nonzero.
67
+
54
68
  ## Errors and version
55
69
 
56
70
  ```c
@@ -98,6 +112,18 @@ Neighbours knearest(const double *xyz, std::size_t n, const Cell &cell,
98
112
  double cell_hint = 0.0);
99
113
 
100
114
  const char *version();
115
+
116
+ struct ShiftedPair {
117
+ int i, j;
118
+ std::array<int, 3> shift;
119
+ double dist2;
120
+ };
121
+
122
+ std::vector<ShiftedPair> pairs_within(const double *xyz, std::size_t n,
123
+ const Cell &cell, double cutoff,
124
+ const int *mask = nullptr,
125
+ double cell_hint = 0.0,
126
+ bool half = false);
101
127
  }
102
128
  ```
103
129