Skip to main content

linkcell

linkcell

Periodic linked-cell neighbour lists for molecular simulations.

pairs_within is the cutoff list: one row per atom-image, the caller's shift S, and a squared distance strictly below the cutoff squared. knearest is the k-nearest list. nanoflann builds Euclidean KD-trees without a minimum-image convention. The walk is the linked-cell method of Allen and Tildesley (Computer Simulation of Liquids). k-nearest shells stop when the k-th neighbour reaches the unvisited plane. The optional gpulite path runs that k-nearest walk on a CUDA device and still stops on the looser reach * cell_min bound (linkcell::gpu::Workspace). src/kokkos/ is the certified walk on a Kokkos execution space. Pair lists stay on the host.

It is a LODE library. The Rust crate is the implementation. The C ABI (lc_*) is the hourglass waist, the same shape as readcon-core. C++ is a RAII header over that ABI.

Released versions live in CHANGELOG.md (Keep a Changelog). Unreleased notes are files under changelog.d/. The cut is towncrier build --version X.Y.Z.

Install

Rust:

cargo add linkcell

C and C++ consumers include linkcell.h or linkcell.hpp and link the installed library. Meson, CMake, and pkg-config install both shared and static CPU libraries. The device API is a separate static library with linkcell_gpu.h / linkcell_gpu.hpp.

Python takes the same search through DLPack (dlpk). Any __dlpack__() object (numpy, torch, jax, cupy) is a valid xyz / cell, on any device. A CUDA xyz stays on device; a CUDA cell is inverted on device. torch.from_dlpack consumes (indices, dist2). Wheels: one CPython 3.12 limited-ABI (abi3) artifact per platform (GIL, 3.12+), and one abi3t artifact (CPython 3.15+ GIL and free-threaded).

pip install linkcell
import numpy as np
import linkcell

xyz = np.array([[0.2, 0.0, 0.0], [9.4, 0.0, 0.0]], dtype=np.float64)
cell = np.array([10.0, 10.0, 10.0], dtype=np.float64)
nn, d2 = linkcell.knearest(xyz, cell, 1)
nn = np.from_dlpack(nn)

Meson

meson setup build
meson compile -C build
meson install -C build

As a wrap, Meson exposes linkcell_dep:

[wrap-git]
url = https://github.com/d-SEAMS/linkcell.git
revision = v0.3.11
depth = 1

[provide]
linkcell = linkcell_dep
linkcell-gpu = linkcell_gpu_dep
linkcell_dep = dependency('linkcell', fallback: ['linkcell', 'linkcell_dep'])
linkcell_gpu_dep = dependency(
  'linkcell-gpu',
  fallback: ['linkcell', 'linkcell_gpu_dep'],
)

with_gpulite controls the device target and defaults to auto.

CMake

cmake -B build -DCMAKE_INSTALL_PREFIX=$PREFIX
cmake --build build
cmake --install build
find_package(linkcell 0.3 REQUIRED)
target_link_libraries(c_app PRIVATE linkcell::linkcell)
target_link_libraries(cpp_app PRIVATE linkcell::cpp)
target_link_libraries(device_app PRIVATE linkcell::gpu)

LINKCELL_WITH_GPULITE=ON builds linkcell::gpu and is the default. linkcell::cpp carries the C++17 requirement; linkcell::linkcell stays valid in a C-only project. The same target names work in the build tree and from an installed prefix.

pkg-config

pkg-config --cflags --libs linkcell
pkg-config --cflags --libs linkcell-gpu

Both Meson and CMake write linkcell.pc and, when the device target is built, linkcell-gpu.pc. Use pkg-config --static when selecting the CPU static archive and its private system libraries.

Rust

use linkcell::{knearest, Cell};

let sim = Cell::ortho(10.0, 10.0, 10.0)?;
let sheared = Cell::from_vectors(
    [10.0, 0.0, 0.0],
    [5.0, 8.66, 0.0],
    [0.0, 0.0, 10.0],
    [0.0, 0.0, 0.0],
)?;
let xyz = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]];
let rows = knearest(&xyz, &sim, 1, None, None)?;
assert_eq!(rows[0].indices, vec![1]);

mask[i] == false removes a point as both a source and a candidate. cell_hint is the target cell edge; None uses 3.0 in the box units.

C

#include "linkcell.h"

double xyz[] = {0.0, 0.0, 0.0, 1.0, 0.0, 0.0};
lc_cell box = lc_cell_ortho(10.0, 10.0, 10.0);
int out[2];
if (lc_knearest(xyz, 2, &box, 1, NULL, 0.0, out) != 0) {
  return 1;
}

n and k are size_t. out has length n * k. Unused slots are -1. Neighbours of source i are out[i*k + 0 ..], nearest first.

C++

#include "linkcell.hpp"

