linkcell 0.3.4__tar.gz → 0.3.6__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 (97) hide show
  1. {linkcell-0.3.4 → linkcell-0.3.6}/CHANGELOG.md +27 -0
  2. {linkcell-0.3.4 → linkcell-0.3.6}/Cargo.lock +4 -4
  3. {linkcell-0.3.4 → linkcell-0.3.6}/Cargo.toml +3 -3
  4. {linkcell-0.3.4 → linkcell-0.3.6}/PKG-INFO +34 -18
  5. {linkcell-0.3.4 → linkcell-0.3.6}/README.md +33 -17
  6. linkcell-0.3.6/build.rs +30 -0
  7. {linkcell-0.3.4 → linkcell-0.3.6}/cbindgen.toml +3 -0
  8. linkcell-0.3.6/docs/explanation/mic-and-cells.md +244 -0
  9. {linkcell-0.3.4 → linkcell-0.3.6}/docs/how-to/embed-c.md +1 -1
  10. linkcell-0.3.6/docs/reference/algorithm.md +202 -0
  11. {linkcell-0.3.4 → linkcell-0.3.6}/docs/reference/c-api.md +26 -0
  12. linkcell-0.3.6/examples/knn_hot.rs +158 -0
  13. linkcell-0.3.6/examples/knn_scale.rs +107 -0
  14. linkcell-0.3.6/examples/pairs_scale.rs +95 -0
  15. {linkcell-0.3.4 → linkcell-0.3.6}/include/linkcell.h +39 -0
  16. {linkcell-0.3.4 → linkcell-0.3.6}/include/linkcell.hpp +57 -0
  17. linkcell-0.3.6/linkcell/__init__.py +12 -0
  18. {linkcell-0.3.4 → linkcell-0.3.6}/meson.build +1 -1
  19. {linkcell-0.3.4 → linkcell-0.3.6}/pyproject.toml +2 -2
  20. {linkcell-0.3.4 → linkcell-0.3.6}/python/Cargo.toml +1 -1
  21. {linkcell-0.3.4 → linkcell-0.3.6}/python/src/gpu.rs +13 -5
  22. {linkcell-0.3.4 → linkcell-0.3.6}/python/src/lib.rs +76 -10
  23. linkcell-0.3.6/scripts/bench-kokkos.sh +25 -0
  24. linkcell-0.3.6/scripts/bench-pairs.sh +17 -0
  25. linkcell-0.3.6/scripts/bench-strong.sh +19 -0
  26. linkcell-0.3.6/scripts/cutoff_work.py +79 -0
  27. linkcell-0.3.6/scripts/pop-report.py +61 -0
  28. linkcell-0.3.6/src/bins.rs +567 -0
  29. {linkcell-0.3.4 → linkcell-0.3.6}/src/capi.rs +116 -0
  30. linkcell-0.3.6/src/cell.rs +35 -0
  31. linkcell-0.3.6/src/knearest.rs +900 -0
  32. linkcell-0.3.6/src/kokkos/CMakeLists.txt +8 -0
  33. linkcell-0.3.6/src/kokkos/bench.cpp +267 -0
  34. linkcell-0.3.6/src/kokkos/knearest.cpp +758 -0
  35. linkcell-0.3.6/src/kokkos/knearest.hpp +32 -0
  36. {linkcell-0.3.4 → linkcell-0.3.6}/src/lib.rs +37 -11
  37. linkcell-0.3.6/src/pairs.rs +1532 -0
  38. linkcell-0.3.6/src/pop.rs +198 -0
  39. {linkcell-0.3.4 → linkcell-0.3.6}/tests/abi.rs +96 -0
  40. {linkcell-0.3.4 → linkcell-0.3.6}/tests/agree.rs +208 -2
  41. {linkcell-0.3.4 → linkcell-0.3.6}/tests/python/test_knearest.py +1 -1
  42. linkcell-0.3.6/tests/python/test_pairs.py +70 -0
  43. linkcell-0.3.4/docs/explanation/mic-and-cells.md +0 -51
  44. linkcell-0.3.4/docs/reference/algorithm.md +0 -91
  45. linkcell-0.3.4/examples/knn_hot.rs +0 -43
  46. linkcell-0.3.4/linkcell/__init__.py +0 -11
  47. linkcell-0.3.4/src/cell.rs +0 -8
  48. linkcell-0.3.4/src/knearest.rs +0 -526
  49. linkcell-0.3.4/src/pairs.rs +0 -244
  50. {linkcell-0.3.4 → linkcell-0.3.6}/.github/scripts/setup-msvc.ps1 +0 -0
  51. {linkcell-0.3.4 → linkcell-0.3.6}/.github/workflows/ci.yml +0 -0
  52. {linkcell-0.3.4 → linkcell-0.3.6}/.github/workflows/publish.yml +0 -0
  53. {linkcell-0.3.4 → linkcell-0.3.6}/.github/workflows/wheels.yml +0 -0
  54. {linkcell-0.3.4 → linkcell-0.3.6}/.gitignore +0 -0
  55. {linkcell-0.3.4 → linkcell-0.3.6}/CITATION.cff +0 -0
  56. {linkcell-0.3.4 → linkcell-0.3.6}/CMakeLists.txt +0 -0
  57. {linkcell-0.3.4 → linkcell-0.3.6}/LICENSE +0 -0
  58. {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/README.md +0 -0
  59. {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/linkcell-icon.svg +0 -0
  60. {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/linkcell-logo-dark.svg +0 -0
  61. {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/linkcell-logo-light.svg +0 -0
  62. {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/linkcell-mark.jpg +0 -0
  63. {linkcell-0.3.4 → linkcell-0.3.6}/changelog.d/.gitkeep +0 -0
  64. {linkcell-0.3.4 → linkcell-0.3.6}/changelog.d/README.md +0 -0
  65. {linkcell-0.3.4 → linkcell-0.3.6}/cmake/linkcell-gpu.pc.in +0 -0
  66. {linkcell-0.3.4 → linkcell-0.3.6}/cmake/linkcell.pc.in +0 -0
  67. {linkcell-0.3.4 → linkcell-0.3.6}/cmake/linkcellConfig.cmake.in +0 -0
  68. {linkcell-0.3.4 → linkcell-0.3.6}/docs/how-to/embed-cpp.md +0 -0
  69. {linkcell-0.3.4 → linkcell-0.3.6}/docs/how-to/embed-python.md +0 -0
  70. {linkcell-0.3.4 → linkcell-0.3.6}/docs/how-to/pkg-config.md +0 -0
  71. {linkcell-0.3.4 → linkcell-0.3.6}/docs/index.md +0 -0
  72. {linkcell-0.3.4 → linkcell-0.3.6}/docs/tutorials/two-points.md +0 -0
  73. {linkcell-0.3.4 → linkcell-0.3.6}/examples/meson.build +0 -0
  74. {linkcell-0.3.4 → linkcell-0.3.6}/examples/two_points.c +0 -0
  75. {linkcell-0.3.4 → linkcell-0.3.6}/examples/two_points.cpp +0 -0
  76. {linkcell-0.3.4 → linkcell-0.3.6}/include/linkcell_gpu.h +0 -0
  77. {linkcell-0.3.4 → linkcell-0.3.6}/include/linkcell_gpu.hpp +0 -0
  78. {linkcell-0.3.4 → linkcell-0.3.6}/meson_options.txt +0 -0
  79. {linkcell-0.3.4 → linkcell-0.3.6}/python/build.rs +0 -0
  80. {linkcell-0.3.4 → linkcell-0.3.6}/scripts/check-install.sh +0 -0
  81. {linkcell-0.3.4 → linkcell-0.3.6}/scripts/copy-cargo-artifacts.py +0 -0
  82. {linkcell-0.3.4 → linkcell-0.3.6}/scripts/regen-capi-headers.sh +0 -0
  83. {linkcell-0.3.4 → linkcell-0.3.6}/src/error.rs +0 -0
  84. {linkcell-0.3.4 → linkcell-0.3.6}/src/gpu/capi.cpp +0 -0
  85. {linkcell-0.3.4 → linkcell-0.3.6}/src/gpu/gpulite_compat.hpp +0 -0
  86. {linkcell-0.3.4 → linkcell-0.3.6}/src/gpu/knearest.cpp +0 -0
  87. {linkcell-0.3.4 → linkcell-0.3.6}/subprojects/gpulite.wrap +0 -0
  88. {linkcell-0.3.4 → linkcell-0.3.6}/subprojects/packagefiles/gpulite/meson.build +0 -0
  89. {linkcell-0.3.4 → linkcell-0.3.6}/tests/cmake-consumer/CMakeLists.txt +0 -0
  90. {linkcell-0.3.4 → linkcell-0.3.6}/tests/cmake-consumer/gpu.cpp +0 -0
  91. {linkcell-0.3.4 → linkcell-0.3.6}/tests/gpu_agree.cpp +0 -0
  92. {linkcell-0.3.4 → linkcell-0.3.6}/tests/python/test_agree_vesin.py +0 -0
  93. {linkcell-0.3.4 → linkcell-0.3.6}/tests/python/test_knearest_cuda.py +0 -0
  94. {linkcell-0.3.4 → linkcell-0.3.6}/third_party/gpulite/LICENSE +0 -0
  95. {linkcell-0.3.4 → linkcell-0.3.6}/third_party/gpulite/README.md +0 -0
  96. {linkcell-0.3.4 → linkcell-0.3.6}/third_party/gpulite/gpulite/gpulite.hpp +0 -0
  97. {linkcell-0.3.4 → linkcell-0.3.6}/towncrier.toml +0 -0
@@ -10,6 +10,33 @@ by [towncrier](https://towncrier.readthedocs.io/).
10
10
 
11
11
  <!-- towncrier release notes start -->
12
12
 
13
+ ## [0.3.6] - 2026-10-04
14
+
15
+ ### Changed
16
+
17
+ - Orthorhombic brute-force neighbours call minimage's Highway kernel (`dist2_ortho_diffs`). `pairs_within` still records the stencil shift and does not wrap that difference a second time. The batch helpers are re-exported.
18
+ - Scale probes always record the POP3 hierarchy: load balance, communication efficiency, parallel efficiency, then computation scaling and global efficiency against the 1-thread run. `scripts/bench-pairs.sh` prints that table for the cutoff list.
19
+ - The crate depends on minimage 0.1.3.
20
+ - The mesh build is parallel from 8192 active points, and `src/kokkos` runs the certified walk on a Kokkos execution space. Scaling runs report the POP hierarchy: load balance, communication efficiency, parallel efficiency, computation scaling, and global efficiency. On this 8-core host a cubic 262144-point, k=4 search has global efficiency 0.74 at 8 threads (10.7 ms); the Kokkos OpenMP backend has global efficiency 0.56 at 8 threads (14.5 ms). This host has no PMU and no CUDA device.
21
+ - `pairs_within` buffers cutoff hits and, with more than one thread and at least 512 atoms, writes disjoint ranges of one pair buffer. A full list still has both shifts. On Linux that buffer stays on the heap so a repeated call does not fault those pages again. On this host a periodic 18 Å cube, 4 Å cutoff, and 4096 atoms is 0.8 ms once the buffer is warm on 8 threads, and the first call is about 4 ms. vesin's cell list tests twice as many distances on that grid; `scripts/cutoff_work.py` reduces the ratio to 2.
22
+
23
+ ### Fixed
24
+
25
+ - The Meson project version matches the crate version.
26
+
27
+
28
+ ## [0.3.5] - 2026-10-04
29
+
30
+ ### Changed
31
+
32
+ - 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`.
33
+ - 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.
34
+ - 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.
35
+ - `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.
36
+ - `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.
37
+ - 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.
38
+
39
+
13
40
  ## [0.3.4] - 2026-09-27
14
41
 
15
42
  ### 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.6"
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.6"
91
91
  dependencies = [
92
92
  "cc",
93
93
  "dlpk",
@@ -108,9 +108,9 @@ dependencies = [
108
108
 
109
109
  [[package]]
110
110
  name = "minimage"
111
- version = "0.1.2"
111
+ version = "0.1.3"
112
112
  source = "registry+https://github.com/rust-lang/crates.io-index"
113
- checksum = "ad8f0c3ad52d3a9253be305dfee0ce9412d3f008784a031e346cc9de8700ee0e"
113
+ checksum = "5b5871b19bca370f68bde5836914dcb7ca0aeca856eb8333233436841db1fbe7"
114
114
 
115
115
  [[package]]
116
116
  name = "ndarray"
@@ -1,9 +1,9 @@
1
1
  [package]
2
2
  name = "linkcell"
3
- version = "0.3.4"
3
+ version = "0.3.6"
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"
@@ -26,7 +26,7 @@ capi = []
26
26
  parallel = ["dep:rayon"]
27
27
 
28
28
  [dependencies]
29
- minimage = "0.1.2"
29
+ minimage = "0.1.3"
30
30
  rayon = { version = "1.10", optional = true }
31
31
 
32
32
  [[test]]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: linkcell
3
- Version: 0.3.4
3
+ Version: 0.3.6
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,18 @@ 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 and
38
+ still stops on the looser `reach * cell_min` bound
39
+ (`linkcell::gpu::Workspace`). `src/kokkos/` is the certified walk on
40
+ a Kokkos execution space. Pair lists stay on the host.
37
41
 
38
42
  It is a LODE library. The Rust crate is the implementation. The C ABI
39
43
  (`lc_*`) is the hourglass waist, the same shape as
@@ -92,7 +96,7 @@ As a wrap, Meson exposes `linkcell_dep`:
92
96
  ```
93
97
  [wrap-git]
94
98
  url = https://github.com/d-SEAMS/linkcell.git
95
- revision = v0.3.4
99
+ revision = v0.3.6
96
100
  depth = 1
97
101
 
98
102
  [provide]
@@ -214,17 +218,29 @@ Rust API: [docs.rs/linkcell](https://docs.rs/linkcell). Map: [docs/index.md](doc
214
218
  origin. Orthorhombic boxes are `Cell::ortho` / `lc_cell_ortho`.
215
219
  Binning is in fractional space, so a sheared dump is not treated as
216
220
  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.
221
+ - Points fold into the primary cell once. Each source then grows a
222
+ rectangular box of neighbour cells, one axis at a time. Pair
223
+ distances are a Cartesian subtract plus that cell's lattice
224
+ translation (`dist2_shifted` and `lattice_shift`), the vesin /
225
+ LAMMPS ghost construction. Orthorhombic boxes use three independent
226
+ wraps and skip the two Hinv matvecs. The batched form of that wrap
227
+ is minimage's Highway kernel, `dist2_ortho_diffs`, re-exported here
228
+ and used by the orthorhombic brute-force check. A cutoff row keeps
229
+ the stencil image, so `pairs_within` does not run that round on an
230
+ already shifted difference. A restricted triclinic box is
231
+ tilt-reduced and uses a triangular shift.
222
232
  - One lattice shift per unique cell is wrong unless every wrap of that
223
233
  cell is visited. The walk visits integer cell offsets, so each wrap
224
234
  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.
235
+ - `knearest` does not take a cutoff. A cell-size hint only sets the bin
236
+ width. `knearest` stores each bin as a contiguous slice. An
237
+ orthorhombic cell is binned as stored, a restricted triclinic cell
238
+ is tilt-reduced, and a general orientation is Minkowski-reduced.
239
+ The box grows until the k-th neighbour is no farther than the
240
+ nearest unvisited face.
241
+ - A cutoff pair list is `pairs_within` / `lc_pairs_within` /
242
+ `linkcell.pairs_within`: atom-image rows with the caller's shift
243
+ `S`. `knearest` is the k-nearest list.
228
244
 
229
245
  ## License
230
246
 
@@ -4,14 +4,18 @@
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.
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.
7
+ Periodic linked-cell neighbour lists for molecular simulations.
8
+
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 and
16
+ still stops on the looser `reach * cell_min` bound
17
+ (`linkcell::gpu::Workspace`). `src/kokkos/` is the certified walk on
18
+ a Kokkos execution space. Pair lists stay on the host.
15
19
 
16
20
  It is a LODE library. The Rust crate is the implementation. The C ABI
17
21
  (`lc_*`) is the hourglass waist, the same shape as
@@ -70,7 +74,7 @@ As a wrap, Meson exposes `linkcell_dep`:
70
74
  ```
71
75
  [wrap-git]
72
76
  url = https://github.com/d-SEAMS/linkcell.git
73
- revision = v0.3.4
77
+ revision = v0.3.6
74
78
  depth = 1
75
79
 
76
80
  [provide]
@@ -192,17 +196,29 @@ Rust API: [docs.rs/linkcell](https://docs.rs/linkcell). Map: [docs/index.md](doc
192
196
  origin. Orthorhombic boxes are `Cell::ortho` / `lc_cell_ortho`.
193
197
  Binning is in fractional space, so a sheared dump is not treated as
194
198
  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.
199
+ - Points fold into the primary cell once. Each source then grows a
200
+ rectangular box of neighbour cells, one axis at a time. Pair
201
+ distances are a Cartesian subtract plus that cell's lattice
202
+ translation (`dist2_shifted` and `lattice_shift`), the vesin /
203
+ LAMMPS ghost construction. Orthorhombic boxes use three independent
204
+ wraps and skip the two Hinv matvecs. The batched form of that wrap
205
+ is minimage's Highway kernel, `dist2_ortho_diffs`, re-exported here
206
+ and used by the orthorhombic brute-force check. A cutoff row keeps
207
+ the stencil image, so `pairs_within` does not run that round on an
208
+ already shifted difference. A restricted triclinic box is
209
+ tilt-reduced and uses a triangular shift.
200
210
  - One lattice shift per unique cell is wrong unless every wrap of that
201
211
  cell is visited. The walk visits integer cell offsets, so each wrap
202
212
  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.
213
+ - `knearest` does not take a cutoff. A cell-size hint only sets the bin
214
+ width. `knearest` stores each bin as a contiguous slice. An
215
+ orthorhombic cell is binned as stored, a restricted triclinic cell
216
+ is tilt-reduced, and a general orientation is Minkowski-reduced.
217
+ The box grows until the k-th neighbour is no farther than the
218
+ nearest unvisited face.
219
+ - A cutoff pair list is `pairs_within` / `lc_pairs_within` /
220
+ `linkcell.pairs_within`: atom-image rows with the caller's shift
221
+ `S`. `knearest` is the k-nearest list.
206
222
 
207
223
  ## License
208
224
 
@@ -0,0 +1,30 @@
1
+ fn main() {
2
+ println!("cargo:rerun-if-changed=build.rs");
3
+ let (major, minor) = rustc_version();
4
+ // `unexpected_cfgs` arrived in 1.80. AVX-512 intrinsics arrived in 1.89.
5
+ if major > 1 || minor >= 80 {
6
+ println!("cargo:rustc-check-cfg=cfg(linkcell_avx512)");
7
+ }
8
+ if major > 1 || minor >= 89 {
9
+ println!("cargo:rustc-cfg=linkcell_avx512");
10
+ }
11
+ }
12
+
13
+ fn rustc_version() -> (u32, u32) {
14
+ let rustc = std::env::var("RUSTC").unwrap_or_else(|_| "rustc".to_string());
15
+ let out = std::process::Command::new(rustc)
16
+ .arg("-vV")
17
+ .output()
18
+ .expect("rustc -vV");
19
+ let text = String::from_utf8_lossy(&out.stdout);
20
+ for line in text.lines() {
21
+ if let Some(rest) = line.strip_prefix("release: ") {
22
+ let ver = rest.split('-').next().unwrap_or(rest);
23
+ let mut parts = ver.split('.');
24
+ let major = parts.next().unwrap_or("1").parse().unwrap_or(1);
25
+ let minor = parts.next().unwrap_or("70").parse().unwrap_or(70);
26
+ return (major, minor);
27
+ }
28
+ }
29
+ (1, 70)
30
+ }
@@ -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,244 @@
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
+ ## Highway batch
26
+
27
+ `dist2_ortho_diffs` is minimage's orthorhombic minimum-image kernel,
28
+ the same arithmetic as Highway `BatchPeriodicDistSq`. Differences
29
+ are packed `dx, dy, dz`. One reciprocal per axis is hoisted, then
30
+ `dr = abs(dr)` and `dr -= L * round(dr / L)`. `knearest_brute` calls
31
+ that on a rectangular box. `pairs_within` does not. Its rows are one
32
+ chosen image `S`, and the distance is `dist2_shifted`. Feeding that
33
+ shifted delta through the round pulls a far image back inside the
34
+ cutoff and stores it under the stencil's `S`, which is a different
35
+ image. `reduce_pairs` is the other minimage helper: it collapses a
36
+ vesin list to one pair and drops the self image. The cutoff list
37
+ keeps every in-range image, so it does not call that reduction.
38
+
39
+ ## One shift per cell is wrong
40
+
41
+ The bins live in the primary cell. Cell `(ix + nx, iy, iz)` is the
42
+ same linked list as `(ix, iy, iz)`, but it is a different wrap:
43
+ `lattice_shift(1, 0, 0)`, not the identity.
44
+
45
+ If the walk records each unique bin once and applies a single
46
+ shift (the minimum image of the cell centre, or the first visit),
47
+ it drops the other images of those points. A pair close across a
48
+ face, edge, or corner can sit in a wrap that visit never reaches.
49
+
50
+ The walk in `knearest` therefore iterates integer cell offsets
51
+ `(dx, dy, dz)` and takes `div_euclid` for the shift. The same
52
+ primary bin is visited once per wrap the Chebyshev shell reaches.
53
+ That is the vesin-style construction: every wrap is a visit. One
54
+ shift per cell is correct only when every wrap is visited.
55
+
56
+ The offsets are taken in a Minkowski-reduced basis of the same
57
+ lattice, so a short vector such as `a - b` is a cell edge. Reduction
58
+ does not change which Cartesian images exist. It does not by itself
59
+ make the nearest image one of the 27 shifts: an unreduced dump can
60
+ need an original shift such as `(-7, 7, 0)`. The walk keeps expanding
61
+ shells until the k-th neighbour is no farther than the unvisited
62
+ frontier plane, or until the shell covers a space diagonal.
63
+ `pairs_within` does not reduce: its shift is the caller's `S`.
64
+
65
+ ## Cutoff pair lists
66
+
67
+ vesin answers "who is inside radius r". This crate answers "who are
68
+ the k nearest, with the periodic image". The search takes no
69
+ cutoff. `cell_hint` only sizes the bins. Shells grow until the
70
+ k-th neighbour is certified against the frontier plane. The gpulite
71
+ device walk still stops on the looser `reach * cell_min` bound, which
72
+ is that plane distance when the source sits on the outer face of its
73
+ cell. The Kokkos walk in `src/kokkos/` uses the host plane stop on
74
+ whatever execution space Kokkos was built with.
75
+
76
+ nanoflann answers the same k question in Euclidean space without a
77
+ minimum-image convention. A periodic dump still needs the fold and
78
+ the wraps above.
79
+
80
+ ## What the literature actually specifies
81
+
82
+ The linked-cell search is Quentrec and Brot, *J. Comput. Phys.* **13**,
83
+ 430 (1973). Allen and Tildesley, *Computer Simulation of Liquids*, is
84
+ the textbook form: a linked list, a half stencil of 13 neighbour
85
+ cells, and a per-pair nearest integer. Rapaport, *The Art of
86
+ Molecular Dynamics Simulation* (Cambridge, 2nd ed., 2004), stores the
87
+ same cells and forms the pair as the Cartesian difference plus the
88
+ lattice shift of that neighbour cell. `dist2_shifted` is Rapaport's
89
+ pair, not Allen and Tildesley's `ANINT`.
90
+
91
+ Exact k-nearest neighbours, with no cutoff, are not in those books.
92
+ Bentley, Weide, and Yao, *ACM Trans. Math. Softw.* **6**, 563 (1980),
93
+ state the cell technique for that problem: bin a bounded distribution,
94
+ then expand square layers, and stop when every unsearched bin misses
95
+ the ball of the current neighbour. The Chebyshev shells and the
96
+ frontier plane are that test on a periodic lattice. A precomputed
97
+ stencil (LAMMPS `NStencil`, Allen and Tildesley's `MAP`) is the same
98
+ set when the radius is an input. A k-nearest radius is not known
99
+ until the heap fills, so the shell grows.
100
+
101
+ Nguyen and Stehlé, *ACM Trans. Algorithms* **5**, 46 (2009), produce
102
+ the Minkowski-reduced basis this walk bins in. Conway and Sloane,
103
+ *Proc. R. Soc. Lond. A* **436**, 55 (1992), prove a different fact:
104
+ every three-dimensional lattice has an obtuse superbase (Selling,
105
+ 1874), and the Voronoi vectors are then `{-1,0,1}` combinations of
106
+ that superbase. Nearest-integer rounding in a Minkowski basis is not
107
+ that certificate. The walk does not stop at 27 images.
108
+
109
+ Welling and Germano, *Comput. Phys. Commun.* **182**, 611 (2011),
110
+ compare the later cell-list variants on the same footing. Gonnet's
111
+ projection sort beats a plain cell list only above roughly 19
112
+ particles per cell. A filled cubic lattice has one particle per cell,
113
+ so the walk computes the distance instead of projecting.
114
+
115
+ The cells this crate is called on are not that cube. eOn and readcon
116
+ store orthorhombic CON frames, often a film plus vacuum. seams walks
117
+ LAMMPS dumps, including restricted triclinic ice (an `xy` tilt).
118
+ rgsaddle's band cell includes a hexagonal prism. Those are
119
+ orthorhombic or tilt-reduced restricted cells. The index box grows
120
+ only on the axis whose plane is still inside the k-th neighbour, so
121
+ a short face does not drag the long faces out to the same shell.
122
+
123
+ ## Codes that answer a different question
124
+
125
+ LAMMPS, GROMACS, HOOMD-blue, OpenMM, and NAMD build a cutoff list,
126
+ usually with a skin and a rebuild. A half stencil (Newton's third
127
+ law, GROMACS's 14 images, Allen and Tildesley's 13) stores each pair
128
+ once. That is wrong for k-nearest neighbours: `j` can be among the
129
+ `k` nearest of `i` while `i` is not among the `k` nearest of `j`.
130
+ GROMACS and OpenMM also require a tilt-reduced triclinic box and a
131
+ cutoff short enough that one image suffices. Copying that stop onto
132
+ an unreduced cell drops a closer shift.
133
+
134
+ vesin and ASE `neighbor_list` are cutoff cell lists. The stencil is
135
+ sized from the face distances, so a long cutoff walks past 27 images,
136
+ and the reported vector is `r_j - r_i + S H`. Sorting that list is a
137
+ k-nearest answer only when the cutoff already contains the k-th
138
+ neighbour. freud (`AABBQuery` / `LinkCell`, Ramasubramani et al.,
139
+ *Comput. Phys. Commun.* **254**, 107275, 2020) does take a neighbour
140
+ count on a triclinic box. The query grows a ball. It is the closest
141
+ peer, and it is still a ball of limited images, not this frontier
142
+ certificate. `scipy.spatial.cKDTree` with `boxsize` is exact on an
143
+ orthorhombic torus and has no triclinic metric.
144
+
145
+ A bounding-volume hierarchy (Howard, Anderson, Nikoubashman, Glotzer,
146
+ and Panagiotopoulos, *Comput. Phys. Commun.* **203**, 45, 2016) wins
147
+ for a cutoff when particle sizes differ. HOOMD's own comparison is
148
+ that the cell list wins when every particle has essentially the same
149
+ range. Verlet skins reuse a cutoff list across timesteps. This
150
+ search is one configuration and has no radius it may legally freeze.
151
+
152
+ ## Geometry, algebra, robotics, tensors, graphs
153
+
154
+ These are the places a molecular-dynamics reading does not look.
155
+ None of them replaces the cell walk on a filled cubic lattice. Two
156
+ of them are the exact certificates for the skewed cell, and they
157
+ answer a different query than "the k nearest sites."
158
+
159
+ **Closest lattice vector.** Agrell, Eriksson, Vardy, and Zeger,
160
+ *IEEE Trans. Inf. Theory* **48**, 2201 (2002), survey closest-point
161
+ search. Schnorr–Euchner enumeration walks lattice layers in order of
162
+ orthogonal distance and stops when the next layer is farther than the
163
+ best point already found. The layer index is not confined to
164
+ `{-1,0,1}`. Babai's nearest plane (*Combinatorica* **6**, 1, 1986)
165
+ keeps only one layer per dimension and can miss the same image a
166
+ 27-image loop misses. McKilliam, Grant, and Clarkson, *SIAM J.
167
+ Discrete Math.* **28**, 1405 (2014), start from the component-wise
168
+ floor in an obtuse superbasis and add a series of relevant vectors.
169
+ Every lattice of dimension less than 4 has such a superbasis, and
170
+ the series reaches a closest lattice point in at most as many steps
171
+ as the dimension. The vector it returns is the closest lattice point
172
+ to one displacement. It does not say which other site is the k-th
173
+ neighbour.
174
+ On the cubic hot path the closest coefficient is already inside the
175
+ first shell, so the certificate does not change the neighbour list
176
+ and does not remove any bin visits.
177
+
178
+ **Periodic Delaunay.** Caroli and Teillaud, ESA 2009, compute the
179
+ Delaunay triangulation of the cubic flat torus, keeping one copy of
180
+ each point once the complex is simplicial, and a finite-sheeted cover
181
+ otherwise. CGAL's `Periodic_3_Delaunay_triangulation_3` implements
182
+ that cubic torus and can return the nearest vertex. Osang,
183
+ Rouxel-Labbé, and Teillaud, ESA 2020, extend it to a general lattice
184
+ by reducing to an obtuse superbase and folding each point with a
185
+ closest-vector query. The dual is an exact 1-nearest structure. The
186
+ link of a vertex is not the 4 nearest neighbours: a site's fourth
187
+ neighbour need not be a Delaunay edge. Dickerson and Eppstein,
188
+ *Comput. Geom.* **5**, 277 (1996), recover the k nearest from a
189
+ Delaunay search in `O(k n log n)` in Euclidean space, with no
190
+ periodic quotient. Lee, *IEEE Trans. Comput.* **C-31**, 478 (1982),
191
+ builds the order-k Voronoi diagram in the plane. The proved cost of
192
+ the 3D periodic triangulation is the same `O(n^2)` worst case as a
193
+ Delaunay triangulation in `R^3`. A cell list on this sample is linear.
194
+ Callahan and Kosaraju, *J. ACM* **42**, 67 (1995), get all k-nearest
195
+ neighbours from a well-separated pair decomposition in Euclidean
196
+ space. A decomposition of one fundamental domain misses a pair that
197
+ is close only after a lattice translation. No tensor train, Gröbner
198
+ basis, or cylindrical algebraic decomposition turned up as the
199
+ decision procedure for this query. The identity that decides the
200
+ closest lattice vector in three dimensions is the obtuse superbase
201
+ already cited above.
202
+
203
+ **Robotics.** Yershova and LaValle, *IEEE Trans. Robot.* **23**, 151
204
+ (2007), extend Arya and Mount's kd-tree to a product of lines,
205
+ circles, and `RP^3`. On `(S^1)^3` the distance is the Euclidean
206
+ minimum image of an orthorhombic box, and a node is discarded only
207
+ when the circular distance to its rectangle is already worse than
208
+ the best point seen. The proof is for one neighbour. The same prune
209
+ is the wrong Euclidean distance on a skewed cell, because the metric
210
+ no longer splits across axes. Ichnowski and Alterovitz, WAFR 2014,
211
+ search `SO(3)` and `SE(3)` with four kd-trees on the quaternion
212
+ 3-sphere. That distance is a great-arc plus a translation, not
213
+ `R^3` modulo a lattice. OMPL's torus state space is the embedded
214
+ doughnut surface, and GNAT answers queries in the metric that
215
+ surface supplies. Cover trees and GNAT likewise answer queries in
216
+ the metric they are given. Neither constructs the lattice images of
217
+ a periodic box. Pan,
218
+ Lauterbach, and Manocha, IROS 2010, use locality-sensitive hashing,
219
+ which they state is approximate.
220
+
221
+ **Tensors.** Jégou, Douze, and Schmid, *IEEE TPAMI* **33**, 117
222
+ (2011), product-quantize a Cartesian product of subspaces. The
223
+ codes are approximate. Pham and Pagh, KDD 2013, sketch a polynomial
224
+ kernel. Novikov, Gneushev, Kadeishvili, and Oseledets, arXiv:2410.04462
225
+ (2024), use a tensor train as an approximate point-cloud index, with
226
+ no periodic cell. The orthorhombic minimum image is a sum of three
227
+ circular distances, which is why the ortho path never multiplies by
228
+ `H`. That is the product metric above, not a tensor decomposition.
229
+
230
+ **Graph construction.** Crystal networks take a cutoff ball, or k
231
+ neighbours from inside a ball. Xie and Grossman, *Phys. Rev. Lett.*
232
+ **120**, 145301 (2018), keep 12 neighbours inside a fixed radius, so
233
+ the 12th neighbour outside that ball is absent. ALIGNN grows the
234
+ radius until 12 neighbours exist and then keeps the whole shell.
235
+ fairchem's periodic radius graph repeats the lattice out to
236
+ `ceil(radius / face height)` and then caps the list. Park and
237
+ Wolverton, *Phys. Rev. Materials* **4**, 063801 (2020), connect
238
+ Voronoi neighbours instead. A Voronoi face can be longer than a
239
+ non-neighbour, so that graph is not the k nearest sites. Ruff,
240
+ Reiser, Stühmer, and Friederich, *Digital Discovery* **3**, 594
241
+ (2024), compare periodic k-nearest, radius, and Voronoi edges and
242
+ keep k = 24. NequIP, Allegro, and MACE consume a cutoff list. None
243
+ of these is an uncapped Euclidean k-nearest walk, and none of them
244
+ 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.6
24
24
  depth = 1
25
25
 
26
26
  [provide]