Skip to content

C application binary interface (ABI)

Header: include/linkcell.h. Prefix lc_. Caller owns every buffer. C++ (include/linkcell.hpp) is a header-only wrap of these entry points. Device searches are lc_gpu_* in include/linkcell_gpu.h; link the package's linkcell-gpu target.

Cell

typedef struct lc_cell {
  double ax, ay, az;
  double bx, by, bz;
  double cx, cy, cz;
  double ox, oy, oz;
} lc_cell;

lc_cell lc_cell_ortho(double lx, double ly, double lz);

Lattice vectors are rows a, b, c (the same order vesin uses) plus an origin. lc_cell_ortho builds a diagonal box at the origin.

int lc_knearest(const double *xyz, size_t n, const lc_cell *simbox,
                size_t k, const int *mask, double cell_hint,
                int *out_nn);

int lc_knearest_d2(const double *xyz, size_t n, const lc_cell *simbox,
                   size_t k, const int *mask, double cell_hint,
                   int *out_nn, double *out_d2);

int lc_knearest_many(const double *xyz, size_t n, size_t n_frames,
                     const lc_cell *simbox, size_t k, const int *mask,
                     double cell_hint, int *out_nn, double *out_d2);
Argument Contract
xyz n packed x y z triples. Not null.
n Point count. size_t. Zero is an error.
simbox Periodic parallelepiped. Not null.
k Neighbours per source. size_t. Zero is an error.
mask NULL (keep every point) or n ints, nonzero to include. A zero drops the point as both source and candidate.
cell_hint Target bin edge. <= 0 selects the default (3.0 in box units).
out_nn Caller-owned, length n * k. Unused slots are -1. Neighbours of source i are out_nn[i*k + t], nearest first.
out_d2 Optional. Caller-owned, length n * k (n_frames * n * k for lc_knearest_many). Unused slots are NaN. NULL skips distances.
n_frames Frame count for lc_knearest_many. xyz is frame-major.

lc_knearest is the one-frame, indices-only entry. Returns 0 on success, nonzero on failure.

int lc_pairs_within(const double *xyz, size_t n, const lc_cell *simbox,
                    double cutoff, const int *mask, double cell_hint,
                    int half, int *out_i, int *out_j, int *out_shift,
                    double *out_d2, size_t cap, size_t *out_count);

A cutoff list is lc_pairs_within. Each row is one atom-image. out_shift[3 * t + 0..3] is (na, nb, nc), the vesin / tonari shift S in the caller's basis. Squared distance is strictly below cutoff * cutoff. half nonzero keeps one side of (i, j, S). Null out_i, out_j, out_shift, and out_d2 query *out_count. A short cap writes that count and returns nonzero.

typedef struct lc_pair { int i; int j; int shift[3]; double dist2; } lc_pair;

int lc_pairs_within_rows(const double *xyz, size_t n, const lc_cell *simbox,
                         double cutoff, const int *mask, double cell_hint,
                         int half, lc_pair *out, size_t cap,
                         size_t *out_count);

lc_pairs_within_rows is the same list as one array of lc_pair rows. Null out queries *out_count.

A query, or a short buffer, keeps its search on the calling thread. That thread writes the rows from the saved search when the next call repeats xyz, the box, cutoff, mask, cell_hint, and half bit for bit. Any other call drops the saved search. A fill that writes keeps nothing, so a count-then-fill pair is one search.

uint64_t lc_stencil_builds(void);

int lc_pairs_open(const double *xyz, size_t n, double cutoff,
                  double cell_hint, lc_pair *out, size_t cap,
                  size_t *out_count);

int lc_pairs_within_pbc(const double *xyz, size_t n, const lc_cell *simbox,
                        const int *pbc, double cutoff, const int *mask,
                        double cell_hint, int half, int closed,
                        int exclude_self_images, lc_pair *out, size_t cap,
                        size_t *out_count);

