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.
- {linkcell-0.3.4 → linkcell-0.3.6}/CHANGELOG.md +27 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/Cargo.lock +4 -4
- {linkcell-0.3.4 → linkcell-0.3.6}/Cargo.toml +3 -3
- {linkcell-0.3.4 → linkcell-0.3.6}/PKG-INFO +34 -18
- {linkcell-0.3.4 → linkcell-0.3.6}/README.md +33 -17
- linkcell-0.3.6/build.rs +30 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/cbindgen.toml +3 -0
- linkcell-0.3.6/docs/explanation/mic-and-cells.md +244 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/docs/how-to/embed-c.md +1 -1
- linkcell-0.3.6/docs/reference/algorithm.md +202 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/docs/reference/c-api.md +26 -0
- linkcell-0.3.6/examples/knn_hot.rs +158 -0
- linkcell-0.3.6/examples/knn_scale.rs +107 -0
- linkcell-0.3.6/examples/pairs_scale.rs +95 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/include/linkcell.h +39 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/include/linkcell.hpp +57 -0
- linkcell-0.3.6/linkcell/__init__.py +12 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/meson.build +1 -1
- {linkcell-0.3.4 → linkcell-0.3.6}/pyproject.toml +2 -2
- {linkcell-0.3.4 → linkcell-0.3.6}/python/Cargo.toml +1 -1
- {linkcell-0.3.4 → linkcell-0.3.6}/python/src/gpu.rs +13 -5
- {linkcell-0.3.4 → linkcell-0.3.6}/python/src/lib.rs +76 -10
- linkcell-0.3.6/scripts/bench-kokkos.sh +25 -0
- linkcell-0.3.6/scripts/bench-pairs.sh +17 -0
- linkcell-0.3.6/scripts/bench-strong.sh +19 -0
- linkcell-0.3.6/scripts/cutoff_work.py +79 -0
- linkcell-0.3.6/scripts/pop-report.py +61 -0
- linkcell-0.3.6/src/bins.rs +567 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/src/capi.rs +116 -0
- linkcell-0.3.6/src/cell.rs +35 -0
- linkcell-0.3.6/src/knearest.rs +900 -0
- linkcell-0.3.6/src/kokkos/CMakeLists.txt +8 -0
- linkcell-0.3.6/src/kokkos/bench.cpp +267 -0
- linkcell-0.3.6/src/kokkos/knearest.cpp +758 -0
- linkcell-0.3.6/src/kokkos/knearest.hpp +32 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/src/lib.rs +37 -11
- linkcell-0.3.6/src/pairs.rs +1532 -0
- linkcell-0.3.6/src/pop.rs +198 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/tests/abi.rs +96 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/tests/agree.rs +208 -2
- {linkcell-0.3.4 → linkcell-0.3.6}/tests/python/test_knearest.py +1 -1
- linkcell-0.3.6/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/cell.rs +0 -8
- 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.6}/.github/scripts/setup-msvc.ps1 +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/.github/workflows/ci.yml +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/.github/workflows/publish.yml +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/.github/workflows/wheels.yml +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/.gitignore +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/CITATION.cff +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/CMakeLists.txt +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/LICENSE +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/README.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/linkcell-icon.svg +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/linkcell-logo-dark.svg +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/linkcell-logo-light.svg +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/assets/branding/linkcell-mark.jpg +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/changelog.d/.gitkeep +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/changelog.d/README.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/cmake/linkcell-gpu.pc.in +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/cmake/linkcell.pc.in +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/cmake/linkcellConfig.cmake.in +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/docs/how-to/embed-cpp.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/docs/how-to/embed-python.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/docs/how-to/pkg-config.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/docs/index.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/docs/tutorials/two-points.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/examples/meson.build +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/examples/two_points.c +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/examples/two_points.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/include/linkcell_gpu.h +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/include/linkcell_gpu.hpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/meson_options.txt +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/python/build.rs +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/scripts/check-install.sh +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/scripts/copy-cargo-artifacts.py +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/scripts/regen-capi-headers.sh +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/src/error.rs +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/src/gpu/capi.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/src/gpu/gpulite_compat.hpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/src/gpu/knearest.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/subprojects/gpulite.wrap +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/subprojects/packagefiles/gpulite/meson.build +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/tests/cmake-consumer/CMakeLists.txt +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/tests/cmake-consumer/gpu.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/tests/gpu_agree.cpp +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/tests/python/test_agree_vesin.py +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/tests/python/test_knearest_cuda.py +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/third_party/gpulite/LICENSE +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/third_party/gpulite/README.md +0 -0
- {linkcell-0.3.4 → linkcell-0.3.6}/third_party/gpulite/gpulite/gpulite.hpp +0 -0
- {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.
|
|
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.
|
|
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.
|
|
111
|
+
version = "0.1.3"
|
|
112
112
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
113
|
-
checksum = "
|
|
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.
|
|
3
|
+
version = "0.3.6"
|
|
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"
|
|
@@ -26,7 +26,7 @@ capi = []
|
|
|
26
26
|
parallel = ["dep:rayon"]
|
|
27
27
|
|
|
28
28
|
[dependencies]
|
|
29
|
-
minimage = "0.1.
|
|
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.
|
|
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
|
|
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 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.
|
|
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
|
|
218
|
-
|
|
219
|
-
subtract plus that cell's lattice
|
|
220
|
-
`lattice_shift`), the vesin /
|
|
221
|
-
boxes use three independent
|
|
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
|
-
-
|
|
226
|
-
width.
|
|
227
|
-
|
|
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
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
a
|
|
13
|
-
|
|
14
|
-
|
|
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.
|
|
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
|
|
196
|
-
|
|
197
|
-
subtract plus that cell's lattice
|
|
198
|
-
`lattice_shift`), the vesin /
|
|
199
|
-
boxes use three independent
|
|
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
|
-
-
|
|
204
|
-
width.
|
|
205
|
-
|
|
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
|
|
linkcell-0.3.6/build.rs
ADDED
|
@@ -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.
|