sycl-nl 0.3.0__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.
sycl_nl-0.3.0/LICENSE ADDED
@@ -0,0 +1,28 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2024, Guillaume Fraux
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ 3. Neither the name of the copyright holder nor the names of its
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,3 @@
1
+ include scripts/build_native.sh scripts/build_aces.sh
2
+ include sycl_nl/launcher.cpp sycl_nl/kernels.sycl
3
+ recursive-include tests/data *.extxyz
sycl_nl-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,335 @@
1
+ Metadata-Version: 2.4
2
+ Name: sycl-nl
3
+ Version: 0.3.0
4
+ Summary: A minimal periodic SYCL neighbor list for PyTorch XPU
5
+ License-Expression: BSD-3-Clause
6
+ Project-URL: Repository, https://gitlab.com/tgmaxson/sycl_nl
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Requires-Dist: ase
11
+ Requires-Dist: numpy
12
+ Requires-Dist: torch
13
+ Provides-Extra: nequip
14
+ Requires-Dist: nequip>=0.19.1; extra == "nequip"
15
+ Provides-Extra: test
16
+ Requires-Dist: pytest; extra == "test"
17
+ Requires-Dist: vesin>=0.6.2; extra == "test"
18
+ Provides-Extra: benchmark
19
+ Requires-Dist: matplotlib; extra == "benchmark"
20
+ Requires-Dist: vesin>=0.6.2; extra == "benchmark"
21
+ Dynamic: license-file
22
+
23
+ # SYCL neighbor lists for PyTorch
24
+
25
+ `sycl_nl` builds full directed atomistic neighbor lists on the current PyTorch
26
+ Intel XPU SYCL queue or an Intel OpenCL CPU queue. It handles isolated systems, periodic bulk, and skew cells
27
+ with mixed periodicity. It supports multiple images of the same pair and an
28
+ optional Verlet cache that filters candidates at the exact cutoff.
29
+
30
+ ## Install and use
31
+
32
+ Install the Linux x86-64 wheel into an existing PyTorch XPU environment with
33
+ a compatible Intel device driver. The wheel contains a native launcher and
34
+ SPIR-V device kernels. It uses the SYCL runtime already supplied by the
35
+ PyTorch XPU environment.
36
+
37
+ ```bash
38
+ python -m pip install /path/to/sycl_nl-0.3.0-py3-none-linux_x86_64.whl
39
+ ```
40
+
41
+ The runtime Python dependencies are ASE, NumPy, and PyTorch. Vesin is
42
+ needed for the `test` and `benchmark` extras. The ACES wheel was built against
43
+ Intel SYCL 2026.0 and tested with PyTorch 2.13.0+XPU. CPU-only use needs an
44
+ Intel SYCL/OpenCL runtime in the environment as well.
45
+
46
+ ### Build a wheel from source
47
+
48
+ A source build needs the Intel DPC++ compiler, its matching `llvm-spirv`,
49
+ a C++20 host compiler, and SYCL development headers compatible with the target
50
+ PyTorch runtime. Intel's `intel-sycl-rt` and `dpcpp-cpp-rt` pip packages
51
+ provide runtime libraries. [Intel compiler installation options](https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-compiler-download.html)
52
+
53
+ ```bash
54
+ # ACES modules and an activated PyTorch XPU environment
55
+ scripts/build_aces.sh "$CONDA_PREFIX" build/native
56
+ SYCL_NL_NATIVE_DIR="$PWD/build/native" python -m pip wheel --no-deps . -w dist
57
+ ```
58
+
59
+ On other Linux systems, set `SYCL_NL_SYCL_ROOT` to the matching SDK prefix
60
+ containing `include/` and `lib/`, and put the tools on `PATH`. A source
61
+ `pip wheel` or `pip install .` compiles the native files when
62
+ `SYCL_NL_NATIVE_DIR` is unset. Set `SYCL_CXX`, `LLVM_SPIRV`, or `CXX` to
63
+ override tool paths. Install an existing wheel to skip source compilation.
64
+
65
+ ### PyTorch and ASE entry points
66
+
67
+ Inside an Intel GPU allocation, pass an XPU tensor of Cartesian coordinates,
68
+ the cell as three row vectors, and three periodicity flags.
69
+
70
+ ```python
71
+ import torch
72
+ from ase.build import bulk
73
+ from sycl_nl import SyclNeighborList
74
+
75
+ atoms = bulk("Si", "diamond", a=5.43)
76
+ positions = torch.as_tensor(atoms.positions, device="xpu")
77
+ with SyclNeighborList(skin=0.5, algorithm="cell_list") as neighbors:
78
+ edges = neighbors.compute(positions, atoms.cell.array, atoms.pbc, cutoff=6.5)
79
+ ```
80
+
81
+ The default algorithm is `all_pairs`. The optional `cell_list` algorithm
82
+ uses fractional-coordinate bins and works with the compiled SPIR-V kernels.
83
+ For compact, fully periodic XPU systems, it builds a dense grid on the device,
84
+ reuses metadata and scratch buffers, and emits edges in one candidate pass.
85
+ The sparse grid handles CPU, mixed periodicity, and XPU systems outside the
86
+ dense path's grid limits. Select `sparse_cell_list` to benchmark that path
87
+ directly. The order of returned edges can vary between builds. Select `half_cell_list`
88
+ to evaluate each candidate pair and periodic image once on the dense XPU
89
+ path and emit both directed edges. Self-images use a canonical shift and
90
+ its negative. The sparse path handles unsupported dense grids and CPU.
91
+
92
+ Use a CPU positions tensor to select the CPU queue. The output is an `int64` tensor on the input device with one row
93
+ `[center, neighbor, shift_a, shift_b, shift_c]` per directed edge. The
94
+ displacement is `positions[neighbor] - positions[center] + shift @ cell`.
95
+ The zero-shift self edge is excluded. Periodic self images within the cutoff
96
+ are included. For force gradients, reconstruct displacements from the original
97
+ differentiable coordinates using the returned topology.
98
+
99
+ An ASE-style function takes an `Atoms` object and returns NumPy arrays.
100
+ It supports scalar cutoffs, per-atom radii, element-pair cutoffs, and
101
+ `self_interaction`. Pass a reusable calculator to retain its Verlet cache.
102
+
103
+ ```python
104
+ from sycl_nl.ase import neighbor_list
105
+
106
+ i, j, shifts = neighbor_list("ijS", atoms, 6.5, device="xpu")
107
+ ```
108
+
109
+ ## NequIP training and inference
110
+
111
+ Install the optional `nequip` extra or use a preconfigured NequIP
112
+ environment. In training, replace the stock neighbor-list transform after
113
+ the type mapper. Use the model's cutoff. The transform runs on each frame
114
+ before the data loader batches graphs.
115
+
116
+ ```yaml
117
+ - _target_: sycl_nl.nequip.NequIPNeighborList
118
+ r_max: 6.5
119
+ skin: 0.0
120
+ ```
121
+
122
+ With no explicit `device`, the search follows the position tensor. CPU
123
+ dataset workers can build graphs on CPU for subsequent XPU training. Set
124
+ `device: xpu` to build on the GPU in the main process with
125
+ `num_workers: 0`. The output tensors follow the input positions. Graph
126
+ construction preserves the position tensor used by the model to compute
127
+ forces.
128
+
129
+ For eager ASE inference, load a NequIP calculator with its usual options,
130
+ then install the transform before the first evaluation.
131
+
132
+ ```python
133
+ from sycl_nl.nequip import use_sycl_neighborlist
134
+
135
+ neighbors = use_sycl_neighborlist(calculator, skin=0.5)
136
+ atoms.calc = calculator
137
+ ```
138
+
139
+ A positive skin retains candidates at the model cutoff plus the skin and
140
+ filters them back to the exact cutoff on each call. Atom-count changes,
141
+ cell or PBC changes, species order changes, and an indexed displacement of
142
+ at least half the skin trigger a rebuild. Pass `atom_id_key` to the transform
143
+ if the data has stable per-atom IDs and same-species permutations must
144
+ explicitly rebuild. Use `reset_cache()` when switching trajectories.
145
+ Cached candidates belong to the transform's current process and device.
146
+ Use zero skin for shuffled training data. The ASE helper supports eager
147
+ calculators whose graph uses standard directed edges. The ACES Intel XPU
148
+ test matched NequIP-OAM-M reference energies and forces and completed an
149
+ energy-and-force Adam step with a Hydra-instantiated transform.
150
+
151
+ ## First PyPI release
152
+
153
+ The distribution name is `sycl-nl` and the import is `sycl_nl`. Set up a
154
+ pending GitLab Trusted Publisher in the PyPI account's Publishing settings.
155
+
156
+ | PyPI field | Value |
157
+ | --- | --- |
158
+ | Project name | `sycl-nl` |
159
+ | GitLab namespace | `tgmaxson` |
160
+ | GitLab project | `sycl_nl` |
161
+ | Top-level pipeline | `.gitlab-ci.yml` |
162
+ | Environment | `pypi` |
163
+
164
+ In GitLab, protect the `v*` tag pattern and permit trusted maintainers to
165
+ create those tags. Push a tag matching the version in `pyproject.toml`,
166
+ such as `v0.3.0`. The `publish-pypi` job runs automatically after the
167
+ build and package checks pass. It uses GitLab's short-lived OIDC token.
168
+
169
+ The first pipeline builds and uploads a source distribution. PyPI source
170
+ installs require the matching SYCL SDK and compilers described above.
171
+ The ACES-specific binary wheel remains available for direct installation.
172
+ Compiler-free installation from PyPI requires a separately validated
173
+ portable Linux wheel that reuses PyTorch's SYCL runtime.
174
+ [PyPI Trusted Publishing setup](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
175
+
176
+ ## Tests and scaling benchmark
177
+
178
+ ```bash
179
+ SYCL_NL_BUILD_DIR="$PWD/build/native" python -m pytest -q
180
+ python benchmarks/bulk_si.py --build-dir build/native --output-dir results
181
+ ```
182
+
183
+ The tests run both algorithms and compare complete edge and shift tuples against CPU Vesin for isolated,
184
+ periodic bulk, and rattled skew Pt(111) cells. A five-frame trajectory checks
185
+ cache reuse, cutoff crossings, and a rebuild. A separate test checks that cell
186
+ changes invalidate a periodic cache.
187
+
188
+ Pass `--profile` to the XPU benchmark to capture diagnostics for the sparse and
189
+ dense cell-list paths. Stage timings include host submission and waits. The
190
+ benchmark takes the end-to-end samples separately with instrumentation disabled.
191
+
192
+ Select `packed_cell_list` to pack each bin's coordinates contiguously on XPU.
193
+ The search also assigns adjacent work items to centers from the same bin. On
194
+ an Intel Max 1100, the packed and linked paths were within about 5% of each other
195
+ across nine sizes in 20 interleaved warmed calls per size. At 5,000 atoms,
196
+ both took about 0.422 ms. Packing reduced the instrumented search stage from
197
+ 0.351 ms to 0.328 ms and added a 0.027 ms packing stage. The standard
198
+ `cell_list` option uses linked bins. Run the XPU benchmark with `--profile --cutoff 4.0`
199
+ to repeat the comparison. [Raw paired samples](docs/packed-bins.json)
200
+
201
+ The opt-in `stencil_cell_list` path caches each bin's neighbor indices and
202
+ periodic shifts for a fixed cell and cutoff. It uses linked bins without
203
+ coordinate packing. Across the nine sizes, it was 4–8% slower than computing
204
+ the stencil in the search kernel. At 5,000 atoms, the warmed medians were
205
+ 0.425 ms for linked bins and 0.447 ms with the cached stencil. Repeat the
206
+ comparison with `--compare-stencil --cutoff 4.0`. [Raw stencil timings](docs/fixed-cell-stencil.json)
207
+
208
+ The benchmark uses 14 fully periodic diamond Si supercells from **50 to
209
+ 100,000 atoms**, a 6.5 Å cutoff, and a small seeded rattle. It checks exact topology before
210
+ timing. All methods use zero skin. The quadratic all-pairs curves stop at
211
+ 5,000 atoms. The two Intel GPU cell-bin paths use 20 interleaved warmed
212
+ calls per size. Other methods use five warmed calls. The plot shows median wall time
213
+ and the range of warmed calls. JSON records the raw samples, atom and edge
214
+ counts, hardware metadata, and run parameters. CPU Vesin receives host arrays.
215
+ The SYCL calls include per-call metadata work and result sizing. On XPU,
216
+ positions already reside on the device. Initial position upload, compilation, and validation are outside
217
+ the timing window.
218
+
219
+ ![Log-log scaling plot for CPU and H100 Vesin and Intel CPU and GPU SYCL through 100,000 silicon atoms](docs/bulk-si.png)
220
+
221
+ At 100,000 atoms, the 6.5 Å cutoff produced 4,600,002 directed edges. The
222
+ CUDA Vesin and the Intel GPU and CPU SYCL paths matched CPU Vesin's edge and image-shift tuples
223
+ at all 14 sizes.
224
+
225
+ | Backend | GPU or CPU | Median at 100,000 atoms |
226
+ | --- | --- | ---: |
227
+ | SYCL, one test per pair | Intel Data Center GPU Max 1100 | 2.072 ms |
228
+ | SYCL linked bins | Intel Data Center GPU Max 1100 | 2.100 ms |
229
+ | CUDA Vesin | NVIDIA H100 PCIe | 2.311 ms |
230
+ | Vesin | Intel Xeon Platinum 8468 | 147.611 ms |
231
+ | SYCL cell bins | Intel Xeon Platinum 8468 | 497.987 ms |
232
+
233
+ The one-test path reduced the build time by about 1% at 100,000 atoms and
234
+ 13% at 48,000 atoms, with mixed results across sizes. It remains opt-in.
235
+ [CPU Vesin and Intel XPU samples](docs/bulk-si.json) · [SYCL CPU samples](docs/bulk-si-sycl-cpu.json) · [H100 samples](docs/bulk-si-h100.json)
236
+
237
+ The archived [4 Å comparison](https://gitlab.com/tgmaxson/sycl_nl/-/blob/0481068/README.md)
238
+ also includes the H100.
239
+
240
+ This repository keeps one published comparison in `docs/`. The plot and its raw
241
+ JSON files are retained together. The `results/` directory and native build products
242
+ are ignored so repeat runs stay local.
243
+
244
+ On ACES, run both from a scratch directory with
245
+ `sbatch /path/to/sycl_nl/scripts/test_benchmark.slurm /path/to/sycl_nl "$CONDA_PREFIX"`.
246
+ Install the test and benchmark dependencies in that environment first.
247
+
248
+ For CPU validation on ACES, run the same suite on a CPU node.
249
+ The job selects Intel OpenCL through the environment's `libintelocl.so`.
250
+ Both algorithms passed on an Intel Xeon Platinum 8468.
251
+
252
+ ```bash
253
+ SYCL_NL_TEST_DEVICE=cpu sbatch --partition=cpu --gres=none \
254
+ /path/to/sycl_nl/scripts/test_benchmark.slurm /path/to/sycl_nl "$CONDA_PREFIX"
255
+ ```
256
+
257
+ To time CPU SYCL, run on a CPU node with the same OpenCL runtime as above.
258
+
259
+ ```bash
260
+ OCL_ICD_FILENAMES="$CONDA_PREFIX/lib/libintelocl.so" ONEAPI_DEVICE_SELECTOR=opencl:cpu \
261
+ python benchmarks/bulk_si.py --device cpu --build-dir build/native --output-dir results
262
+ ```
263
+
264
+ In a CUDA environment with `vesin-torch`, run the companion benchmark on
265
+ an NVIDIA GPU. It checks the same 14 structures at the default 6.5 Å cutoff, uses zero skin, and times
266
+ synchronized builds with coordinates, cell, and periodicity already on device.
267
+
268
+ ```bash
269
+ python benchmarks/bulk_si_cuda.py --output results/bulk-si-h100.json
270
+ ```
271
+
272
+ Regenerate the published overlay from the saved measurements.
273
+
274
+ ```bash
275
+ python benchmarks/bulk_si.py --plot-only --output-dir docs \
276
+ --h100-json docs/bulk-si-h100.json --sycl-cpu-json docs/bulk-si-sycl-cpu.json
277
+ ```
278
+
279
+ ## Precision at 6.5 Å
280
+
281
+ The dense Intel GPU linked-bin path uses FP64 by default. The precision
282
+ experiments kept coordinate storage and bin assignment in FP64. FP32 and
283
+ FP16 cast the distance operands in the search. Mixed screens in FP32 and
284
+ rechecks near the cutoff in FP64. BF16 rounds the scalar FP32 operations
285
+ back to BF16, so its timing measures emulation. Vesin-torch 0.6.2 converts
286
+ all input dtypes to FP64 before calling CUDA Vesin.
287
+
288
+ | Device and mode | 5,000 atoms | 100,000 atoms | Extra / missing edges at 100,000 |
289
+ | --- | ---: | ---: | ---: |
290
+ | Intel Max 1100, FP64 | 1.256 ms | 2.019 ms | 0 / 0 |
291
+ | Intel Max 1100, FP32 distance | 1.338 ms | 1.989 ms | 0 / 0 |
292
+ | Intel Max 1100, FP32 screen with FP64 recheck | 3.174 ms | 3.522 ms | 0 / 0 |
293
+ | Intel Max 1100, FP16 distance | 1.528 ms | 2.247 ms | 842 / 2 |
294
+ | Intel Max 1100, BF16 distance | 4.147 ms | 3.962 ms | 585,550 / 37,342 |
295
+ | H100 Vesin, FP64 input | 0.279 ms | 2.260 ms | 0 / 0 |
296
+ | H100 Vesin, FP32 input | 0.287 ms | 2.261 ms | 0 / 0 |
297
+ | H100 Vesin, FP16 input | 0.280 ms | 2.278 ms | 742 / 2 |
298
+ | H100 Vesin, BF16 input | 0.284 ms | 2.425 ms | 591,778 / 35,720 |
299
+
300
+ Each bulk timing is the median of 20 interleaved calls. We compared full
301
+ directed edge and image-shift sets against CPU Vesin. We also tested six
302
+ near-cutoff cases in a skewed cell, including periodic translations.
303
+ FP32 changed the near-cutoff topology and gave no consistent speedup
304
+ across runs. FP16 and BF16 gave no speed benefit here and changed even the
305
+ 100,000-atom bulk topology. FP64 remains the default.
306
+
307
+ Use `python benchmarks/precision.py --device xpu --build-dir build/native --output results/precision-xpu.json`
308
+ or `python benchmarks/precision.py --device cuda --output results/precision-h100.json` in
309
+ the corresponding environment.
310
+ [Intel data](docs/precision-xpu.json) · [H100 data](docs/precision-h100.json)
311
+
312
+ ## Design and attribution
313
+
314
+ The prototype follows [Vesin](https://github.com/Luthaf/vesin)'s cutoff, directed
315
+ edge, and periodic image-shift conventions and uses Vesin as its correctness
316
+ reference. The all-pairs path checks all atom pairs for each candidate periodic
317
+ image. The optional cell-list path uses a Vesin-style neighboring-bin search
318
+ with sorted sparse bin keys or dense per-bin atom lists. The sparse path counts
319
+ then fills edges. The dense XPU path reserves output slots on device and reads
320
+ back the final count. It repeats with a larger output buffer if the initial
321
+ capacity is too small. Both use exact Cartesian distances after selecting
322
+ candidates.
323
+ A positive skin adds a cached candidate list and rebuilds when any atom moves
324
+ at least half the skin or the cell, cutoff, or periodicity changes.
325
+
326
+ The launcher uses Intel's SYCL runtime and integrates with the PyTorch queue on XPU.
327
+ AMD would need a separate compatible build and device integration.
328
+
329
+ ## License
330
+
331
+ [BSD 3-Clause](LICENSE), with the supplied Guillaume Fraux copyright notice.
332
+
333
+ ## AI disclosure
334
+
335
+ The code was developed primarily using Codex (6.2 Sol), with human validation.
@@ -0,0 +1,313 @@
1
+ # SYCL neighbor lists for PyTorch
2
+
3
+ `sycl_nl` builds full directed atomistic neighbor lists on the current PyTorch
4
+ Intel XPU SYCL queue or an Intel OpenCL CPU queue. It handles isolated systems, periodic bulk, and skew cells
5
+ with mixed periodicity. It supports multiple images of the same pair and an
6
+ optional Verlet cache that filters candidates at the exact cutoff.
7
+
8
+ ## Install and use
9
+
10
+ Install the Linux x86-64 wheel into an existing PyTorch XPU environment with
11
+ a compatible Intel device driver. The wheel contains a native launcher and
12
+ SPIR-V device kernels. It uses the SYCL runtime already supplied by the
13
+ PyTorch XPU environment.
14
+
15
+ ```bash
16
+ python -m pip install /path/to/sycl_nl-0.3.0-py3-none-linux_x86_64.whl
17
+ ```
18
+
19
+ The runtime Python dependencies are ASE, NumPy, and PyTorch. Vesin is
20
+ needed for the `test` and `benchmark` extras. The ACES wheel was built against
21
+ Intel SYCL 2026.0 and tested with PyTorch 2.13.0+XPU. CPU-only use needs an
22
+ Intel SYCL/OpenCL runtime in the environment as well.
23
+
24
+ ### Build a wheel from source
25
+
26
+ A source build needs the Intel DPC++ compiler, its matching `llvm-spirv`,
27
+ a C++20 host compiler, and SYCL development headers compatible with the target
28
+ PyTorch runtime. Intel's `intel-sycl-rt` and `dpcpp-cpp-rt` pip packages
29
+ provide runtime libraries. [Intel compiler installation options](https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-compiler-download.html)
30
+
31
+ ```bash
32
+ # ACES modules and an activated PyTorch XPU environment
33
+ scripts/build_aces.sh "$CONDA_PREFIX" build/native
34
+ SYCL_NL_NATIVE_DIR="$PWD/build/native" python -m pip wheel --no-deps . -w dist
35
+ ```
36
+
37
+ On other Linux systems, set `SYCL_NL_SYCL_ROOT` to the matching SDK prefix
38
+ containing `include/` and `lib/`, and put the tools on `PATH`. A source
39
+ `pip wheel` or `pip install .` compiles the native files when
40
+ `SYCL_NL_NATIVE_DIR` is unset. Set `SYCL_CXX`, `LLVM_SPIRV`, or `CXX` to
41
+ override tool paths. Install an existing wheel to skip source compilation.
42
+
43
+ ### PyTorch and ASE entry points
44
+
45
+ Inside an Intel GPU allocation, pass an XPU tensor of Cartesian coordinates,
46
+ the cell as three row vectors, and three periodicity flags.
47
+
48
+ ```python
49
+ import torch
50
+ from ase.build import bulk
51
+ from sycl_nl import SyclNeighborList
52
+
53
+ atoms = bulk("Si", "diamond", a=5.43)
54
+ positions = torch.as_tensor(atoms.positions, device="xpu")
55
+ with SyclNeighborList(skin=0.5, algorithm="cell_list") as neighbors:
56
+ edges = neighbors.compute(positions, atoms.cell.array, atoms.pbc, cutoff=6.5)
57
+ ```
58
+
59
+ The default algorithm is `all_pairs`. The optional `cell_list` algorithm
60
+ uses fractional-coordinate bins and works with the compiled SPIR-V kernels.
61
+ For compact, fully periodic XPU systems, it builds a dense grid on the device,
62
+ reuses metadata and scratch buffers, and emits edges in one candidate pass.
63
+ The sparse grid handles CPU, mixed periodicity, and XPU systems outside the
64
+ dense path's grid limits. Select `sparse_cell_list` to benchmark that path
65
+ directly. The order of returned edges can vary between builds. Select `half_cell_list`
66
+ to evaluate each candidate pair and periodic image once on the dense XPU
67
+ path and emit both directed edges. Self-images use a canonical shift and
68
+ its negative. The sparse path handles unsupported dense grids and CPU.
69
+
70
+ Use a CPU positions tensor to select the CPU queue. The output is an `int64` tensor on the input device with one row
71
+ `[center, neighbor, shift_a, shift_b, shift_c]` per directed edge. The
72
+ displacement is `positions[neighbor] - positions[center] + shift @ cell`.
73
+ The zero-shift self edge is excluded. Periodic self images within the cutoff
74
+ are included. For force gradients, reconstruct displacements from the original
75
+ differentiable coordinates using the returned topology.
76
+
77
+ An ASE-style function takes an `Atoms` object and returns NumPy arrays.
78
+ It supports scalar cutoffs, per-atom radii, element-pair cutoffs, and
79
+ `self_interaction`. Pass a reusable calculator to retain its Verlet cache.
80
+
81
+ ```python
82
+ from sycl_nl.ase import neighbor_list
83
+
84
+ i, j, shifts = neighbor_list("ijS", atoms, 6.5, device="xpu")
85
+ ```
86
+
87
+ ## NequIP training and inference
88
+
89
+ Install the optional `nequip` extra or use a preconfigured NequIP
90
+ environment. In training, replace the stock neighbor-list transform after
91
+ the type mapper. Use the model's cutoff. The transform runs on each frame
92
+ before the data loader batches graphs.
93
+
94
+ ```yaml
95
+ - _target_: sycl_nl.nequip.NequIPNeighborList
96
+ r_max: 6.5
97
+ skin: 0.0
98
+ ```
99
+
100
+ With no explicit `device`, the search follows the position tensor. CPU
101
+ dataset workers can build graphs on CPU for subsequent XPU training. Set
102
+ `device: xpu` to build on the GPU in the main process with
103
+ `num_workers: 0`. The output tensors follow the input positions. Graph
104
+ construction preserves the position tensor used by the model to compute
105
+ forces.
106
+
107
+ For eager ASE inference, load a NequIP calculator with its usual options,
108
+ then install the transform before the first evaluation.
109
+
110
+ ```python
111
+ from sycl_nl.nequip import use_sycl_neighborlist
112
+
113
+ neighbors = use_sycl_neighborlist(calculator, skin=0.5)
114
+ atoms.calc = calculator
115
+ ```
116
+
117
+ A positive skin retains candidates at the model cutoff plus the skin and
118
+ filters them back to the exact cutoff on each call. Atom-count changes,
119
+ cell or PBC changes, species order changes, and an indexed displacement of
120
+ at least half the skin trigger a rebuild. Pass `atom_id_key` to the transform
121
+ if the data has stable per-atom IDs and same-species permutations must
122
+ explicitly rebuild. Use `reset_cache()` when switching trajectories.
123
+ Cached candidates belong to the transform's current process and device.
124
+ Use zero skin for shuffled training data. The ASE helper supports eager
125
+ calculators whose graph uses standard directed edges. The ACES Intel XPU
126
+ test matched NequIP-OAM-M reference energies and forces and completed an
127
+ energy-and-force Adam step with a Hydra-instantiated transform.
128
+
129
+ ## First PyPI release
130
+
131
+ The distribution name is `sycl-nl` and the import is `sycl_nl`. Set up a
132
+ pending GitLab Trusted Publisher in the PyPI account's Publishing settings.
133
+
134
+ | PyPI field | Value |
135
+ | --- | --- |
136
+ | Project name | `sycl-nl` |
137
+ | GitLab namespace | `tgmaxson` |
138
+ | GitLab project | `sycl_nl` |
139
+ | Top-level pipeline | `.gitlab-ci.yml` |
140
+ | Environment | `pypi` |
141
+
142
+ In GitLab, protect the `v*` tag pattern and permit trusted maintainers to
143
+ create those tags. Push a tag matching the version in `pyproject.toml`,
144
+ such as `v0.3.0`. The `publish-pypi` job runs automatically after the
145
+ build and package checks pass. It uses GitLab's short-lived OIDC token.
146
+
147
+ The first pipeline builds and uploads a source distribution. PyPI source
148
+ installs require the matching SYCL SDK and compilers described above.
149
+ The ACES-specific binary wheel remains available for direct installation.
150
+ Compiler-free installation from PyPI requires a separately validated
151
+ portable Linux wheel that reuses PyTorch's SYCL runtime.
152
+ [PyPI Trusted Publishing setup](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
153
+
154
+ ## Tests and scaling benchmark
155
+
156
+ ```bash
157
+ SYCL_NL_BUILD_DIR="$PWD/build/native" python -m pytest -q
158
+ python benchmarks/bulk_si.py --build-dir build/native --output-dir results
159
+ ```
160
+
161
+ The tests run both algorithms and compare complete edge and shift tuples against CPU Vesin for isolated,
162
+ periodic bulk, and rattled skew Pt(111) cells. A five-frame trajectory checks
163
+ cache reuse, cutoff crossings, and a rebuild. A separate test checks that cell
164
+ changes invalidate a periodic cache.
165
+
166
+ Pass `--profile` to the XPU benchmark to capture diagnostics for the sparse and
167
+ dense cell-list paths. Stage timings include host submission and waits. The
168
+ benchmark takes the end-to-end samples separately with instrumentation disabled.
169
+
170
+ Select `packed_cell_list` to pack each bin's coordinates contiguously on XPU.
171
+ The search also assigns adjacent work items to centers from the same bin. On
172
+ an Intel Max 1100, the packed and linked paths were within about 5% of each other
173
+ across nine sizes in 20 interleaved warmed calls per size. At 5,000 atoms,
174
+ both took about 0.422 ms. Packing reduced the instrumented search stage from
175
+ 0.351 ms to 0.328 ms and added a 0.027 ms packing stage. The standard
176
+ `cell_list` option uses linked bins. Run the XPU benchmark with `--profile --cutoff 4.0`
177
+ to repeat the comparison. [Raw paired samples](docs/packed-bins.json)
178
+
179
+ The opt-in `stencil_cell_list` path caches each bin's neighbor indices and
180
+ periodic shifts for a fixed cell and cutoff. It uses linked bins without
181
+ coordinate packing. Across the nine sizes, it was 4–8% slower than computing
182
+ the stencil in the search kernel. At 5,000 atoms, the warmed medians were
183
+ 0.425 ms for linked bins and 0.447 ms with the cached stencil. Repeat the
184
+ comparison with `--compare-stencil --cutoff 4.0`. [Raw stencil timings](docs/fixed-cell-stencil.json)
185
+
186
+ The benchmark uses 14 fully periodic diamond Si supercells from **50 to
187
+ 100,000 atoms**, a 6.5 Å cutoff, and a small seeded rattle. It checks exact topology before
188
+ timing. All methods use zero skin. The quadratic all-pairs curves stop at
189
+ 5,000 atoms. The two Intel GPU cell-bin paths use 20 interleaved warmed
190
+ calls per size. Other methods use five warmed calls. The plot shows median wall time
191
+ and the range of warmed calls. JSON records the raw samples, atom and edge
192
+ counts, hardware metadata, and run parameters. CPU Vesin receives host arrays.
193
+ The SYCL calls include per-call metadata work and result sizing. On XPU,
194
+ positions already reside on the device. Initial position upload, compilation, and validation are outside
195
+ the timing window.
196
+
197
+ ![Log-log scaling plot for CPU and H100 Vesin and Intel CPU and GPU SYCL through 100,000 silicon atoms](docs/bulk-si.png)
198
+
199
+ At 100,000 atoms, the 6.5 Å cutoff produced 4,600,002 directed edges. The
200
+ CUDA Vesin and the Intel GPU and CPU SYCL paths matched CPU Vesin's edge and image-shift tuples
201
+ at all 14 sizes.
202
+
203
+ | Backend | GPU or CPU | Median at 100,000 atoms |
204
+ | --- | --- | ---: |
205
+ | SYCL, one test per pair | Intel Data Center GPU Max 1100 | 2.072 ms |
206
+ | SYCL linked bins | Intel Data Center GPU Max 1100 | 2.100 ms |
207
+ | CUDA Vesin | NVIDIA H100 PCIe | 2.311 ms |
208
+ | Vesin | Intel Xeon Platinum 8468 | 147.611 ms |
209
+ | SYCL cell bins | Intel Xeon Platinum 8468 | 497.987 ms |
210
+
211
+ The one-test path reduced the build time by about 1% at 100,000 atoms and
212
+ 13% at 48,000 atoms, with mixed results across sizes. It remains opt-in.
213
+ [CPU Vesin and Intel XPU samples](docs/bulk-si.json) · [SYCL CPU samples](docs/bulk-si-sycl-cpu.json) · [H100 samples](docs/bulk-si-h100.json)
214
+
215
+ The archived [4 Å comparison](https://gitlab.com/tgmaxson/sycl_nl/-/blob/0481068/README.md)
216
+ also includes the H100.
217
+
218
+ This repository keeps one published comparison in `docs/`. The plot and its raw
219
+ JSON files are retained together. The `results/` directory and native build products
220
+ are ignored so repeat runs stay local.
221
+
222
+ On ACES, run both from a scratch directory with
223
+ `sbatch /path/to/sycl_nl/scripts/test_benchmark.slurm /path/to/sycl_nl "$CONDA_PREFIX"`.
224
+ Install the test and benchmark dependencies in that environment first.
225
+
226
+ For CPU validation on ACES, run the same suite on a CPU node.
227
+ The job selects Intel OpenCL through the environment's `libintelocl.so`.
228
+ Both algorithms passed on an Intel Xeon Platinum 8468.
229
+
230
+ ```bash
231
+ SYCL_NL_TEST_DEVICE=cpu sbatch --partition=cpu --gres=none \
232
+ /path/to/sycl_nl/scripts/test_benchmark.slurm /path/to/sycl_nl "$CONDA_PREFIX"
233
+ ```
234
+
235
+ To time CPU SYCL, run on a CPU node with the same OpenCL runtime as above.
236
+
237
+ ```bash
238
+ OCL_ICD_FILENAMES="$CONDA_PREFIX/lib/libintelocl.so" ONEAPI_DEVICE_SELECTOR=opencl:cpu \
239
+ python benchmarks/bulk_si.py --device cpu --build-dir build/native --output-dir results
240
+ ```
241
+
242
+ In a CUDA environment with `vesin-torch`, run the companion benchmark on
243
+ an NVIDIA GPU. It checks the same 14 structures at the default 6.5 Å cutoff, uses zero skin, and times
244
+ synchronized builds with coordinates, cell, and periodicity already on device.
245
+
246
+ ```bash
247
+ python benchmarks/bulk_si_cuda.py --output results/bulk-si-h100.json
248
+ ```
249
+
250
+ Regenerate the published overlay from the saved measurements.
251
+
252
+ ```bash
253
+ python benchmarks/bulk_si.py --plot-only --output-dir docs \
254
+ --h100-json docs/bulk-si-h100.json --sycl-cpu-json docs/bulk-si-sycl-cpu.json
255
+ ```
256
+
257
+ ## Precision at 6.5 Å
258
+
259
+ The dense Intel GPU linked-bin path uses FP64 by default. The precision
260
+ experiments kept coordinate storage and bin assignment in FP64. FP32 and
261
+ FP16 cast the distance operands in the search. Mixed screens in FP32 and
262
+ rechecks near the cutoff in FP64. BF16 rounds the scalar FP32 operations
263
+ back to BF16, so its timing measures emulation. Vesin-torch 0.6.2 converts
264
+ all input dtypes to FP64 before calling CUDA Vesin.
265
+
266
+ | Device and mode | 5,000 atoms | 100,000 atoms | Extra / missing edges at 100,000 |
267
+ | --- | ---: | ---: | ---: |
268
+ | Intel Max 1100, FP64 | 1.256 ms | 2.019 ms | 0 / 0 |
269
+ | Intel Max 1100, FP32 distance | 1.338 ms | 1.989 ms | 0 / 0 |
270
+ | Intel Max 1100, FP32 screen with FP64 recheck | 3.174 ms | 3.522 ms | 0 / 0 |
271
+ | Intel Max 1100, FP16 distance | 1.528 ms | 2.247 ms | 842 / 2 |
272
+ | Intel Max 1100, BF16 distance | 4.147 ms | 3.962 ms | 585,550 / 37,342 |
273
+ | H100 Vesin, FP64 input | 0.279 ms | 2.260 ms | 0 / 0 |
274
+ | H100 Vesin, FP32 input | 0.287 ms | 2.261 ms | 0 / 0 |
275
+ | H100 Vesin, FP16 input | 0.280 ms | 2.278 ms | 742 / 2 |
276
+ | H100 Vesin, BF16 input | 0.284 ms | 2.425 ms | 591,778 / 35,720 |
277
+
278
+ Each bulk timing is the median of 20 interleaved calls. We compared full
279
+ directed edge and image-shift sets against CPU Vesin. We also tested six
280
+ near-cutoff cases in a skewed cell, including periodic translations.
281
+ FP32 changed the near-cutoff topology and gave no consistent speedup
282
+ across runs. FP16 and BF16 gave no speed benefit here and changed even the
283
+ 100,000-atom bulk topology. FP64 remains the default.
284
+
285
+ Use `python benchmarks/precision.py --device xpu --build-dir build/native --output results/precision-xpu.json`
286
+ or `python benchmarks/precision.py --device cuda --output results/precision-h100.json` in
287
+ the corresponding environment.
288
+ [Intel data](docs/precision-xpu.json) · [H100 data](docs/precision-h100.json)
289
+
290
+ ## Design and attribution
291
+
292
+ The prototype follows [Vesin](https://github.com/Luthaf/vesin)'s cutoff, directed
293
+ edge, and periodic image-shift conventions and uses Vesin as its correctness
294
+ reference. The all-pairs path checks all atom pairs for each candidate periodic
295
+ image. The optional cell-list path uses a Vesin-style neighboring-bin search
296
+ with sorted sparse bin keys or dense per-bin atom lists. The sparse path counts
297
+ then fills edges. The dense XPU path reserves output slots on device and reads
298
+ back the final count. It repeats with a larger output buffer if the initial
299
+ capacity is too small. Both use exact Cartesian distances after selecting
300
+ candidates.
301
+ A positive skin adds a cached candidate list and rebuilds when any atom moves
302
+ at least half the skin or the cell, cutoff, or periodicity changes.
303
+
304
+ The launcher uses Intel's SYCL runtime and integrates with the PyTorch queue on XPU.
305
+ AMD would need a separate compatible build and device integration.
306
+
307
+ ## License
308
+
309
+ [BSD 3-Clause](LICENSE), with the supplied Guillaume Fraux copyright notice.
310
+
311
+ ## AI disclosure
312
+
313
+ The code was developed primarily using Codex (6.2 Sol), with human validation.