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.10
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.10

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.10
File Size Uploaded Provenance Actions
linkcell-0.3.10.tar.gz 302.0 kB With provenance Details for linkcell-0.3.10.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for linkcell 0.3.10
File Actions
linkcell-0.3.10-cp315-abi3.abi3t-win_amd64.whl CPython 3.15 abi3, abi3t Windows x86-64 Details for linkcell-0.3.10-cp315-abi3.abi3t-win_amd64.whl
linkcell-0.3.10-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.10-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl
linkcell-0.3.10-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl CPython 3.15 abi3t, abi3 Linux glibc 2.28+ ARM64 Details for linkcell-0.3.10-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl
linkcell-0.3.10-cp315-abi3.abi3t-macosx_11_0_arm64.whl CPython 3.15 abi3, abi3t macOS 11.0+ ARM64 Details for linkcell-0.3.10-cp315-abi3.abi3t-macosx_11_0_arm64.whl
linkcell-0.3.10-cp312-abi3-win_amd64.whl CPython 3.12 abi3 Windows x86-64 Details for linkcell-0.3.10-cp312-abi3-win_amd64.whl
linkcell-0.3.10-cp312-abi3-manylinux_2_28_x86_64.whl CPython 3.12 abi3 Linux glibc 2.28+ x86-64 Details for linkcell-0.3.10-cp312-abi3-manylinux_2_28_x86_64.whl
linkcell-0.3.10-cp312-abi3-manylinux_2_28_aarch64.whl CPython 3.12 abi3 Linux glibc 2.28+ ARM64 Details for linkcell-0.3.10-cp312-abi3-manylinux_2_28_aarch64.whl
linkcell-0.3.10-cp312-abi3-macosx_11_0_arm64.whl CPython 3.12 abi3 macOS 11.0+ ARM64 Details for linkcell-0.3.10-cp312-abi3-macosx_11_0_arm64.whl

Total release size: 4.6 MB

Release files / linkcell-0.3.10.tar.gz

Download URL linkcell-0.3.10.tar.gz
Size 302.0 kB
Tags Source
SHA-256 checksum
How to use checksums
61d80bf29c013bce3dcd1a9d85d4d26b6141cac69058cfdd8364640e9682e08c
BLAKE2b-256 checksum
How to use checksums
d4600e5ab8a0aa60ce1f4b046042604bd169fc5c780a5ae3fd558726e49305fc
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.10-cp315-abi3.abi3t-win_amd64.whl

Download URL linkcell-0.3.10-cp315-abi3.abi3t-win_amd64.whl
Size 675.5 kB
Tags CPython 3.15 Windows x86-64 abi3 abi3t
SHA-256 checksum
How to use checksums
e51860a38d34573c2fd6b7efc305a88a8f353c697172f28d90e1c69b40a65bc7
BLAKE2b-256 checksum
How to use checksums
ba7b0b88807d673e16db30a6e1693945c3a35505318cb4d9be977f889c535324
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.10-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl

Download URL linkcell-0.3.10-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl
Size 569.8 kB
Tags CPython 3.15 Linux glibc 2.28+ x86-64 abi3 abi3t
SHA-256 checksum
How to use checksums
25c643166868d85368cae399f7ed537b7a2e4934ba2b001b48b335da7490dc83
BLAKE2b-256 checksum
How to use checksums
cd8f09c930d8f78e72a3714ed8633f9a01b23fc71f3f825906994ea88d00ee08
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.10-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl

Download URL linkcell-0.3.10-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl
Size 487.4 kB
Tags CPython 3.15 Linux glibc 2.28+ ARM64 abi3 abi3t
SHA-256 checksum
How to use checksums
5df4b6ceb0b78e9f7fea1ef3a4d82296b4e81e6a4306c7e3ff0f48a7225f20ca
BLAKE2b-256 checksum
How to use checksums
677e2230ab47c2e37468e66b8253050cddf469578dea4c2223ad7fa263155a93
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.10-cp315-abi3.abi3t-macosx_11_0_arm64.whl

Download URL linkcell-0.3.10-cp315-abi3.abi3t-macosx_11_0_arm64.whl
Size 453.2 kB
Tags CPython 3.15 abi3 abi3t macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
329233e6e635bae1d6960a592a1f8cf7434cb40720fdaef1bdd9d3361671b2de
BLAKE2b-256 checksum
How to use checksums
32a5788ba934459fb97d87f8434ee9cc7a7d44a3553d2adf5efcb66237b3ad85
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.10-cp312-abi3-win_amd64.whl

Download URL linkcell-0.3.10-cp312-abi3-win_amd64.whl
Size 648.2 kB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
d7062831466c63416adf8e1ab63c29bd253d0c352284a8516307e5103b36d567
BLAKE2b-256 checksum
How to use checksums
04f9e15920261be0a61ea2ac6f26b6849fdb6f8f629084f4b99ed8d97314301a
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.10-cp312-abi3-manylinux_2_28_x86_64.whl

Download URL linkcell-0.3.10-cp312-abi3-manylinux_2_28_x86_64.whl
Size 566.9 kB
Tags CPython 3.12 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
cd89da1ebc0c6f24dfe90f5d322cc7d2c0567047b4376b0ec97ed037f35a3a0b
BLAKE2b-256 checksum
How to use checksums
fc4bd66beac892caf6d58ed4bb6c25cd566fbc21a8d307520ff260048672bb4b
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.10-cp312-abi3-manylinux_2_28_aarch64.whl

Download URL linkcell-0.3.10-cp312-abi3-manylinux_2_28_aarch64.whl
Size 484.3 kB
Tags CPython 3.12 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
8ac2a6ce41357b9d286502e87a0e9c24f986a9faf9c432f21a3b797066849ed7
BLAKE2b-256 checksum
How to use checksums
09fefd817f15e83709458b0a0349b6513f38809b586f431ca015042539abffb1
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.10-cp312-abi3-macosx_11_0_arm64.whl

Download URL linkcell-0.3.10-cp312-abi3-macosx_11_0_arm64.whl
Size 451.4 kB
Tags CPython 3.12 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
a27f0077152fc69f94cfc319f58285e88c338e04321580fe37767b4d7d47bf07
BLAKE2b-256 checksum
How to use checksums
7e4076a34c928efeb0c8844c31d28f705ae400fa8f872adf1599ef0df9adc89a
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.10

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.10.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