linkcell 0.3.5__tar.gz → 0.3.7__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 (92) hide show
  1. {linkcell-0.3.5 → linkcell-0.3.7}/CHANGELOG.md +21 -0
  2. {linkcell-0.3.5 → linkcell-0.3.7}/Cargo.lock +4 -4
  3. {linkcell-0.3.5 → linkcell-0.3.7}/Cargo.toml +2 -2
  4. {linkcell-0.3.5 → linkcell-0.3.7}/PKG-INFO +11 -5
  5. {linkcell-0.3.5 → linkcell-0.3.7}/README.md +10 -4
  6. linkcell-0.3.7/build.rs +30 -0
  7. {linkcell-0.3.5 → linkcell-0.3.7}/docs/explanation/mic-and-cells.md +19 -4
  8. {linkcell-0.3.5 → linkcell-0.3.7}/docs/how-to/embed-c.md +1 -1
  9. {linkcell-0.3.5 → linkcell-0.3.7}/docs/reference/algorithm.md +83 -16
  10. linkcell-0.3.7/examples/knn_scale.rs +107 -0
  11. linkcell-0.3.7/examples/pairs_scale.rs +95 -0
  12. {linkcell-0.3.5 → linkcell-0.3.7}/meson.build +1 -1
  13. {linkcell-0.3.5 → linkcell-0.3.7}/pyproject.toml +1 -1
  14. {linkcell-0.3.5 → linkcell-0.3.7}/python/Cargo.toml +1 -1
  15. linkcell-0.3.7/scripts/bench-kokkos.sh +25 -0
  16. linkcell-0.3.7/scripts/bench-pairs.sh +17 -0
  17. linkcell-0.3.7/scripts/bench-strong.sh +19 -0
  18. linkcell-0.3.7/scripts/cutoff_work.py +79 -0
  19. linkcell-0.3.7/scripts/pop-report.py +61 -0
  20. {linkcell-0.3.5 → linkcell-0.3.7}/src/bins.rs +261 -36
  21. linkcell-0.3.7/src/cell.rs +35 -0
  22. {linkcell-0.3.5 → linkcell-0.3.7}/src/knearest.rs +159 -20
  23. linkcell-0.3.7/src/kokkos/CMakeLists.txt +8 -0
  24. linkcell-0.3.7/src/kokkos/bench.cpp +267 -0
  25. linkcell-0.3.7/src/kokkos/knearest.cpp +758 -0
  26. linkcell-0.3.7/src/kokkos/knearest.hpp +32 -0
  27. {linkcell-0.3.5 → linkcell-0.3.7}/src/lib.rs +12 -2
  28. linkcell-0.3.7/src/pairs.rs +1594 -0
  29. linkcell-0.3.7/src/pop.rs +198 -0
  30. {linkcell-0.3.5 → linkcell-0.3.7}/tests/python/test_knearest.py +1 -1
  31. linkcell-0.3.5/src/cell.rs +0 -8
  32. linkcell-0.3.5/src/pairs.rs +0 -270
  33. {linkcell-0.3.5 → linkcell-0.3.7}/.github/scripts/setup-msvc.ps1 +0 -0
  34. {linkcell-0.3.5 → linkcell-0.3.7}/.github/workflows/ci.yml +0 -0
  35. {linkcell-0.3.5 → linkcell-0.3.7}/.github/workflows/publish.yml +0 -0
  36. {linkcell-0.3.5 → linkcell-0.3.7}/.github/workflows/wheels.yml +0 -0
  37. {linkcell-0.3.5 → linkcell-0.3.7}/.gitignore +0 -0
  38. {linkcell-0.3.5 → linkcell-0.3.7}/CITATION.cff +0 -0
  39. {linkcell-0.3.5 → linkcell-0.3.7}/CMakeLists.txt +0 -0
  40. {linkcell-0.3.5 → linkcell-0.3.7}/LICENSE +0 -0
  41. {linkcell-0.3.5 → linkcell-0.3.7}/assets/branding/README.md +0 -0
  42. {linkcell-0.3.5 → linkcell-0.3.7}/assets/branding/linkcell-icon.svg +0 -0
  43. {linkcell-0.3.5 → linkcell-0.3.7}/assets/branding/linkcell-logo-dark.svg +0 -0
  44. {linkcell-0.3.5 → linkcell-0.3.7}/assets/branding/linkcell-logo-light.svg +0 -0
  45. {linkcell-0.3.5 → linkcell-0.3.7}/assets/branding/linkcell-mark.jpg +0 -0
  46. {linkcell-0.3.5 → linkcell-0.3.7}/cbindgen.toml +0 -0
  47. {linkcell-0.3.5 → linkcell-0.3.7}/changelog.d/.gitkeep +0 -0
  48. {linkcell-0.3.5 → linkcell-0.3.7}/changelog.d/README.md +0 -0
  49. {linkcell-0.3.5 → linkcell-0.3.7}/cmake/linkcell-gpu.pc.in +0 -0
  50. {linkcell-0.3.5 → linkcell-0.3.7}/cmake/linkcell.pc.in +0 -0
  51. {linkcell-0.3.5 → linkcell-0.3.7}/cmake/linkcellConfig.cmake.in +0 -0
  52. {linkcell-0.3.5 → linkcell-0.3.7}/docs/how-to/embed-cpp.md +0 -0
  53. {linkcell-0.3.5 → linkcell-0.3.7}/docs/how-to/embed-python.md +0 -0
  54. {linkcell-0.3.5 → linkcell-0.3.7}/docs/how-to/pkg-config.md +0 -0
  55. {linkcell-0.3.5 → linkcell-0.3.7}/docs/index.md +0 -0
  56. {linkcell-0.3.5 → linkcell-0.3.7}/docs/reference/c-api.md +0 -0
  57. {linkcell-0.3.5 → linkcell-0.3.7}/docs/tutorials/two-points.md +0 -0
  58. {linkcell-0.3.5 → linkcell-0.3.7}/examples/knn_hot.rs +0 -0
  59. {linkcell-0.3.5 → linkcell-0.3.7}/examples/meson.build +0 -0
  60. {linkcell-0.3.5 → linkcell-0.3.7}/examples/two_points.c +0 -0
  61. {linkcell-0.3.5 → linkcell-0.3.7}/examples/two_points.cpp +0 -0
  62. {linkcell-0.3.5 → linkcell-0.3.7}/include/linkcell.h +0 -0
  63. {linkcell-0.3.5 → linkcell-0.3.7}/include/linkcell.hpp +0 -0
  64. {linkcell-0.3.5 → linkcell-0.3.7}/include/linkcell_gpu.h +0 -0
  65. {linkcell-0.3.5 → linkcell-0.3.7}/include/linkcell_gpu.hpp +0 -0
  66. {linkcell-0.3.5 → linkcell-0.3.7}/linkcell/__init__.py +0 -0
  67. {linkcell-0.3.5 → linkcell-0.3.7}/meson_options.txt +0 -0
  68. {linkcell-0.3.5 → linkcell-0.3.7}/python/build.rs +0 -0
  69. {linkcell-0.3.5 → linkcell-0.3.7}/python/src/gpu.rs +0 -0
  70. {linkcell-0.3.5 → linkcell-0.3.7}/python/src/lib.rs +0 -0
  71. {linkcell-0.3.5 → linkcell-0.3.7}/scripts/check-install.sh +0 -0
  72. {linkcell-0.3.5 → linkcell-0.3.7}/scripts/copy-cargo-artifacts.py +0 -0
  73. {linkcell-0.3.5 → linkcell-0.3.7}/scripts/regen-capi-headers.sh +0 -0
  74. {linkcell-0.3.5 → linkcell-0.3.7}/src/capi.rs +0 -0
  75. {linkcell-0.3.5 → linkcell-0.3.7}/src/error.rs +0 -0
  76. {linkcell-0.3.5 → linkcell-0.3.7}/src/gpu/capi.cpp +0 -0
  77. {linkcell-0.3.5 → linkcell-0.3.7}/src/gpu/gpulite_compat.hpp +0 -0
  78. {linkcell-0.3.5 → linkcell-0.3.7}/src/gpu/knearest.cpp +0 -0
  79. {linkcell-0.3.5 → linkcell-0.3.7}/subprojects/gpulite.wrap +0 -0
  80. {linkcell-0.3.5 → linkcell-0.3.7}/subprojects/packagefiles/gpulite/meson.build +0 -0
  81. {linkcell-0.3.5 → linkcell-0.3.7}/tests/abi.rs +0 -0
  82. {linkcell-0.3.5 → linkcell-0.3.7}/tests/agree.rs +0 -0
  83. {linkcell-0.3.5 → linkcell-0.3.7}/tests/cmake-consumer/CMakeLists.txt +0 -0
  84. {linkcell-0.3.5 → linkcell-0.3.7}/tests/cmake-consumer/gpu.cpp +0 -0
  85. {linkcell-0.3.5 → linkcell-0.3.7}/tests/gpu_agree.cpp +0 -0
  86. {linkcell-0.3.5 → linkcell-0.3.7}/tests/python/test_agree_vesin.py +0 -0
  87. {linkcell-0.3.5 → linkcell-0.3.7}/tests/python/test_knearest_cuda.py +0 -0
  88. {linkcell-0.3.5 → linkcell-0.3.7}/tests/python/test_pairs.py +0 -0
  89. {linkcell-0.3.5 → linkcell-0.3.7}/third_party/gpulite/LICENSE +0 -0
  90. {linkcell-0.3.5 → linkcell-0.3.7}/third_party/gpulite/README.md +0 -0
  91. {linkcell-0.3.5 → linkcell-0.3.7}/third_party/gpulite/gpulite/gpulite.hpp +0 -0
  92. {linkcell-0.3.5 → linkcell-0.3.7}/towncrier.toml +0 -0
