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.

The host pair-list library is a Library of Data Exchange (LODE) library for the linked-cell walk. The Rust crate is the implementation. The C application binary interface (lc_*) is the hourglass waist, the same shape as readcon-core. C++ is a Resource Acquisition Is Initialization (RAII) header over that interface.

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.

The Python library install 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.4.1
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.4 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

The documentation is published at d-seams.github.io/linkcell, with the Rust API under /api and an llms.txt map. The sources are under docs/.

Quadrant Page
Tutorial Two points
How-to Embed from C, Embed from C++, Embed from Python, pkg-config
Reference C ABI, Algorithm, Cell partition
Explanation Minimum image convention (MIC) and cells, SIMD paths and dispatch

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.
  • An open axis is not padded into a periodic box. pairs_open / lc_pairs_open bins the occupied Cartesian cells and returns the half list (i < j, shift zero). With every axis open the partner stencil depends on the cutoff and the bin edge alone, so frames in other bins reuse it; with a periodic axis it is rebuilt when the bounding bins change. lc_stencil_builds counts the builds. pairs_within_pbc is the same list with a periodicity mask; a fully periodic mask is pairs_within.
  • Points fold into the primary cell once. Each source then grows a rectangular box of neighbour cells, one direction 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 skips 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 takes a neighbour count and a cell-size hint. The 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.

Domain partition

cell_grid is the fractional mesh pairs_within uses, with a point count on each bin. cell_graph adds the periodic adjacency. An edge weight is the number of cutoff pairs with one end in each bin. partition returns one domain id per cell. halo_width turns a cutoff and a shell count into three bin radii, and halo lists the ghost bins of one domain.

The balance bound defaults to 1 + parts * w_max / total for every system. w_max is the heaviest cell weight and total is the sum of the cell weights. lc_partition selects that ratio when balance <= 0. A weighted median assigns the straddling cell to one side. The part may exceed the ideal share by at most that cell. That is the tightest bound a cell-aligned cut can promise, and it is the ratio the d-SEAMS domain driver derives per frame. Our method computes the default from the five-system panel in examples/partition_panel.rs. We report the native cut with the smallest sum of edge cuts among the cuts that stay inside that bound. A tie breaks toward the smaller sum of median wall times. Morton, Hilbert, recursive coordinate bisection (RCB), and a Fiduccia-Mattheyses pass are always built. Serial Scotch is --features scotch. Parallel Scotch is --features ptscotch. Neither library is vendored, and both features are off by default. The device path runs weights, curve keys, and the prefix split through gpulite. Copies both ways are inside that time.

use linkcell::{halo, halo_width, partition, PartRequest, Cell};

let sim = Cell::ortho(10.0, 10.0, 10.0)?;
let xyz = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]];
let domain = partition(&xyz, &sim, 3.0, None, None, PartRequest::new(2))?;
let width = halo_width(3.0, 1, [10.0, 10.0, 10.0])?;
let _ghosts = halo(
    &linkcell::cell_grid(&xyz, &sim, 3.0, None, None)?,
    &domain,
    0,
    width,
)?;

lc_cell_grid, lc_cell_graph, lc_partition, lc_halo_width, and lc_halo are the C entry points. linkcell::partition in include/linkcell.hpp is the Resource Acquisition Is Initialization wrap. Python is cell_grid, cell_graph, partition, halo_width, and halo, all DLPack.

License

Massachusetts Institute of Technology (MIT)

Metadata

Release files for linkcell 0.4.1

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.4.1
File Size Uploaded Provenance Actions
linkcell-0.4.1.tar.gz 502.0 kB With provenance Details for linkcell-0.4.1.tar.gz

Built distributions (wheels)

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

Total release size: 7.9 MB

Release files / linkcell-0.4.1.tar.gz

Download URL linkcell-0.4.1.tar.gz
Size 502.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ca1712929dee755c41301830d1c1ac18b22359eb83123bde7940cfe5c27f6f1e
BLAKE2b-256 checksum
How to use checksums
a3dd3c3f4cd1fb168f1be4ceeeee42af26948da6b51bb66cc02cd26d6d57e2e3
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 Nov 16, 2026.