const linkcell::Cell box = linkcell::Cell::ortho(10.0, 10.0, 10.0);
const double xyz[] = {0.0, 0.0, 0.0, 1.0, 0.0, 0.0};
const linkcell::Neighbours nn = linkcell::knearest(xyz, 2, box, 1);

nn owns the packed n * k buffer. Unused slots are -1. nn.neighbour(i, j) is the j-th neighbour of i. Failure throws linkcell::Error.

The optional device walk reads occupancy from the environment: LINKCELL_TPP (threads per particle) and LINKCELL_BLOCK (CUDA block size). Unset, the library picks a pair that maximises particles per block under the device thread and 48 KiB shared-memory limits. d-SEAMS writes the same keys from SEAMS_CONFIG / seams --tpp.

Docs

Quadrant Page
Tutorial Two points
How-to Embed from C, Embed from C++, pkg-config
Reference C ABI, Algorithm
Explanation MIC and cells

Rust API: docs.rs/linkcell. Map: docs/index.md.

Design

  • The cell is a general parallelepiped: three lattice vectors plus an origin. Orthorhombic boxes are Cell::ortho / lc_cell_ortho. Binning is in fractional space, so a sheared dump is not treated as orthogonal.
  • Points fold into the primary cell once. Each source then grows a rectangular box of neighbour cells, one axis at a time. Pair distances are a Cartesian subtract plus that cell's lattice translation (dist2_shifted and lattice_shift), the vesin / LAMMPS ghost construction. Orthorhombic boxes use three independent wraps and skip the two Hinv matvecs. The batched form of that wrap is minimage's Highway kernel, dist2_ortho_diffs, re-exported here and used by the orthorhombic brute-force check. A cutoff row keeps the stencil image, so pairs_within does not run that round on an already shifted difference. A restricted triclinic box is tilt-reduced and uses a triangular shift.
  • One lattice shift per unique cell is wrong unless every wrap of that cell is visited. The walk visits integer cell offsets, so each wrap of a bin is a separate visit.
  • knearest does not take a cutoff. A cell-size hint only sets the bin width. knearest stores each bin as a contiguous slice. An orthorhombic cell is binned as stored, a restricted triclinic cell is tilt-reduced, and a general orientation is Minkowski-reduced. The box grows until the k-th neighbour is no farther than the nearest unvisited face.
  • A cutoff pair list is pairs_within / lc_pairs_within / linkcell.pairs_within: atom-image rows with the caller's shift S. knearest is the k-nearest list. pairs_within_columns, lc_pairs_within_rows, and the Python call write the ijS columns or lc_pair rows straight from the search, and a C count query keeps its search for the fill that follows on the same thread.

License

MIT

Metadata

Release files for linkcell 0.3.11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for linkcell 0.3.11
File Size Uploaded Provenance Actions
linkcell-0.3.11.tar.gz 304.3 kB With provenance Details for linkcell-0.3.11.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for linkcell 0.3.11
File Actions
linkcell-0.3.11-cp315-abi3.abi3t-win_amd64.whl CPython 3.15 abi3, abi3t Windows x86-64 Details for linkcell-0.3.11-cp315-abi3.abi3t-win_amd64.whl
linkcell-0.3.11-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl CPython 3.15 abi3, abi3t Linux glibc 2.28+ x86-64 Details for linkcell-0.3.11-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl
linkcell-0.3.11-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl CPython 3.15 abi3, abi3t Linux glibc 2.28+ ARM64 Details for linkcell-0.3.11-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl
linkcell-0.3.11-cp315-abi3.abi3t-macosx_11_0_arm64.whl CPython 3.15 abi3, abi3t macOS 11.0+ ARM64 Details for linkcell-0.3.11-cp315-abi3.abi3t-macosx_11_0_arm64.whl
linkcell-0.3.11-cp312-abi3-win_amd64.whl CPython 3.12 abi3 Windows x86-64 Details for linkcell-0.3.11-cp312-abi3-win_amd64.whl
linkcell-0.3.11-cp312-abi3-manylinux_2_28_x86_64.whl CPython 3.12 abi3 Linux glibc 2.28+ x86-64 Details for linkcell-0.3.11-cp312-abi3-manylinux_2_28_x86_64.whl
linkcell-0.3.11-cp312-abi3-manylinux_2_28_aarch64.whl CPython 3.12 abi3 Linux glibc 2.28+ ARM64 Details for linkcell-0.3.11-cp312-abi3-manylinux_2_28_aarch64.whl
linkcell-0.3.11-cp312-abi3-macosx_11_0_arm64.whl CPython 3.12 abi3 macOS 11.0+ ARM64 Details for linkcell-0.3.11-cp312-abi3-macosx_11_0_arm64.whl

Total release size: 4.7 MB

