Neighbours

Build a neighbour list and read it back.

Generated from the comments on the SEAMS_API declarations in include/seams.h. This tree has 85 exports. meson test docs_capi_symbols fails if a declaration is missing from these pages, and meson test docs_capi_examples compiles the example when this page has one.

// Copyright (c) d-SEAMS developers
/* One neighbour-list row per Ice Ih oxygen. */
#include "seams.h"

#include <stdio.h>

int main(void) {
  seams_system *sys = seams_system_create();
  seams_neighbours *nb = NULL;
  size_t nrows = 0;
  if (seams_system_read(sys, "input/traj/ice1h.lammpstrj", 1, -1) != SEAMS_OK) {
    return 1;
  }
  if (seams_neighbours_build(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, &nb) != SEAMS_OK) {
    fprintf(stderr, "%s\n", seams_last_error());
    return 1;
  }
  int rows = seams_neighbours_count(nb);
  if (seams_neighbours_nrows(nb, &nrows) != SEAMS_OK || nrows != 128 || rows != 128) {
    fprintf(stderr, "nrows %zu count %d\n", nrows, rows);
    return 1;
  }
  printf("neighbours %d\n", rows);
  seams_neighbours_destroy(nb);
  seams_system_destroy(sys);
  return 0;
}

seams_neighbours_build

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

Build a cutoff or mutual neighbour list.

sys

Frame handle that already holds a frame.

cutoff

Positive finite cutoff, Angstrom. The mutual graph keeps the four nearest neighbours inside cutoff + 1.5.

type

Species to keep. Zero and negative keep every atom.

graph

::SEAMS_GRAPH_CUTOFF or ::SEAMS_GRAPH_MUTUAL. ::SEAMS_GRAPH_SEEDED is rejected here.

out

Receives 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.

@par 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. @par Ownership The caller frees *out with seams_neighbours_destroy(). The list is a copy and does not borrow sys. @par Thread safety Exclusive use of sys. The new handle is private to the caller. @par Example @code seams_neighbours *nb = NULL; if (seams_neighbours_build(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, &nb) == SEAMS_OK) { seams_neighbours_destroy(nb); } @endcode

seams_neighbours_destroy

void seams_neighbours_destroy(seams_neighbours *nb)

Free a neighbour list.

nb

Handle from seams_neighbours_build() or seams_neighbours_knn(), or NULL. NULL is ignored.

@par Ownership Releases the handle and its CSR arrays. @par Thread safety The caller must not use nb after this returns. @par Example @code seams_neighbours_destroy(nb); @endcode

seams_neighbours_count

int seams_neighbours_count(const seams_neighbours *nb)

Number of neighbour rows, as an int.

nb

Neighbour handle, or NULL.

Returns: The row count, or 0 when nb is NULL.

ABI 1 query. seams_neighbours_nrows() reports errors.

@par Ownership The caller owns nb; the call borrows it. The library keeps no pointer to any argument. @par Thread safety Read-only: may run alongside other const calls on nb, and not alongside a non-const call on nb. @par Example @code int rows = seams_neighbours_count(nb); @endcode

seams_neighbours_csr

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

Deprecated. use seams_neighbours_copy; these pointers are owned by the handle.

Borrow the neighbour list as CSR.

nb

Neighbour handle.

offsets

Receives the offset pointer.

n_offsets

Receives the offset count, n + 1.

cols

Receives the column pointer. May be NULL when the list has no pairs; *nnz is then 0.

nnz

Receives the column count.

Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL.

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

@par Ownership The pointers are owned by nb and remain valid until seams_neighbours_destroy(nb). Use seams_neighbours_copy() for caller buffers. @par Thread safety Exclusive use of nb. The returned pointers must not be used concurrently with a call that frees nb. @par Example @code const int *off = NULL, *cols = NULL; int n_off = 0, nnz = 0; seams_neighbours_csr(nb, &off, &n_off, &cols, &nnz); @endcode

seams_neighbours_copy

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.

nb

Neighbour handle.

offsets

Caller buffer of offsets_cap ints, or NULL to query.

offsets_cap

Capacity of offsets. Ignored when offsets is NULL.

n_offsets

Receives the required offset count (n + 1).

cols

Caller buffer of cols_cap ints, or NULL to query.

cols_cap

Capacity of cols. Ignored when cols is NULL.

nnz

Receives 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.

@par Ownership The caller owns the buffers. The handle is not modified. @par Thread safety Read-only: may run alongside other const calls on nb, and not alongside a non-const call on nb. @par Example @code 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); @endcode

seams_neighbours_knn

seams_status seams_neighbours_knn(seams_system *sys, int k, double cutoff, int type, int mutual, seams_neighbours **out)

k-nearest neighbour list.

sys

Frame handle.

k

Positive neighbour count.

cutoff

Nominal positive cutoff, Angstrom. Candidates are taken inside cutoff + 1.5.

type

Species filter. Zero and negative keep every atom.

mutual

Non-zero keeps the mutual graph. Zero keeps the one-way k-nearest graph.

out

Receives a neighbour 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.

@par 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. @par Ownership The caller frees *out with seams_neighbours_destroy(). @par Thread safety Exclusive use of sys. @par Example @code seams_neighbours *nb = NULL; seams_neighbours_knn(sys, 4, 3.5, 0, 1, &nb); seams_neighbours_destroy(nb); @endcode

seams_neighbours_nrows

seams_status seams_neighbours_nrows(const seams_neighbours *nb, size_t *n)

Number of neighbour rows.

nb

Neighbour handle.

n

Receives the row count.

Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL when nb or n is NULL.

@par Ownership The caller owns nb; the call borrows it. n is caller storage that the call fills. The library keeps no pointer to any argument. @par Thread safety Read-only: may run alongside other const calls on nb, and not alongside a non-const call on nb. @par Example @code size_t rows = 0; seams_neighbours_nrows(nb, &rows); @endcode