# linkcell

> Periodic linked-cell neighbour lists for molecular simulations: a cutoff pair list (`pairs_within`) with the caller's lattice shift per row, and a k-nearest list (`knearest`), on orthorhombic and general triclinic cells.

The Rust crate `linkcell` is the implementation. The C ABI (`lc_*`, `include/linkcell.h`) is the interface every other language uses: C++ through `include/linkcell.hpp`, Python through DLPack (`pip install linkcell`). Meson, CMake and pkg-config consume an installed prefix. seams-core (d-SEAMS) calls this library for its neighbour lists. Contributor rules and commands are in the contributing guide at the repository root.

## Start

- [README](https://github.com/d-SEAMS/linkcell/blob/main/README.md): what the library computes, install lines for Rust, C, C++, Python, Meson and CMake
- [Documentation site](https://d-seams.github.io/linkcell/): the pages below, rendered
- [Tutorial: two points](https://d-seams.github.io/linkcell/tutorials/two-points/): nearest neighbour of two atoms in a 10-unit cubic box, in each language

## How-to guides

- [Embed linkcell from C](https://d-seams.github.io/linkcell/how-to/embed-c/): link the installed CPU library and include linkcell.h
- [Embed linkcell from C++](https://d-seams.github.io/linkcell/how-to/embed-cpp/): the C++17 RAII header over the C ABI, with CMake
- [Embed linkcell from Python](https://d-seams.github.io/linkcell/how-to/embed-python/): the DLPack module, accepting any object with `__dlpack__()`
- [Use pkg-config](https://d-seams.github.io/linkcell/how-to/pkg-config/): linkcell.pc and linkcell-gpu.pc from Meson and CMake installs

## Reference

- [C ABI](https://d-seams.github.io/linkcell/reference/c-api/): every `lc_*` entry point, ownership and error contract
- [Rust API](https://d-seams.github.io/linkcell/api/linkcell/): rustdoc for the crate
- [Algorithm](https://d-seams.github.io/linkcell/reference/algorithm/): the linked-cell walk, the k-heap per source, basis reduction, threading and bit identity
- [Cell partition](https://d-seams.github.io/linkcell/reference/partition/): domain ids per cell, halos, and the balance bound
- [Changelog](https://github.com/d-SEAMS/linkcell/blob/main/CHANGELOG.md): release notes per version

## Explanation

- [Minimum image and linked cells](https://d-seams.github.io/linkcell/explanation/mic-and-cells/): why the walk applies lattice shifts per cell instead of a minimum image per pair
- [SIMD paths and dispatch](https://d-seams.github.io/linkcell/explanation/simd-paths/): scalar, AVX2, AVX-512 and NEON paths, and the bit identity they keep

## Related

- [minimage](https://github.com/lode-org/minimage): the minimum-image library linkcell uses for cell geometry and floors
- [seams-core](https://github.com/d-SEAMS/seams-core): the d-SEAMS analysis engine that calls linkcell, documented at https://docs.dseams.info
