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.
- {linkcell-0.3.4 → linkcell-0.3.5}/CHANGELOG.md +12 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/Cargo.lock +2 -2
- {linkcell-0.3.4 → linkcell-0.3.5}/Cargo.toml +2 -2
- {linkcell-0.3.4 → linkcell-0.3.5}/PKG-INFO +28 -18
- {linkcell-0.3.4 → linkcell-0.3.5}/README.md +26 -16
- {linkcell-0.3.4 → linkcell-0.3.5}/cbindgen.toml +3 -0
- linkcell-0.3.5/docs/explanation/mic-and-cells.md +229 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/docs/how-to/embed-c.md +1 -1
- linkcell-0.3.5/docs/reference/algorithm.md +135 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/docs/reference/c-api.md +26 -0
- linkcell-0.3.5/examples/knn_hot.rs +158 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/include/linkcell.h +39 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/include/linkcell.hpp +57 -0
- linkcell-0.3.5/linkcell/__init__.py +12 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/pyproject.toml +2 -2
- {linkcell-0.3.4 → linkcell-0.3.5}/python/Cargo.toml +1 -1
- {linkcell-0.3.4 → linkcell-0.3.5}/python/src/gpu.rs +13 -5
- {linkcell-0.3.4 → linkcell-0.3.5}/python/src/lib.rs +76 -10
- linkcell-0.3.5/src/bins.rs +342 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/src/capi.rs +116 -0
- linkcell-0.3.5/src/knearest.rs +761 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/src/lib.rs +25 -9
- linkcell-0.3.5/src/pairs.rs +270 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/tests/abi.rs +96 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/tests/agree.rs +208 -2
- {linkcell-0.3.4 → linkcell-0.3.5}/tests/python/test_knearest.py +1 -1
- linkcell-0.3.5/tests/python/test_pairs.py +70 -0
- linkcell-0.3.4/docs/explanation/mic-and-cells.md +0 -51
- linkcell-0.3.4/docs/reference/algorithm.md +0 -91
- linkcell-0.3.4/examples/knn_hot.rs +0 -43
- linkcell-0.3.4/linkcell/__init__.py +0 -11
- linkcell-0.3.4/src/knearest.rs +0 -526
- linkcell-0.3.4/src/pairs.rs +0 -244
- {linkcell-0.3.4 → linkcell-0.3.5}/.github/scripts/setup-msvc.ps1 +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/.github/workflows/ci.yml +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/.github/workflows/publish.yml +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/.github/workflows/wheels.yml +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/.gitignore +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/CITATION.cff +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/CMakeLists.txt +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/LICENSE +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/README.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/linkcell-icon.svg +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/linkcell-logo-dark.svg +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/linkcell-logo-light.svg +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/assets/branding/linkcell-mark.jpg +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/changelog.d/.gitkeep +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/changelog.d/README.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/cmake/linkcell-gpu.pc.in +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/cmake/linkcell.pc.in +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/cmake/linkcellConfig.cmake.in +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/docs/how-to/embed-cpp.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/docs/how-to/embed-python.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/docs/how-to/pkg-config.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/docs/index.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/docs/tutorials/two-points.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/examples/meson.build +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/examples/two_points.c +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/examples/two_points.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/include/linkcell_gpu.h +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/include/linkcell_gpu.hpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/meson.build +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/meson_options.txt +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/python/build.rs +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/scripts/check-install.sh +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/scripts/copy-cargo-artifacts.py +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/scripts/regen-capi-headers.sh +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/src/cell.rs +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/src/error.rs +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/src/gpu/capi.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/src/gpu/gpulite_compat.hpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/src/gpu/knearest.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/subprojects/gpulite.wrap +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/subprojects/packagefiles/gpulite/meson.build +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/tests/cmake-consumer/CMakeLists.txt +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/tests/cmake-consumer/gpu.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/tests/gpu_agree.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/tests/python/test_agree_vesin.py +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/tests/python/test_knearest_cuda.py +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/third_party/gpulite/LICENSE +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/third_party/gpulite/README.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.5}/third_party/gpulite/gpulite/gpulite.hpp +0 -0
- {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.
|
|
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.
|
|
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.
|
|
3
|
+
version = "0.3.5"
|
|
4
4
|
edition = "2021"
|
|
5
5
|
rust-version = "1.70"
|
|
6
|
-
description = "Periodic linked-cell k-nearest neighbour search
|
|
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.
|
|
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
|
|
29
|
+
Periodic linked-cell neighbour lists for molecular simulations.
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
a
|
|
35
|
-
|
|
36
|
-
|
|
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.
|
|
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
|
|
218
|
-
|
|
219
|
-
subtract plus that cell's lattice
|
|
220
|
-
`lattice_shift`), the vesin /
|
|
221
|
-
boxes use three independent
|
|
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
|
-
-
|
|
226
|
-
width.
|
|
227
|
-
|
|
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
|
|
7
|
+
Periodic linked-cell neighbour lists for molecular simulations.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
a
|
|
13
|
-
|
|
14
|
-
|
|
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.
|
|
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
|
|
196
|
-
|
|
197
|
-
subtract plus that cell's lattice
|
|
198
|
-
`lattice_shift`), the vesin /
|
|
199
|
-
boxes use three independent
|
|
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
|
-
-
|
|
204
|
-
width.
|
|
205
|
-
|
|
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.
|
|
@@ -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
|
|