Fast pair list C ABI¶
CppCore/rgpot/nlist/fastnlist.h is the C ABI of a Rust static library, CppCore/rgpot/nlist/fastnlist/src/lib.rs.
The library is built on the linkcell crate and the minimage crate that
linkcell uses.
Meson builds it when it finds cargo and rustc 1.89 or newer, the rust-version
in its Cargo.toml.
That is the default, -Dwith_fast_nlist=auto.
The build then defines RGPOT_HAS_FAST_NLIST and links the archive into
librgpot.
CMake does not build it.
The library does not convert units.
Coordinates, cells, cutoffs and difference vectors share the caller’s length
unit.
cell9 is nine doubles, the lattice vectors as rows:
ax ay az bx by bz cx cy cz.
A hard failure returns -1 and stores a message for rgpot_fast_last_error on
the calling thread.
Callers¶
The Fortran water-H kernel, CppCore/rgpot/fortran/rgpot_water_h.f90, wraps its
legs with rgpot_fast_wrap.
On a sheared cell it keeps that result only when it is shorter than half the
smallest face width, and otherwise uses its 26-image scan.
rgpot_fast_pairs and rgpot_fast_wrap_axes have no caller inside the
potentials.
LJPot, MorsePot and LJClusterPot search pairs with the C++ cell list
rgpot::nlist::Neighbours, not with this library.
LJClusterPot walks all pairs directly when the bounding box of the atoms fits
inside the cutoff, there is no switch, and the neighbour mode is not a stream.
CppCore/tests/FastNlistTest.cc checks the counts from rgpot_fast_pairs and
checks the potentials against a direct scan.
Pair candidates¶
Which set rgpot_fast_pairs returns depends on the cell.
Cell |
Candidates |
|---|---|
any periodic axis narrower than three cutoffs |
all pairs, |
any open axis whose atoms span at most one cutoff |
all pairs |
otherwise |
linkcell pairs inside the cutoff |
The width of a periodic axis is the diagonal element of the cell. Each linkcell bin is checked against itself and its 26 neighbours. Why the cut is at three bins is in Neighbour list design. On an all-pairs answer the caller folds every pair with the minimum image and drops the pairs outside the cutoff.
An all-pairs answer has n * (n - 1) / 2 pairs.
The call computes that count without building a list and writes the pairs
straight into the caller’s buffer.
For 10000 atoms that is 49995000 pairs of two 4-byte ints, about 400 MB.
On the linkcell path each call runs the search, so a probe followed by a fill
searches twice.
Functions¶
rgpot_fast_pairs¶
int rgpot_fast_pairs(const double *xyz, size_t n, const double *cell9,
const int32_t *periodic, double list_cutoff,
int32_t *out_ij, size_t cap, size_t *out_count);
- Inputs
xyzis3 * ndoubles, row-majorx y zper atom.cell9is the cell andperiodicthree ints, nonzero for a periodic axis.list_cutoffis the candidate cutoff.out_ijholdscappairs, two ints each; it may be null when the call only probes.- Units
xyz,cell9andlist_cutoffshare the caller’s length unit.- Outputs
\*out_countis the number of candidate pairs. When that count fits incap,out_ijreceives the pairs asi, jwithi < j, unique and sorted, and the call returns 0. When it does not fit, the call returns 1 and leavesout_ijuntouched. Fewer than two atoms, or alist_cutoffthat is not positive and finite, gives 0 pairs and returns 0. Self images are never included. An open axis is padded inside the call so that no periodic image across it falls inside the cutoff.- Errors
-1 for a null
out_count,cell9orperiodic, a nullxyzwithn > 0, or a nullout_ijwhen the pairs fit incapand there is at least one. -1 for a cell with a nonzero off-diagonal element (“pair list requires an orthorhombic cell”) or a periodic axis whose width is not positive. -1 whenndoes not fit inint32_tor the count does not fit insize_t. A return of 0 or 1 clears the message ofrgpot_fast_last_error.
rgpot_fast_wrap¶
int rgpot_fast_wrap(const double *cell9, const double *diffs, size_t n,
double *out);
- Inputs
cell9, any non-singular cell, anddiffs,ndifference vectors as3 * ndoubles.outholds3 * ndoubles.- Units
cell9,diffsandoutshare the caller’s length unit.- Outputs
outreceives each vector wrapped on every axis, and the call returns 0. The wrap rounds the fractional coordinatesH^-1 dto the nearest image and returnsHtimes the remainder. On an orthorhombic cell that is the minimum image. On a sheared cell a result shorter than half the smallest face width is the minimum image; a longer one may not be.- Errors
-1 for a null
cell9, a nulldiffsoroutwithn > 0, or a singular cell (“singular or non-positive cell”).
rgpot_fast_wrap_axes¶
int rgpot_fast_wrap_axes(const double *cell9, const int32_t *periodic,
const double *diffs, size_t n, double *out);
- Inputs
as
rgpot_fast_wrap, plusperiodic, three ints, nonzero for a periodic axis.- Units
cell9,diffsandoutshare the caller’s length unit.- Outputs
outreceives each vector with its periodic components folded to the minimum image and its open components unchanged, and the call returns 0. An open axis is given a width of 1e16, so a component folds only once its magnitude reaches 5e15.- Errors
-1 for a null
cell9orperiodic, a nulldiffsoroutwithn > 0, a cell with a nonzero off-diagonal element (“axis wrap requires an orthorhombic cell”), or a periodic axis whose width is not positive.
rgpot_fast_last_error¶
const char *rgpot_fast_last_error(void);
- Inputs
none.
- Units
none.
- Outputs
the message of the most recent -1 return on this thread, or null when the most recent call on this thread succeeded or no call has failed. The pointer is owned by the library and stays valid until the next call of this library on the same thread.
- Errors
none; the call cannot fail.
Probe and fill¶
The caller owns the buffer. A probe with no buffer returns the count, and a second call fills it.
#include <stdio.h>
#include <stdlib.h>
#include "rgpot/nlist/fastnlist.h"
int main(void) {
const double xyz[9] = {0.0, 0.0, 0.0, 1.5, 0.0, 0.0, 0.0, 1.5, 0.0};
const double cell9[9] = {20.0, 0.0, 0.0, 0.0, 20.0, 0.0, 0.0, 0.0, 20.0};
const int32_t periodic[3] = {1, 1, 1};
const double list_cutoff = 2.0;
size_t count = 0;
int rc = rgpot_fast_pairs(xyz, 3, cell9, periodic, list_cutoff, NULL, 0, &count);
if (rc < 0) {
fprintf(stderr, "%s\n", rgpot_fast_last_error());
return 1;
}
int32_t *ij = malloc(2 * (count ? count : 1) * sizeof *ij);
rc = rgpot_fast_pairs(xyz, 3, cell9, periodic, list_cutoff, ij, count, &count);
if (rc != 0 || count != 2) {
fprintf(stderr, "rc %d count %zu\n", rc, count);
return 1;
}
for (size_t p = 0; p < count; ++p) {
printf("%d %d\n", ij[2 * p], ij[2 * p + 1]);
}
free(ij);
return 0;
}