seams-core v2.14.0
libyodaLib, the C++ engine of d-SEAMS
Loading...
Searching...
No Matches
Neighbour lists

Cutoff, mutual, and k-nearest graphs as CSR. More...

Functions

SEAMS_API seams_status seams_neighbours_build (seams_system *sys, double cutoff, int type, int graph, seams_neighbours **out)
 Build a cutoff or mutual neighbour list.
SEAMS_API void seams_neighbours_destroy (seams_neighbours *nb)
 Free a neighbour list.
SEAMS_API int seams_neighbours_count (const seams_neighbours *nb)
 Number of neighbour rows, as an int.
SEAMS_API seams_status seams_neighbours_csr (const seams_neighbours *nb, const int **offsets, int *n_offsets, const int **cols, int *nnz)
 Borrow the neighbour list as CSR.
SEAMS_API seams_status seams_neighbours_copy (const seams_neighbours *nb, int *offsets, size_t offsets_cap, size_t *n_offsets, int *cols, size_t cols_cap, size_t *nnz)
 Copy the neighbour CSR into caller buffers.

Detailed Description

Cutoff, mutual, and k-nearest graphs as CSR.

Function Documentation

◆ seams_neighbours_build()

SEAMS_API seams_status seams_neighbours_build ( seams_system * sys,
double cutoff,
int type,
int graph,
seams_neighbours ** out )

Build a cutoff or mutual neighbour list.

Parameters
sysFrame handle that already holds a frame.
cutoffPositive finite cutoff, Angstrom. The mutual graph keeps the four nearest neighbours inside cutoff + 1.5.
typeSpecies to keep. Zero and negative keep every atom.
graphSEAMS_GRAPH_CUTOFF or SEAMS_GRAPH_MUTUAL. SEAMS_GRAPH_SEEDED is rejected here.
outReceives a new handle. On failure *out is NULL.
Returns
SEAMS_OK, or SEAMS_ERR_NULL, SEAMS_ERR_STATE, SEAMS_ERR_RANGE, SEAMS_ERR_ARG, SEAMS_ERR_NOMEM, SEAMS_ERR_INTERNAL.
Handle access
Non-const only because the call clears the handle's error slot on entry, so seams_handle_error() reports this call. It reads the frame and keeps no scratch on the handle.
Ownership
The caller frees *out with seams_neighbours_destroy(). The list is a copy and does not borrow sys.
Thread safety
Exclusive use of sys. The new handle is private to the caller.
Example
seams_neighbours *nb = NULL;
}
SEAMS_API void seams_neighbours_destroy(seams_neighbours *nb)
Free a neighbour list.
SEAMS_API seams_status seams_neighbours_build(seams_system *sys, double cutoff, int type, int graph, seams_neighbours **out)
Build a cutoff or mutual neighbour list.
struct seams_neighbours seams_neighbours
One neighbour list.
Definition seams.h:243
@ SEAMS_OK
The call succeeded.
Definition seams.h:154
@ SEAMS_GRAPH_CUTOFF
Every neighbour inside the cutoff.
Definition seams.h:208

◆ seams_neighbours_copy()

SEAMS_API seams_status seams_neighbours_copy ( const seams_neighbours * nb,
int * offsets,
size_t offsets_cap,
size_t * n_offsets,
int * cols,
size_t cols_cap,
size_t * nnz )

Copy the neighbour CSR into caller buffers.

Parameters
nbNeighbour handle.
offsetsCaller buffer of offsets_cap ints, or NULL to query.
offsets_capCapacity of offsets. Ignored when offsets is NULL.
n_offsetsReceives the required offset count (n + 1).
colsCaller buffer of cols_cap ints, or NULL to query.
cols_capCapacity of cols. Ignored when cols is NULL.
nnzReceives the required column count.
Returns
SEAMS_OK when every non-NULL buffer was filled, or when both buffers were NULL and the lengths were written. SEAMS_ERR_RANGE when a non-NULL buffer is short. SEAMS_ERR_NULL when nb, n_offsets, or nnz is NULL.
Ownership
The caller owns the buffers. The handle is not modified.
Thread safety
Read-only: may run alongside other const calls on nb, and not alongside a non-const call on nb.
Example
size_t n_off = 0, nnz = 0;
seams_neighbours_copy(nb, NULL, 0, &n_off, NULL, 0, &nnz);
int *off = malloc(n_off * sizeof *off), *cols = malloc(nnz * sizeof *cols);
seams_neighbours_copy(nb, off, n_off, &n_off, cols, nnz, &nnz);
free(off);
free(cols);
SEAMS_API seams_status seams_neighbours_copy(const seams_neighbours *nb, int *offsets, size_t offsets_cap, size_t *n_offsets, int *cols, size_t cols_cap, size_t *nnz)
Copy the neighbour CSR into caller buffers.

◆ seams_neighbours_count()

SEAMS_API int seams_neighbours_count ( const seams_neighbours * nb)

Number of neighbour rows, as an int.

ABI 1 query. seams_neighbours_nrows() reports errors.

Parameters
nbNeighbour handle, or NULL.
Returns
The row count, or 0 when nb is NULL.
Ownership
The caller owns nb; the call borrows it. The library keeps no pointer to any argument.
Thread safety
Read-only: may run alongside other const calls on nb, and not alongside a non-const call on nb.
Example
int rows = seams_neighbours_count(nb);
SEAMS_API int seams_neighbours_count(const seams_neighbours *nb)
Number of neighbour rows, as an int.

◆ seams_neighbours_csr()

SEAMS_API seams_status seams_neighbours_csr ( const seams_neighbours * nb,
const int ** offsets,
int * n_offsets,
const int ** cols,
int * nnz )

Borrow the neighbour list as CSR.

Offsets has n + 1 entries. Columns omit the self entry.

Parameters
nbNeighbour handle.
offsetsReceives the offset pointer.
n_offsetsReceives the offset count, n + 1.
colsReceives the column pointer. May be NULL when the list has no pairs; *nnz is then 0.
nnzReceives the column count.
Returns
SEAMS_OK, or SEAMS_ERR_NULL.
Ownership
The pointers are owned by nb and remain valid until seams_neighbours_destroy(nb). Use seams_neighbours_copy() for caller buffers.
Thread safety
Exclusive use of nb. The returned pointers must not be used concurrently with a call that frees nb.
Example
const int *off = NULL, *cols = NULL;
int n_off = 0, nnz = 0;
seams_neighbours_csr(nb, &off, &n_off, &cols, &nnz);
SEAMS_API seams_status seams_neighbours_csr(const seams_neighbours *nb, const int **offsets, int *n_offsets, const int **cols, int *nnz)
Borrow the neighbour list as CSR.

◆ seams_neighbours_destroy()

SEAMS_API void seams_neighbours_destroy ( seams_neighbours * nb)

Free a neighbour list.

Parameters
nbHandle from seams_neighbours_build() or seams_neighbours_knn(), or NULL. NULL is ignored.
Ownership
Releases the handle and its CSR arrays.
Thread safety
The caller must not use nb after this returns.
Example