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.
Search¶
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.