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.0
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++, pkg-config
Reference C ABI, Algorithm
Explanation Minimum image convention (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.
  • 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). The partner stencil is rebuilt only when those bounding bins change, and 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.0

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.0
File Size Uploaded Provenance Actions
linkcell-0.4.0.tar.gz 486.0 kB With provenance Details for linkcell-0.4.0.tar.gz

Built distributions (wheels)

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

Total release size: 7.8 MB

Release files / linkcell-0.4.0.tar.gz

Download URL linkcell-0.4.0.tar.gz
Size 486.0 kB
Tags Source
SHA-256 checksum
How to use checksums
1e033a899ff765fa5f82051a8a34f63aafd431d8f4b19483a8e7702906c336c3
BLAKE2b-256 checksum
How to use checksums
8f4a18f636cc03c3c27820c8c727cf7d2b57efefca539c0f489354c9e07f3b5b
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.0-cp315-abi3.abi3t-win_amd64.whl

Download URL linkcell-0.4.0-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
76f3cd177bf73b21b11c2b5ec17ae9f74ad695fe88585293569bc7273eecfdfc
BLAKE2b-256 checksum
How to use checksums
88db573f0b7857ce55d00da1183a256cca6bb0abda7014ee5cedababd0ba3895
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.0-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl

Download URL linkcell-0.4.0-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
3a2c6e4bb327e6ffd9243fc4955c7bf8dc2399df01aaaa0a0a37431abea79ff8
BLAKE2b-256 checksum
How to use checksums
938ec0c84c2ad1d5664ed999912e334ca63b80dbcd49880098e74e8fad4007e4
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.0-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl

Download URL linkcell-0.4.0-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl
Size 849.1 kB
Tags CPython 3.15 Linux glibc 2.28+ ARM64 abi3 abi3t
SHA-256 checksum
How to use checksums
7163a9e3398b13b291bf6545aa390a8c0cdd4af9ba19c7b0646cde65f767a51a
BLAKE2b-256 checksum
How to use checksums
901cdd802102453fb3ac277fe9851c8731ed9d441f95edc6b636ef14376a41db
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.0-cp315-abi3.abi3t-macosx_11_0_arm64.whl

Download URL linkcell-0.4.0-cp315-abi3.abi3t-macosx_11_0_arm64.whl
Size 690.5 kB
Tags CPython 3.15 abi3 abi3t macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
20a918197a96ec3cf6eecd5b56748cc76ffb5cf59a5202b9b774bdc4bc34c997
BLAKE2b-256 checksum
How to use checksums
e3b9d0bae136bc72d4b2f65a678b293c80f232a531e051c63848bea6ecfa4bf9
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.0-cp312-abi3-win_amd64.whl

Download URL linkcell-0.4.0-cp312-abi3-win_amd64.whl
Size 1.0 MB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
a442cfb3d6e36c535057bc147665cea937e4fc886cbe0c8b34051a2252478519
BLAKE2b-256 checksum
How to use checksums
2c9137221e91676b91c1784e9c10d3118bde710537e324a8e6565aa98cea358e
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.0-cp312-abi3-manylinux_2_28_x86_64.whl

Download URL linkcell-0.4.0-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
6b39ba39c42ba9aa5ebbbdd417c5834e235602d41021e3942d17c3cdaee6a35c
BLAKE2b-256 checksum
How to use checksums
40d4184d53c2ea07c4d6892b4f703a320cf435084edeb0e79cbe54c05fa77fc7
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.0-cp312-abi3-manylinux_2_28_aarch64.whl

Download URL linkcell-0.4.0-cp312-abi3-manylinux_2_28_aarch64.whl
Size 845.8 kB
Tags CPython 3.12 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
23fdb33f340780d88bc11e6bf547b82ac98a81aeeaeeaaaa5b4d219a33932a77
BLAKE2b-256 checksum
How to use checksums
dd152fb093de0c05da259584632ecaad1b56fe30e0c8b3918b8563f3ad6d5af4
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.0-cp312-abi3-macosx_11_0_arm64.whl

Download URL linkcell-0.4.0-cp312-abi3-macosx_11_0_arm64.whl
Size 686.0 kB
Tags CPython 3.12 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
957b913a0c63713fe37a56c28520549979c89c98e4641c025ecb0b5054b0f4c0
BLAKE2b-256 checksum
How to use checksums
8612045bfd573b40cfc5e664bf90b408956365f5a6714b71b28abbb73f0061df
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.0

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