lc_pairs_open is the Cartesian half list of an open cluster: i < j, shift zero, squared distance strictly below cutoff * cutoff. lc_pairs_within_pbc is that list with a periodicity mask. pbc[k] nonzero keeps axis k periodic. A null pbc is fully periodic and is lc_pairs_within_rows. An open axis is binned on the occupied Cartesian cells. It is not padded into a periodic box. lc_stencil_builds counts partner stencils that were built. A stencil that is reused, because the atoms stayed inside the same bounding bins, does not increment it.

Errors and version

const char *lc_last_error(void);
const char *lc_version(void);

Both return pointers the caller leaves alone. lc_last_error is thread-local and NULL after a successful lc_knearest on that thread, or if none has failed yet. lc_version returns the process-static version string. The pointer is invalid after the next lc_knearest on the same thread. Distinct searches may run concurrently; each thread reads its own slot. lc_version is process-static.

C++ wrap

namespace linkcell {
class Error : public std::runtime_error { /* status() is the C return */ };

struct Cell {
  std::array<double, 3> a, b, c, origin;
  static Cell ortho(double lx, double ly, double lz);
  static Cell from_vectors(std::array<double, 3> a, std::array<double, 3> b,
                           std::array<double, 3> c,
                           std::array<double, 3> origin = {});
  lc_cell raw() const;
};

class Neighbours {
  int neighbour(std::size_t i, std::size_t j) const; /* or -1 */
  double dist2(std::size_t i, std::size_t j) const;  /* unused NaN */
  std::size_t n() const;
  std::size_t k() const;
  const int *data() const;
  const double *distances() const;
};

void knearest_into(const double *xyz, std::size_t n, const Cell &cell,
                   std::size_t k, int *out, std::size_t out_len,
                   const int *mask = nullptr, double cell_hint = 0.0);

Neighbours knearest(const double *xyz, std::size_t n, const Cell &cell,
                    std::size_t k, const int *mask = nullptr,
                    double cell_hint = 0.0);

const char *version();

struct ShiftedPair {
  int i, j;
  std::array<int, 3> shift;
  double dist2;
};

std::vector<ShiftedPair> pairs_within(const double *xyz, std::size_t n,
                                      const Cell &cell, double cutoff,
                                      const int *mask = nullptr,
                                      double cell_hint = 0.0,
                                      bool half = false);
}

knearest returns an owning packed Neighbours (n * k ints). knearest_into writes a caller buffer and requires out_len == n * k. Neither returns std::vector<std::vector<int>>. Failure throws linkcell::Error. Requires C++17.

ShiftedPair has the layout of lc_pair. pairs_within queries the count, then lc_pairs_within_rows writes the returned vector from that same search.

Partition

lc_cell_grid writes nx, ny, nz, three bin widths, and one point count per cell. lc_cell_graph adds the compressed sparse row (CSR) of the periodic adjacency. Edge weights are pair counts from lc_pairs_within with half set. lc_partition writes one domain id per cell. method is 0 Morton, 1 Hilbert, 2 recursive coordinate bisection (RCB), 3 Hilbert plus Fiduccia-Mattheyses, 4 bisection plus that pass, 5 Scotch, 6 multilevel, 7 parallel Scotch. balance <= 0 selects 1 + parts * w_max / total, where w_max is the heaviest cell weight and total is the sum of the cell weights. That is the tightest bound a cell-aligned cut can promise, and it is the ratio the d-SEAMS domain driver derives per frame. lc_halo_width writes three bin radii for cutoff * depth. lc_halo writes the ghost cell ids.

A null weight or domain pointer queries the count. The C++ wrappers are linkcell::partition, linkcell::halo_width, and linkcell::halo.

Rust errors (same crate)

linkcell::Error:

Variant Meaning
ZeroK k == 0
BadBox A box length is not strictly positive, or H is singular
Empty The point list is empty
BufferSize knearest_into / out length is not n * k
MaskLen mask is Some and mask.len() != n
TooManyCells linked-cell mesh overflows the bin cap
Overflow n * k overflows a slice
BadPartition The part count is zero, or the balance bound is below 1
BadGraph The cell graph must be a square compressed sparse row (CSR) of that grid
NoDevice A device curve split was requested and no device is loaded
ScotchDisabled Scotch support was not compiled in

Error::Empty is not a wrong-length buffer.

Walk and stop rule: algorithm.