@@ -10,6 +10,27 @@ by [towncrier](https://towncrier.readthedocs.io/).
10
10
 
11
11
  <!-- towncrier release notes start -->
12
12
 
13
+ ## [0.3.7] - 2026-10-04
14
+
15
+ ### Fixed
16
+
17
+ - The cutoff list sizes its row buffer from the pairs it found. A shell denser than the ideal-gas estimate no longer writes past that buffer.
18
+
19
+ ## [0.3.6] - 2026-10-04
20
+
21
+ ### Changed
22
+
23
+ - 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.
24
+ - 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.
25
+ - The crate depends on minimage 0.1.3.
26
+ - 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.
27
+ - `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.
28
+
29
+ ### Fixed
30
+
31
+ - The Meson project version matches the crate version.
32
+
33
+
13
34
  ## [0.3.5] - 2026-10-04
14
35
 
15
36
  ### Changed
@@ -79,7 +79,7 @@ checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
79
79
 
80
80
  [[package]]
81
81
  name = "linkcell"
82
- version = "0.3.5"
82
+ version = "0.3.7"
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.5"
90
+ version = "0.3.7"
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,6 +1,6 @@
1
1
  [package]
2
2
  name = "linkcell"
3
- version = "0.3.5"
3
+ version = "0.3.7"
4
4
  edition = "2021"
5
5
  rust-version = "1.70"
6
6
  description = "Periodic linked-cell cutoff pairs and k-nearest neighbour search"
@@ -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.5
3
+ Version: 0.3.7
4
4
  Classifier: Programming Language :: Rust
5
5
  Classifier: Programming Language :: Python :: 3
6
6
  Classifier: Programming Language :: Python :: 3.12
@@ -34,8 +34,10 @@ shift `S`, and a squared distance strictly below the cutoff squared.
34
34
  without a minimum-image convention. The walk is the linked-cell method
35
35
  of Allen and Tildesley (*Computer Simulation of Liquids*). k-nearest
36
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
+ 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.
39
41
 
40
42
  It is a LODE library. The Rust crate is the implementation. The C ABI
41
43
  (`lc_*`) is the hourglass waist, the same shape as
@@ -94,7 +96,7 @@ As a wrap, Meson exposes `linkcell_dep`:
94
96
  ```
95
97
  [wrap-git]
96
98
  url = https://github.com/d-SEAMS/linkcell.git
97
- revision = v0.3.5
99
+ revision = v0.3.7
98
100
  depth = 1
99
101
 
100
102
  [provide]
@@ -221,7 +223,11 @@ Rust API: [docs.rs/linkcell](https://docs.rs/linkcell). Map: [docs/index.md](doc
221
223
  distances are a Cartesian subtract plus that cell's lattice
222
224
  translation (`dist2_shifted` and `lattice_shift`), the vesin /
223
225
  LAMMPS ghost construction. Orthorhombic boxes use three independent
224
- wraps and skip the two Hinv matvecs. A restricted triclinic box is
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
225
231
  tilt-reduced and uses a triangular shift.
226
232
  - One lattice shift per unique cell is wrong unless every wrap of that
227
233
  cell is visited. The walk visits integer cell offsets, so each wrap
@@ -12,8 +12,10 @@ shift `S`, and a squared distance strictly below the cutoff squared.
12
12
  without a minimum-image convention. The walk is the linked-cell method
13
13
  of Allen and Tildesley (*Computer Simulation of Liquids*). k-nearest
14
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
+ 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.
17
19
 
18
20
  It is a LODE library. The Rust crate is the implementation. The C ABI
19
21
  (`lc_*`) is the hourglass waist, the same shape as
@@ -72,7 +74,7 @@ As a wrap, Meson exposes `linkcell_dep`:
72
74
  ```
73
75
  [wrap-git]
74
76
  url = https://github.com/d-SEAMS/linkcell.git
75
- revision = v0.3.5
77
+ revision = v0.3.7
76
78
  depth = 1
77
79
 
78
80
  [provide]
@@ -199,7 +201,11 @@ Rust API: [docs.rs/linkcell](https://docs.rs/linkcell). Map: [docs/index.md](doc
199
201
  distances are a Cartesian subtract plus that cell's lattice
200
202
  translation (`dist2_shifted` and `lattice_shift`), the vesin /
201
203
  LAMMPS ghost construction. Orthorhombic boxes use three independent
202
- wraps and skip the two Hinv matvecs. A restricted triclinic box is
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
203
209
  tilt-reduced and uses a triangular shift.
204
210
  - One lattice shift per unique cell is wrong unless every wrap of that
205
211
  cell is visited. The walk visits integer cell offsets, so each wrap
@@ -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
+ }
@@ -22,6 +22,20 @@ Orthorhombic boxes skip the two 3x3 matvecs everywhere they can:
22
22
  `fractional` divides by the three widths, `lattice_shift` multiplies
23
23
  those widths, and brute `dist2` is three independent wraps.
24
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
+
25
39
  ## One shift per cell is wrong
26
40
 
27
41
  The bins live in the primary cell. Cell `(ix + nx, iy, iz)` is the
@@ -53,10 +67,11 @@ frontier plane, or until the shell covers a space diagonal.
53
67
  vesin answers "who is inside radius r". This crate answers "who are
54
68
  the k nearest, with the periodic image". The search takes no
55
69
  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.
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.
60
75
 
61
76
  nanoflann answers the same k question in Euclidean space without a
62
77
  minimum-image convention. A periodic dump still needs the fold and
@@ -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.5
23
+ revision = v0.3.7
24
24
  depth = 1
25
25
 
26
26
  [provide]
@@ -70,12 +70,35 @@ basis can still miss a closer shift; the shell cap is the space
70
70
  diagonal divided by the minimum cell height, and the frontier test
71
71
  stops the walk once the k-th neighbour is certified.
72
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`,
73
+ `S` is an integer combination of that H. Each unordered pair is
74
+ tested once. Hits from that walk are buffered, then the rows are
75
+ written in one pass. A full list writes both `(i, j, S)` and
76
+ `(j, i, -S)`. With more than one thread and at least 512 atoms, each
77
+ thread searches a slice of cells and writes a disjoint range of the
78
+ same pair buffer. On Linux that buffer stays on the heap, so a
79
+ repeated call does not fault those pages in again.
80
+ The C, C++, and Python entries are that list (`lc_pairs_within`,
76
81
  `linkcell::pairs_within`, `linkcell.pairs_within`). A cutoff
77
82
  neighbour list is this call.
78
83
 
84
+ With the bin edge equal to the cutoff the search radius is 1, and the
85
+ gap between any two cells inside that stencil is 0, so the bin test
86
+ does not drop a cell. vesin's cell list then evaluates
87
+ `27 ρ − 1` ordered distances per atom (`ρ` atoms in the cell). This
88
+ walk evaluates `(ρ − 1) / 2 + 13 ρ`, which is exactly half:
89
+ `scripts/cutoff_work.py` simplifies the ratio to 2. vesin also forms
90
+ `S H` with a 3×3 product on every candidate. This walk forms that
91
+ shift once per cell pair. The extra traffic is the hit buffer and the
92
+ 40-byte row.
93
+
94
+ GROMACS nbnxn stores a cluster-pair list and an interaction bitmask,
95
+ and the force kernel reads that list. This call returns one atom-image
96
+ row. Morton-ordering each bin and skipping a 4×8 tile whose certified
97
+ box misses the cutoff was timed on this host for the 4096-atom cube at
98
+ a 4 Å cutoff: about 2.8 ms on one thread and 0.98 ms on eight, against
99
+ 2.68 ms and 0.87 ms for the distance tile alone. The walk keeps the
100
+ distance tile. A cluster bitmask would still expand into the same row.
101
+
79
102
  ## Heap and stop
80
103
 
81
104
  A max-heap of size `k` stores `(dist2, index)`, ordered
@@ -100,8 +123,10 @@ first. `knearest_into` / `lc_knearest` write packed indices.
100
123
  `knearest_into_many` / `lc_knearest_many` cover a frame-major batch.
101
124
 
102
125
  `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
126
+ systems. An orthorhombic box calls `dist2_ortho_diffs` (the Highway
127
+ batch: SoA differences, one reciprocal per axis, then the per-axis
128
+ round). Any other box calls `Cell::dist2_euclidean` per pair: Smith
129
+ half-edge test, then a Minkowski-reduced 27-image. The 27-image of an
105
130
  unreduced H misses lattice points such as `2(a-b)`. The fractional
106
131
  wrap of a hex-prism body diagonal is not nearest. It is not the
107
132
  production walk.
@@ -118,18 +143,60 @@ builders take a cutoff, or k neighbours inside a ball.
118
143
 
119
144
  ## Parallel
120
145
 
146
+ linkcell is a sub-library. An MPI caller keeps the primary
147
+ communicator and passes a sub-communicator. MPI setup stays in that
148
+ caller. The POP3 figures below are the threads inside one search:
149
+ the share that sub-communicator already assigned to this call.
150
+
121
151
  The `parallel` Cargo feature (on by default) maps sources with
122
- rayon. Each source owns its heap.
152
+ rayon. Each source owns its heap. From 8192 active points upward the
153
+ same feature builds the mesh in parallel: a thread writes each point's
154
+ fractional coordinate once, histograms with atomics, then scatters
155
+ occupants with atomics. Bins are sorted by index afterwards, so the
156
+ occupant order matches the serial build. Below that count the mesh
157
+ stays serial. The cubic hot path is 4096 points and does not take the
158
+ parallel build. `--no-default-features` keeps the whole search serial.
159
+
160
+ `examples/knn_scale.rs` and `examples/pairs_scale.rs` time one fixed
161
+ problem and always record the POP3 hierarchy. `RAYON_NUM_THREADS` has
162
+ to be set before the process starts. The box in the k-nearest probe
163
+ grows with `n` so the spacing stays 3.125. Useful time is the
164
+ monotonic clock inside that worker's mesh and walk loops, not while
165
+ it waits for another worker. Load balance is the average of that time
166
+ over the maximum, communication efficiency is the maximum over the
167
+ wall time, and parallel efficiency is their product. Strong-scaling
168
+ computation scaling is the 1-thread useful total over the useful
169
+ total at the larger thread count, per repetition. Global efficiency
170
+ is parallel efficiency times that computation scaling.
171
+ `scripts/bench-strong.sh` and `scripts/bench-pairs.sh` print the
172
+ hierarchy. Instruction scaling, IPC scaling, and frequency scaling
173
+ need a PMU. This host's `perf_event_open` has no PMU, so those three
174
+ are not reported. Serialization and transfer are not split: there is
175
+ no ideal-network model, so communication efficiency stays one number.
123
176
 
124
177
  ## Device
125
178
 
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`.
179
+ `linkcell::gpu::Workspace` is the gpulite CUDA walk. It still stops on
180
+ `reach * cell_min`, which is a lower bound on the host plane, so it
181
+ does not stop earlier than the host. `k <= 16`. That path is separate
182
+ from the Kokkos walk.
183
+
184
+ `src/kokkos/` is the certified walk on `Kokkos::DefaultExecutionSpace`.
185
+ The caller starts Kokkos. The standalone timer calls
186
+ `Kokkos::initialize` because that program is the whole process. A
187
+ caller that already started Kokkos keeps doing so, and an MPI caller
188
+ still passes a sub-communicator. Fold, bin, exclusive scan, and the
189
+ per-axis index box run as Kokkos parallel loops. The stop is the host
190
+ plane test, not `reach * cell_min`.
191
+ `k <= 16`. The sources are not in the Cargo or CMake graph, so a
192
+ build without Kokkos stays the same. A Cuda execution space uses this
193
+ source; the timings in the changelog were taken with the OpenMP
194
+ backend, because the machine that measured them has no CUDA device.
195
+ The Kokkos bench always records thread CPU time for each OpenMP static
196
+ slice of the fill, the scatter, and the walk, plus the host copies
197
+ into and out of the views. One sample covers the slice. The exclusive
198
+ scan and the view allocation stay outside that clock, so they widen
199
+ the communication-efficiency gap. The hierarchy is the same one as
200
+ the host script, and the same missing PMU means no instruction, IPC,
201
+ or frequency scaling. `scripts/bench-kokkos.sh` builds that bench
202
+ against a Kokkos install and prints the hierarchy.
@@ -0,0 +1,107 @@
1
+ //! Strong-scaling probe for one fixed problem.
2
+ //!
3
+ //! The box grows with `n` so the spacing stays 3.125, the cubic hot-path
4
+ //! density. Set `RAYON_NUM_THREADS` before the process starts. Env:
5
+ //! `KNN_SCALE_N` (default 262144), `KNN_SCALE_K` (default 4),
6
+ //! `KNN_SCALE_REPS` (default 6), `KNN_SCALE_SHAPE` (`cubic` or `tilt`).
7
+
8
+ use std::time::Instant;
9
+
10
+ use linkcell::{knearest_into, Cell};
11
+
12
+ fn env_usize(key: &str, default: usize) -> usize {
13
+ std::env::var(key)
14
+ .ok()
15
+ .and_then(|s| s.parse().ok())
16
+ .unwrap_or(default)
17
+ }
18
+
19
+ fn nside_of(n: usize) -> usize {
20
+ ((n as f64).cbrt().round() as usize).max(1)
21
+ }
22
+
23
+ fn cubic(nside: usize) -> (Vec<[f64; 3]>, Cell) {
24
+ let boxl = nside as f64 * 3.125;
25
+ let cell = Cell::ortho(boxl, boxl, boxl).expect("box");
26
+ let mut xyz = Vec::with_capacity(nside * nside * nside);
27
+ let a = 3.125;
28
+ for iz in 0..nside {
29
+ for iy in 0..nside {
30
+ for ix in 0..nside {
31
+ xyz.push([ix as f64 * a, iy as f64 * a, iz as f64 * a]);
32
+ }
33
+ }
34
+ }
35
+ (xyz, cell)
36
+ }
37
+
38
+ /// Restricted triclinic box, tilt-reduced, scaled so the a edge matches
39
+ /// the cubic spacing times `nside`.
40
+ fn tilt(nside: usize) -> (Vec<[f64; 3]>, Cell) {
41
+ let lx = nside as f64 * 3.125;
42
+ let cell = Cell::from_vectors(
43
+ [lx, 0.0, 0.0],
44
+ [lx * 0.2, lx * 0.9, 0.0],
45
+ [lx * 0.05, lx * -0.08, lx * 0.95],
46
+ [0.0, 0.0, 0.0],
47
+ )
48
+ .expect("tilt");
49
+ let mut xyz = Vec::with_capacity(nside * nside * nside);
50
+ let nf = nside as f64;
51
+ for iz in 0..nside {
52
+ for iy in 0..nside {
53
+ for ix in 0..nside {
54
+ let s = [
55
+ (ix as f64 + 0.5) / nf,
56
+ (iy as f64 + 0.5) / nf,
57
+ (iz as f64 + 0.5) / nf,
58
+ ];
59
+ xyz.push(cell.cartesian(s));
60
+ }
61
+ }
62
+ }
63
+ (xyz, cell)
64
+ }
65
+
66
+ fn main() {
67
+ let nside = nside_of(env_usize("KNN_SCALE_N", 262_144));
68
+ let k = env_usize("KNN_SCALE_K", 4);
69
+ let reps = env_usize("KNN_SCALE_REPS", 6);
70
+ let shape = std::env::var("KNN_SCALE_SHAPE").unwrap_or_else(|_| "cubic".to_string());
71
+ let (xyz, cell) = match shape.as_str() {
72
+ "cubic" => cubic(nside),
73
+ "tilt" => tilt(nside),
74
+ other => panic!("unknown KNN_SCALE_SHAPE {other}"),
75
+ };
76
+ let threads = std::env::var("RAYON_NUM_THREADS").unwrap_or_else(|_| "default".to_string());
77
+ let mut out = vec![-1i32; xyz.len() * k];
78
+ linkcell::pop_engage();
79
+ linkcell::pop_prepare();
80
+ knearest_into(&xyz, &cell, k, None, Some(3.0), &mut out).expect("warmup");
81
+ linkcell::pop_reset();
82
+ let mut acc = 0i32;
83
+ let started = Instant::now();
84
+ for _ in 0..reps {
85
+ knearest_into(&xyz, &cell, k, None, Some(3.0), &mut out).expect("knearest");
86
+ acc = acc.wrapping_add(out[0]);
87
+ }
88
+ let wall_ns = started.elapsed().as_nanos() as u64;
89
+ std::hint::black_box(acc);
90
+ let useful = linkcell::pop_snapshot();
91
+ let ms = wall_ns as f64 / 1e6;
92
+ println!(
93
+ "shape={shape} threads={threads} n={} k={k} reps={reps} ms={ms:.1} ms_per={:.2}",
94
+ xyz.len(),
95
+ ms / reps as f64
96
+ );
97
+ let (lb, ce, pe) = linkcell::pop_efficiencies(&useful, wall_ns);
98
+ let list = useful
99
+ .iter()
100
+ .map(|ns| ns.to_string())
101
+ .collect::<Vec<_>>()
102
+ .join(",");
103
+ println!(
104
+ "pop shape={shape} threads={threads} n={} reps={reps} wall_ns={wall_ns} useful_ns={list} lb={lb:.4} ce={ce:.4} pe={pe:.4}",
105
+ xyz.len()
106
+ );
107
+ }
@@ -0,0 +1,95 @@
1
+ //! Cutoff-list probe for the periodic 18 Å cube at a 4 Å cutoff.
2
+ //!
3
+ //! Env: `PAIRS_N` (default 4096), `PAIRS_REPS` (default 5),
4
+ //! `PAIRS_HALF` (default 0), `PAIRS_HINT` (bin edge, or the cutoff).
5
+ //! `RAYON_NUM_THREADS` is read at startup. The line reports the first
6
+ //! three calls, then the mean of the timed reps after that. Those
7
+ //! timed reps always record the POP3 hierarchy.
8
+
9
+ use std::time::Instant;
10
+
11
+ use linkcell::{pairs_within, Cell};
12
+
13
+ fn env_usize(key: &str, default: usize) -> usize {
14
+ std::env::var(key)
15
+ .ok()
16
+ .and_then(|s| s.parse().ok())
17
+ .unwrap_or(default)
18
+ }
19
+
20
+ fn fill(n: usize) -> Vec<[f64; 3]> {
21
+ let boxl = 18.0;
22
+ let m = (n as f64).cbrt().ceil() as usize;
23
+ let mut xyz = Vec::with_capacity(n);
24
+ let mut count = 0usize;
25
+ 'outer: for iz in 0..m {
26
+ for iy in 0..m {
27
+ for ix in 0..m {
28
+ if count >= n {
29
+ break 'outer;
30
+ }
31
+ xyz.push([
32
+ (ix as f64 + 0.5) * boxl / m as f64,
33
+ (iy as f64 + 0.5) * boxl / m as f64,
34
+ (iz as f64 + 0.5) * boxl / m as f64,
35
+ ]);
36
+ count += 1;
37
+ }
38
+ }
39
+ }
40
+ xyz
41
+ }
42
+
43
+ fn main() {
44
+ let n = env_usize("PAIRS_N", 4096);
45
+ let reps = env_usize("PAIRS_REPS", 5).max(1);
46
+ let half = std::env::var("PAIRS_HALF").ok().as_deref() == Some("1");
47
+ let hint = std::env::var("PAIRS_HINT")
48
+ .ok()
49
+ .and_then(|s| s.parse().ok());
50
+ let threads = std::env::var("RAYON_NUM_THREADS").unwrap_or_else(|_| "default".to_string());
51
+ let xyz = fill(n);
52
+ let cell = Cell::ortho(18.0, 18.0, 18.0).expect("box");
53
+ linkcell::pop_engage();
54
+ linkcell::pop_prepare();
55
+ let mut pairs = Vec::new();
56
+ let mut early = Vec::new();
57
+ for _ in 0..3 {
58
+ let t = Instant::now();
59
+ pairs = pairs_within(&xyz, &cell, 4.0, None, hint, half).expect("pairs");
60
+ early.push(t.elapsed().as_secs_f64() * 1e3);
61
+ }
62
+ linkcell::pop_reset();
63
+ let t0 = Instant::now();
64
+ let mut acc = 0usize;
65
+ for _ in 0..reps {
66
+ let got = pairs_within(&xyz, &cell, 4.0, None, hint, half).expect("pairs");
67
+ acc += got.len();
68
+ }
69
+ let wall_ns = t0.elapsed().as_nanos() as u64;
70
+ let ms = wall_ns as f64 / 1e6;
71
+ println!(
72
+ "n={} half={} hint={:?} pairs={} cold={:.3} call2={:.3} call3={:.3} reps={} ms_per={:.4} acc={}",
73
+ xyz.len(),
74
+ half as u8,
75
+ hint,
76
+ pairs.len(),
77
+ early[0],
78
+ early[1],
79
+ early[2],
80
+ reps,
81
+ ms / reps as f64,
82
+ acc
83
+ );
84
+ let useful = linkcell::pop_snapshot();
85
+ let (lb, ce, pe) = linkcell::pop_efficiencies(&useful, wall_ns);
86
+ let list = useful
87
+ .iter()
88
+ .map(|ns| ns.to_string())
89
+ .collect::<Vec<_>>()
90
+ .join(",");
91
+ println!(
92
+ "pop shape=pairs-{n}-h{} threads={threads} n={n} reps={reps} wall_ns={wall_ns} useful_ns={list} lb={lb:.4} ce={ce:.4} pe={pe:.4}",
93
+ half as u8
94
+ );
95
+ }
@@ -2,7 +2,7 @@ project(
2
2
  'linkcell',
3
3
  ['c', 'cpp'],
4
4
  # Keep in lockstep with Cargo.toml [package].version (source of truth).
5
- version: '0.3.3',
5
+ version: '0.3.7',
6
6
  meson_version: '>=1.2.0',
7
7
  license: 'MIT',
8
8
  default_options: [
@@ -4,7 +4,7 @@ build-backend = "maturin"
4
4
 
5
5
  [project]
6
6
  name = "linkcell"
7
- version = "0.3.5"
7
+ version = "0.3.7"
8
8
  description = "Periodic linked-cell cutoff pairs and k-nearest neighbour search"
9
9
  readme = "README.md"
10
10
  license = { text = "MIT" }
@@ -1,6 +1,6 @@
1
1
  [package]
2
2
  name = "linkcell-python"
3
- version = "0.3.5"
3
+ version = "0.3.7"
4
4
  edition = "2021"
5
5
  rust-version = "1.88"
6
6
  license = "MIT"
@@ -0,0 +1,25 @@
1
+ #!/bin/sh
2
+ # Build and time the Kokkos certified walk with the POP3 hierarchy.
3
+ # OpenMP is the backend this script expects. A Cuda Kokkos install
4
+ # uses the same sources. The bench always records useful time.
5
+ set -eu
6
+ ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
7
+ PREFIX=${KOKKOS_ROOT:-/tmp/kokkos-install}
8
+ BUILD=${LC_KOKKOS_BUILD:-/tmp/linkcell-kokkos}
9
+ export LIBRARY_PATH="/usr/lib/gcc/x86_64-linux-gnu/13${LIBRARY_PATH:+:$LIBRARY_PATH}"
10
+ export LD_LIBRARY_PATH="/usr/lib/gcc/x86_64-linux-gnu/13${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
11
+ cmake -S "$ROOT/src/kokkos" -B "$BUILD" \
12
+ -DCMAKE_BUILD_TYPE=Release \
13
+ -DCMAKE_CXX_COMPILER=g++ \
14
+ -DKokkos_ROOT="$PREFIX"
15
+ cmake --build "$BUILD" -j "$(nproc)"
16
+ N=${LC_KOKKOS_N:-262144}
17
+ REPS=${LC_KOKKOS_REPS:-5}
18
+ LOG=$(mktemp)
19
+ for t in 1 2 4 8; do
20
+ OMP_NUM_THREADS=$t OMP_PROC_BIND=true \
21
+ LC_KOKKOS_POP=1 LC_KOKKOS_N=$N LC_KOKKOS_REPS=$REPS \
22
+ "$BUILD/lc_kokkos_bench" --kokkos-num-threads=$t | tee -a "$LOG"
23
+ done
24
+ python3 "$ROOT/scripts/pop-report.py" < "$LOG"
25
+ rm -f "$LOG"
@@ -0,0 +1,17 @@
1
+ #!/bin/sh
2
+ # Cutoff-list sweep with the POP3 hierarchy.
3
+ # Build first: cargo build --release --example pairs_scale
4
+ # The probe always records useful time per worker. Computation scaling
5
+ # is against the 1-thread row of the same atom count.
6
+ set -eu
7
+ ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
8
+ BIN=${PAIRS_SCALE_BIN:-$ROOT/target/release/examples/pairs_scale}
9
+ REPS=${PAIRS_REPS:-8}
10
+ LOG=$(mktemp)
11
+ for n in 256 1024 4096; do
12
+ for t in 1 2 4 8; do
13
+ RAYON_NUM_THREADS=$t PAIRS_N=$n PAIRS_REPS=$REPS "$BIN" | tee -a "$LOG"
14
+ done
15
+ done
16
+ python3 "$ROOT/scripts/pop-report.py" < "$LOG"
17
+ rm -f "$LOG"
@@ -0,0 +1,19 @@
1
+ #!/bin/sh
2
+ # Strong-scaling sweep with the POP3 hierarchy.
3
+ # Build first: cargo build --release --example knn_scale
4
+ # The probe always records useful time per worker. The hierarchy is
5
+ # load balance, communication efficiency, parallel efficiency,
6
+ # computation scaling against 1 thread, and global efficiency.
7
+ set -eu
8
+ ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
9
+ BIN=${KNN_SCALE_BIN:-$ROOT/target/release/examples/knn_scale}
10
+ N=${KNN_SCALE_N:-262144}
11
+ REPS=${KNN_SCALE_REPS:-6}
12
+ SHAPE=${KNN_SCALE_SHAPE:-cubic}
13
+ LOG=$(mktemp)
14
+ for t in 1 2 4 8; do
15
+ RAYON_NUM_THREADS=$t LINKCELL_POP=1 KNN_SCALE_N=$N KNN_SCALE_REPS=$REPS \
16
+ KNN_SCALE_SHAPE=$SHAPE "$BIN" | tee -a "$LOG"
17
+ done
18
+ python3 "$ROOT/scripts/pop-report.py" < "$LOG"
19
+ rm -f "$LOG"