Release files / linkcell-0.3.11.tar.gz

Download URL linkcell-0.3.11.tar.gz
Size 304.3 kB
Tags Source
SHA-256 checksum
How to use checksums
cb0ccb1b9e8a98ef5259b05f26d5412ce56f5d3874938a6536c8913bb8540678
BLAKE2b-256 checksum
How to use checksums
1b40e0c3c11abd37764cfa31c9e6ca4d9025e5ee463270895a4c7f2c9313314a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / linkcell-0.3.11-cp315-abi3.abi3t-win_amd64.whl

Download URL linkcell-0.3.11-cp315-abi3.abi3t-win_amd64.whl
Size 677.9 kB
Tags CPython 3.15 Windows x86-64 abi3 abi3t
SHA-256 checksum
How to use checksums
c444925a1433fc25025589c8f656152ac519f79343d3380acb71082fb420ec1e
BLAKE2b-256 checksum
How to use checksums
793ee77fabfd1b3acd84ce5e3744753d4063eb3f6490795ea81e0491ff15b32a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / linkcell-0.3.11-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl

Download URL linkcell-0.3.11-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl
Size 572.3 kB
Tags CPython 3.15 Linux glibc 2.28+ x86-64 abi3 abi3t
SHA-256 checksum
How to use checksums
ee97263369949ad67079362bbc86dd37e791bd39265b71ec680031697a34ef44
BLAKE2b-256 checksum
How to use checksums
cef4288e747e92b142b33b1c1d6ca02232935e04a80bece6d91479e10e364be8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / linkcell-0.3.11-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl

Download URL linkcell-0.3.11-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl
Size 490.3 kB
Tags CPython 3.15 Linux glibc 2.28+ ARM64 abi3 abi3t
SHA-256 checksum
How to use checksums
30a2fec662a538e6ececbc728188aa00a8324f2eefe9cdfebc301d1e26c3a358
BLAKE2b-256 checksum
How to use checksums
dae8e7351cc9239665f5f63f9a963447ad4b19592da24035615d5554d3d75321
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / linkcell-0.3.11-cp315-abi3.abi3t-macosx_11_0_arm64.whl

Download URL linkcell-0.3.11-cp315-abi3.abi3t-macosx_11_0_arm64.whl
Size 455.3 kB
Tags CPython 3.15 abi3 abi3t macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
bc2428e4a3108292fe2eff673a373afbb841f707bf2f039bb650f91c737e16b9
BLAKE2b-256 checksum
How to use checksums
fad234f557c335657626fa0ec59bfa0032cd1c851851ef303a9cd96e84b4b4c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / linkcell-0.3.11-cp312-abi3-win_amd64.whl

Download URL linkcell-0.3.11-cp312-abi3-win_amd64.whl
Size 650.4 kB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
34ddf5af264c605bbc6da33a946e49907c39dbaa6e931cacb381f4b705efce6f
BLAKE2b-256 checksum
How to use checksums
e52819df0c83c2fb34b6f4ad91485af9adde023f0dc41963e554ec8df98830ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / linkcell-0.3.11-cp312-abi3-manylinux_2_28_x86_64.whl

Download URL linkcell-0.3.11-cp312-abi3-manylinux_2_28_x86_64.whl
Size 569.5 kB
Tags CPython 3.12 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
be3330ef6043fe36492d1b6121901629a478c61832c3dcc0b5775c8b2d0ff861
BLAKE2b-256 checksum
How to use checksums
4241e1d39776dcbb1163746dacacb33333f8a56f109c8569f9241e4cbe16b4a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / linkcell-0.3.11-cp312-abi3-manylinux_2_28_aarch64.whl

Download URL linkcell-0.3.11-cp312-abi3-manylinux_2_28_aarch64.whl
Size 487.3 kB
Tags CPython 3.12 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
f08040fd9ab31b66a49975cffdfb28db5755257750b337d6eeac2bf535bdfdeb
BLAKE2b-256 checksum
How to use checksums
3c4064019b96e299ead3ea2d03df8a492413e1916b18c6b16bb6d6a9029b17da
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Release files / linkcell-0.3.11-cp312-abi3-macosx_11_0_arm64.whl

Download URL linkcell-0.3.11-cp312-abi3-macosx_11_0_arm64.whl
Size 452.4 kB
Tags CPython 3.12 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
dca5d2533368c89dcbb37e3f340d907e5a210a8b932a8917e51d94905814804b
BLAKE2b-256 checksum
How to use checksums
2e0ae925d3e75735803f2888e0bd3a5a121e853fc5e1dce8b5d8b879d97e7e74
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

Security for linkcell 0.3.11

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 9 files in this release have been uploaded with provenance metadata.

Select from 9 files

Attestation for linkcell-0.3.11.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page