Transparency log

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

Download URL linkcell-0.4.1-cp315-abi3.abi3t-win_amd64.whl
Size 1.1 MB
Tags CPython 3.15 Windows x86-64 abi3 abi3t
SHA-256 checksum
How to use checksums
bbaf2ddaf52d20d4ff135da848dd2aae46de64af1d67f97b481deacf4ec11dbc
BLAKE2b-256 checksum
How to use checksums
439f23b914690d6d5a0c08d6c30056cf633964e0b96fb7fe2574b88a5ab13890
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 Nov 16, 2026.

Transparency log

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

Download URL linkcell-0.4.1-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl
Size 1.1 MB
Tags CPython 3.15 Linux glibc 2.28+ x86-64 abi3 abi3t
SHA-256 checksum
How to use checksums
8ec2c358270a9d8462ed6cc211b13a40e63fc4dbdaa4f5f863192ebccdbd6501
BLAKE2b-256 checksum
How to use checksums
79b1b64de2457bf8ff926be883b009f3a4a9bfc56084bc55190abf114f4592c9
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 Nov 16, 2026.

Transparency log

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

Download URL linkcell-0.4.1-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl
Size 864.2 kB
Tags CPython 3.15 Linux glibc 2.28+ ARM64 abi3 abi3t
SHA-256 checksum
How to use checksums
39ca9f04b5e222ac796b4c5e31da13869e601a6b2b610ca8dd67bef0a3e060d0
BLAKE2b-256 checksum
How to use checksums
ef035317ff749e42f6baccc76dfd9f56606f3472c6c54d7dd7dd50bca41ebb09
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 Nov 16, 2026.

Transparency log

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

Download URL linkcell-0.4.1-cp315-abi3.abi3t-macosx_11_0_arm64.whl
Size 703.3 kB
Tags CPython 3.15 abi3 abi3t macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
b9aafbf51867776f31494e4149b46d29c34b36319b12c911de732271552dcf8d
BLAKE2b-256 checksum
How to use checksums
a730e5f20fed4271686adff1bf35eddc3defb2f9ab792ece57485d088553c8f1
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 Nov 16, 2026.

Transparency log

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

Download URL linkcell-0.4.1-cp312-abi3-win_amd64.whl
Size 1.0 MB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
2ea4ac41c7ee212a0bbc70f621e712adcee8640685b93a83226bdf17bbc7e2ea
BLAKE2b-256 checksum
How to use checksums
57afc95cb4692b9677103c5665e8642e7fac35f9d29213694296b11e279d4ef3
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 Nov 16, 2026.

Transparency log

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

Download URL linkcell-0.4.1-cp312-abi3-manylinux_2_28_x86_64.whl
Size 1.1 MB
Tags CPython 3.12 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
9a5aaba150d279177b71a9d8eecc81b5b413ca7160f9965ce742d9a2926fe798
BLAKE2b-256 checksum
How to use checksums
00cfd8dd59d37b69bab5d7aa7a6571aeb835f985b1d8cc99ba308699dc1dae47
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 Nov 16, 2026.

Transparency log

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

Download URL linkcell-0.4.1-cp312-abi3-manylinux_2_28_aarch64.whl
Size 860.8 kB
Tags CPython 3.12 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
665ad51aa69f57f023f8217062a024a5d29126ba360b52b7996e601b3644a685
BLAKE2b-256 checksum
How to use checksums
278ad78130eec6385b4d536289f8524ec9e44be7d0a6e2a51ab5925866aeb0c7
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 Nov 16, 2026.

Transparency log

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

Download URL linkcell-0.4.1-cp312-abi3-macosx_11_0_arm64.whl
Size 700.2 kB
Tags CPython 3.12 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
9b78d80ba3c53cb33435fdf7107f867ecdd32e9b86cf7c7a54f11a2f484f72b8
BLAKE2b-256 checksum
How to use checksums
31ff0a641d40b7d7b7d78be59484b5fdb9e88173bac3c0b00127cf071d0852e4
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 Nov 16, 2026.

Transparency log

Security for linkcell 0.4.1

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.4.1.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 Nov 16, 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