Neighbour-list C ABI¶
CppCore/rgpot/nlist/rgpot_nlist.h declares the neighbour query of librgpot.
CppCore/rgpot/nlist/NeighbourList.cc implements it.
Every function returns an RGPOT_NLIST_* code unless its entry says otherwise.
RGPOT_NLIST_ABI is 4.
The library does not convert units.
Positions, cutoff, skin, pair vectors and distances share one length unit,
the one the caller uses.
box9 is nine doubles, the lattice vectors as rows:
ax ay az bx by bz cx cy cz.
The pair vector of (i, j) at integer shift S is r_j - r_i + S H, with H
the rows of box9.
A pair of an atom with itself at shift zero is never returned.
Different objects may be used from different threads at the same time.
One walk, one builder and the buffers of one call are used by one thread.
A build of at least 8192 atoms starts an OpenMP team when OMP_NUM_THREADS asks
for more than one thread.
The runtime may start fewer threads, as inside another OpenMP region; the list
does not depend on how many.
Codes¶
Code |
Value |
|
|---|---|---|
|
0 |
ok |
|
1 |
neighbour request abi or size does not match this library |
|
2 |
a required neighbour pointer is null |
|
3 |
cutoff and skin must be finite and >= 0 |
|
4 |
box must be finite, and a periodic box must have positive volume |
|
5 |
neighbour shape, shell or cut is not a supported value |
|
6 |
neighbour buffer is shorter than the list; needed holds the full count |
|
7 |
neighbour list allocation failed |
|
8 |
a positive skin needs a loose cut; a strict cut stores no buffer |
The functions that take a request check it in this order.
A null request returns RGPOT_NLIST_NULL.
bytes shorter than the struct through
want_distances, or abi other than RGPOT_NLIST_ABI, returns RGPOT_NLIST_ERR_ABI.
shape, shell or cut outside 0 and 1, or shape 1 with shell 0, returns
RGPOT_NLIST_SHAPE.
Null positions with n > 0, or a null box9, returns RGPOT_NLIST_NULL.
A negative or non-finite cutoff or skin returns RGPOT_NLIST_CUTOFF.
skin > 0 with cut 0 returns RGPOT_NLIST_SKIN.
A non-finite element of box9, or a zero-volume box with any periodic axis,
returns RGPOT_NLIST_BOX.
A failed allocation returns RGPOT_NLIST_NOMEM.
Types¶
rgpot_nlist_request¶
- Inputs
bytesissizeof(rgpot_nlist_request)as the caller compiled it, andabiisRGPOT_NLIST_ABI.cutoffandskinare the cutoff and the Verlet buffer.shapeis 0 for pairs and 1 for a cluster of four.shellis 0 for a half list and 1 for a full list.cutis 0 for strict (distance <cutoff) and 1 for loose (distance <cutoff + skin, or distance <=cutoffwhenskinis 0).periodicis one flag per axis, nonzero when the axis is periodic.want_shifts,want_vectorsandwant_distancesare nonzero for each column the call fills.- Units
cutoffandskinare in the length unit of the positions; every other field has none.- Outputs
none; the caller fills the struct, normally after
rgpot_nlist_request_init.- Errors
the codes listed under Codes for a bad request.
A half list keeps one direction of each pair, with the rule vesin uses for an
atom and its own periodic image.
A full list keeps both directions.
A cluster list stores every neighbour, so it needs shell 1.
rgpot_nlist_soa¶
- Inputs
bytesissizeof(rgpot_nlist_soa)as the caller compiled it.capis the number of pairs each column holds.firstandsecondholdcapints.shiftholds3 * capints andvector3 * capdoubles, pairpat elements3p,3p+1,3p+2.distanceholdscapdoubles andmaskcapbytes. A null column pointer skips that column.- Units
vectoranddistanceare in the length unit of the positions; the other columns have none.- Outputs
the calls write zero-based atom indices into
firstandsecond, and each requested column for every pair they write.maskis 0xff for a pair list. For a cluster listfirstis the lowest index of four consecutive atoms,secondthe partner, and bitkofmaskis set when atomfirst + khas that partner at that shift. The vector and distance of a cluster row belong to the lowest atom whose bit is set. A column the request did not ask for is not written even when its pointer is set.- Errors
bytessmaller than the struct throughcapreturnsRGPOT_NLIST_ERR_ABI. Withcap > 0, a nullfirstorsecond, a null pointer for a requested column, or a nullmaskon a cluster list returnsRGPOT_NLIST_NULLbefore anything is written.
rgpot_nlist_walk¶
- Inputs
none; an opaque handle from
rgpot_nlist_walk_open.- Units
none.
- Outputs
none.
- Errors
none.
A walk borrows positions and box9 until rgpot_nlist_walk_close.
The caller keeps those arrays alive and does not write them during a pull.
rgpot_nlist_builder¶
- Inputs
none; an opaque handle from
rgpot_nlist_builder_open.- Units
none.
- Outputs
none.
- Errors
none.
rgpot_nlist_fortran_list¶
- Inputs
none; an opaque handle from
rgpot_nlist_fortran_open.- Units
none.
- Outputs
none.
- Errors
none.
Functions¶
rgpot_nlist_abi_version¶
int32_t rgpot_nlist_abi_version(void);
- Inputs
none.
- Units
none.
- Outputs
RGPOT_NLIST_ABIof the loaded library.- Errors
none; the call cannot fail.
rgpot_nlist_strerror¶
const char *rgpot_nlist_strerror(int32_t code);
- Inputs
code, a value returned by a neighbour call.- Units
none.
- Outputs
a string literal, the text in the Codes table. The caller does not free it.
- Errors
none; an unknown code returns “unknown neighbour error”.
rgpot_nlist_request_init¶
void rgpot_nlist_request_init(rgpot_nlist_request *request);
- Inputs
request, caller storage.- Units
none.
- Outputs
zeroes
\*request, then setsbytes,abi, a half pair list with a strict cut, every axis periodic, and all threewant_*flags.cutoffandskinstay 0.- Errors
none; a null
requestis ignored.
rgpot_nlist_build¶
int32_t rgpot_nlist_build(const double *positions, size_t n, const double *box9,
const rgpot_nlist_request *request, rgpot_nlist_soa *out,
size_t *count, size_t *needed);
- Inputs
positionsis3 * ndoubles, row-majorx y zper atom.box9is the cell,requestthe query andoutthe caller’s columns.countandneededmay be null.- Units
positions,box9, the request’scutoffandskin, and the writtenvectoranddistanceshare the caller’s length unit.- Outputs
\*neededis the number of pairs in the list.\*countis the number written, at mostout->cap. A nullout, orout->cap0, writes no pair, sets\*countto 0 and returnsRGPOT_NLIST_OK; this is the size probe.- Errors
RGPOT_NLIST_SHORTafter writingout->cappairs when the list is longer. The request, geometry and buffer errors listed under Codes andrgpot_nlist_soa. On an error other thanRGPOT_NLIST_SHORT,\*countis 0.
Each call searches again; the probe and the fill search twice.
rgpot_nlist_walk_open¶
int32_t rgpot_nlist_walk_open(const double *positions, size_t n,
const double *box9,
const rgpot_nlist_request *request,
rgpot_nlist_walk **walk);
- Inputs
positions(3 * ndoubles),box9,request, andwalk, where the handle goes.- Units
as
rgpot_nlist_build.- Outputs
\*walk, a new walk over the geometry. The walk does not store the pairs of the whole system.- Errors
RGPOT_NLIST_NULLfor a nullwalk. The request and geometry errors listed under Codes. On any error\*walkis null whenwalkis not null.
rgpot_nlist_walk_pull¶
int32_t rgpot_nlist_walk_pull(rgpot_nlist_walk *walk, rgpot_nlist_soa *out,
size_t *count, int32_t *done);
- Inputs
walk,out(the caller’s columns), andcountanddone, which may be null.- Units
vectoranddistanceare in the length unit of the positions given torgpot_nlist_walk_open.- Outputs
up to
out->cappairs written intoout.\*countis the number written.\*doneis 1 once the geometry is exhausted, which can be on a pull that also wrote pairs.out->cap0 writes nothing and does not advance.- Errors
RGPOT_NLIST_NULLfor a nullwalkorout. The buffer errors ofrgpot_nlist_soa. An error does not advance the walk and sets\*countto 0.
rgpot_nlist_walk_close¶
void rgpot_nlist_walk_close(rgpot_nlist_walk *walk);
- Inputs
walk, a handle fromrgpot_nlist_walk_openor null.- Units
none.
- Outputs
frees the walk and ends its borrow of
positionsandbox9.- Errors
none; a null
walkis ignored.
rgpot_nlist_build_systems¶
int32_t rgpot_nlist_build_systems(const double *positions, const int32_t *counts,
size_t nsystems, const double *box9,
const rgpot_nlist_request *request,
rgpot_nlist_soa *out, int32_t *system,
size_t *count, size_t *needed);
- Inputs
positionsis the concatenation ofnsystemssystems,counts[s]atoms each,3doubles per atom.box9holds9 * nsystemsdoubles, one cell per system in the same order.system, when not null, holdsout->capints.- Units
as
rgpot_nlist_build; every system uses the same length unit.- Outputs
the pairs of every system, system 0 first.
firstandsecondindex the concatenated positions.system[p]is the system of pairp.\*needed,\*countand the size probe behave as inrgpot_nlist_build.- Errors
RGPOT_NLIST_NULLwhennsystems > 0andpositions,countsorbox9is null.RGPOT_NLIST_SHAPEfor a negativecounts[s]. The other codes as inrgpot_nlist_build.
The systems do not see each other’s atoms.
rgpot_nlist_builder_open¶
int32_t rgpot_nlist_builder_open(rgpot_nlist_builder **builder);
- Inputs
builder, where the handle goes.- Units
none.
- Outputs
\*builder, a builder that holds no list yet.- Errors
RGPOT_NLIST_NULLfor a nullbuilder;RGPOT_NLIST_NOMEMwith\*buildernull when the allocation fails.
rgpot_nlist_builder_update¶
int32_t rgpot_nlist_builder_update(rgpot_nlist_builder *builder,
const double *positions, size_t n,
const double *box9,
const rgpot_nlist_request *request,
rgpot_nlist_soa *out, size_t *count,
size_t *needed, int32_t *reused);
- Inputs
builderand the arguments ofrgpot_nlist_build.reusedmay be null.- Units
as
rgpot_nlist_build.- Outputs
\*reusedis 1 when the stored list was kept, else 0. The list is kept whenn,box9and every request field are unchanged and every atom has moved by at mostskin / 2since the last search. Withskin0 that means the coordinates did not move.out,\*count,\*neededand the size probe behave as inrgpot_nlist_build. On a kept list every column,vectoranddistanceincluded, describes the geometry of the last search.- Errors
RGPOT_NLIST_NULLfor a nullbuilder. The other codes as inrgpot_nlist_build. A rejected geometry leaves the stored list as it was.
rgpot_nlist_builder_close¶
void rgpot_nlist_builder_close(rgpot_nlist_builder *builder);
- Inputs
builder, a handle fromrgpot_nlist_builder_openor null.- Units
none.
- Outputs
frees the builder and its list.
- Errors
none; a null
builderis ignored.
rgpot_nlist_fortran_open¶
rgpot_nlist_fortran_list *rgpot_nlist_fortran_open(void);
- Inputs
none.
- Units
none.
- Outputs
a new list handle.
- Errors
returns null when the allocation fails.
rgpot_nlist_fortran_close¶
void rgpot_nlist_fortran_close(rgpot_nlist_fortran_list *list);
- Inputs
list, a handle fromrgpot_nlist_fortran_openor null.- Units
none.
- Outputs
frees the list.
- Errors
none; a null
listis ignored.
rgpot_nlist_fortran_build¶
int32_t rgpot_nlist_fortran_build(rgpot_nlist_fortran_list *list,
const double *positions, size_t natoms,
const double *box9, double cutoff, double skin,
const int32_t periodic[3], int32_t *first,
int32_t *second, double *vector, double *distance,
size_t cap, size_t *count, int32_t *reused);
- Inputs
list,positions(3 * natomsdoubles),box9,cutoff,skin, andperiodic, three ints, nonzero for a periodic axis.first,secondanddistanceholdcapvalues andvector3 * capdoubles. Whenfirstis not null,second,vectoranddistancemust not be null; the call does not check them.countandreusedmay be null.- Units
positions,box9,cutoff,skin,vectoranddistanceshare the caller’s length unit.- Outputs
the pairs strictly inside
cutofffor the positions passed in, both directions of each pair (a full list), indices zero-based.vectoris in Fortran(3, npairs)order,x y zof pair 0, then pair 1. Vectors and distances are computed from these positions even when the stored search is reused.\*countis the number of such pairs, which can exceedcap; at mostcapare written. A nullfirstwrites no pair and only sets\*count.\*reusedis 1 when the stored search was kept.- Errors
RGPOT_NLIST_NULLwith\*count0 whenlist,positions,box9orperiodicis null.RGPOT_NLIST_SHORTwhenfirstis not null and the count exceedscap. The geometry codes listed under Codes, with\*count0.
The list keeps a builder that searches at cutoff + skin with a loose cut when
skin > 0, and at cutoff with a strict cut when skin is 0.
The search is reused while every atom stays within skin / 2 of the last
search.
Cap’n Proto messages¶
CppCore/rgpot/rpc/local/neighbour-chunk.diff adds the query to the
Potentials.capnp that rgpot compiles and installs.
The pinned potentials-schema file does not have it;
CppCore/rgpot/rpc/local/series lists the rgpot-local diffs.
The messages carry the columns of rgpot_nlist_request and rgpot_nlist_soa.
Lengths are in the unit of the positions, ForceInput.lengthUnit on the wire.
No rgpot server answers the query yet.
potserv and rgpot_rpc_server_start do not implement Potential.neighbours,
so a call fails with Cap’n Proto’s unimplemented error.
They ignore ForceInput.neighbors and never set PotentialResult.neighborList.
CppCore/examples/nlist_stream.cc sends NeighborRequest and NeighborList as
framed messages over a socket and serves each chunk from a stored list.
Field |
Type |
Meaning |
|---|---|---|
|
|
The query to answer with the forces. A client that does not know it leaves it unset. |
|
|
The answer, present only when |
|
method |
Takes |
|
Type |
Default |
Meaning |
|---|---|---|---|
|
|
0 |
The cutoff, as |
|
|
0 |
The Verlet buffer, as |
|
|
0 |
0 half pairs, 1 full pairs, 2 cluster of four. It is |
|
|
0 |
0 strict, 1 loose, as |
|
|
empty |
One flag per axis. Empty means every axis is periodic. |
|
|
true |
Fill |
|
|
true |
Fill |
|
|
true |
Fill |
|
|
1 |
1 one stored chunk, 2 a stream that honours |
|
|
0 |
The pair index the chunk starts at. |
|
|
0 |
The most pairs in the reply. 0 means 4096 on a stream. |
|
|
empty |
Empty for one system. Otherwise systems that do not interact, as in |
|
|
0 |
The atoms of the system. Positions are concatenated in the order of |
|
|
empty |
The cell of the system, the lattice vectors as rows. |
|
Type |
Meaning |
|---|---|---|
|
|
The first atom of each pair. With |
|
|
The second atom of each pair, the same length as |
|
|
Three integers per pair when shifts were requested. |
|
|
Three values per pair. |
|
|
One value per pair. |
|
|
One byte per pair, 0xff for a pair list and the low four bits for a cluster. |
|
|
True when a later chunk exists. The client repeats the call with the same query. |
|
|
The |
|
|
0 on success. |
|
|
A sentence when |
|
|
The system of each pair. Empty when the request named one system. |
Example¶
The size probe, then the fill.
#include <stdio.h>
#include <stdlib.h>
#include "rgpot/nlist/rgpot_nlist.h"
int main(void) {
const double positions[9] = {0.0, 0.0, 0.0, 1.5, 0.0, 0.0, 0.0, 1.5, 0.0};
const double box9[9] = {10.0, 0.0, 0.0, 0.0, 10.0, 0.0, 0.0, 0.0, 10.0};
rgpot_nlist_request request;
rgpot_nlist_request_init(&request);
request.cutoff = 2.0;
size_t count = 0, needed = 0;
int32_t rc = rgpot_nlist_build(positions, 3, box9, &request, NULL, &count, &needed);
if (rc != RGPOT_NLIST_OK) {
fprintf(stderr, "%s\n", rgpot_nlist_strerror(rc));
return 1;
}
rgpot_nlist_soa out = {0};
out.bytes = sizeof out;
out.cap = needed;
out.first = malloc(needed * sizeof *out.first);
out.second = malloc(needed * sizeof *out.second);
out.shift = malloc(3 * needed * sizeof *out.shift);
out.vector = malloc(3 * needed * sizeof *out.vector);
out.distance = malloc(needed * sizeof *out.distance);
rc = rgpot_nlist_build(positions, 3, box9, &request, &out, &count, &needed);
if (rc != RGPOT_NLIST_OK || count != 2) {
fprintf(stderr, "rc %d count %zu\n", rc, count);
return 1;
}
for (size_t p = 0; p < count; ++p) {
printf("%d %d %.3f\n", out.first[p], out.second[p], out.distance[p]);
}
free(out.first);
free(out.second);
free(out.shift);
free(out.vector);
free(out.distance);
return 0;
}