seams-core v2.14.0
libyodaLib, the C++ engine of d-SEAMS
Loading...
Searching...
No Matches
Status-returning and length-checked entry points

Preferred spellings for new callers. More...

Functions

SEAMS_API const char * seams_last_error_message (void)
 Thread-local detail of the last failing call on this thread.
SEAMS_API seams_status seams_system_natoms (const seams_system *sys, size_t *n)
 Number of points in the frame.
SEAMS_API seams_status seams_neighbours_nrows (const seams_neighbours *nb, size_t *n)
 Number of neighbour rows.
SEAMS_API seams_status seams_rings_nrings (const seams_rings *rings, size_t *n)
 Number of primitive rings.
SEAMS_API seams_status seams_chill_plus_n (seams_system *sys, double cutoff, int type, int graph, int rule, int *labels, size_t labels_len, int counts9[9])
 CHILL+ labels into a buffer of known length.
SEAMS_API seams_status seams_q4q6_n (seams_system *sys, double cutoff, int type, double *q4, size_t q4_len, double *q6, size_t q6_len)
 Local q4 and q6 on the cutoff shell into buffers of known length.
SEAMS_API seams_status seams_rings_labels_n (const seams_rings *rings, int *sizes, size_t sizes_len, int *symmetry, size_t symmetry_len)
 Size and symmetry of each ring into buffers of known length.
SEAMS_API seams_status seams_rings_histogram_n (const seams_rings *rings, int *counts, size_t counts_len)
 Count primitive rings by size into a buffer of known length.

Detailed Description

Preferred spellings for new callers.

Each one reports errors through seams_status and takes a size_t length for every caller buffer.

Function Documentation

◆ seams_chill_plus_n()

SEAMS_API seams_status seams_chill_plus_n ( seams_system * sys,
double cutoff,
int type,
int graph,
int rule,
int * labels,
size_t labels_len,
int counts9[9] )

CHILL+ labels into a buffer of known length.

rule selects the q_lm shell. SEAMS_CHILL_PUBLISHED, the default, is Nguyen and Molinero equation 1: the four closest neighbours. SEAMS_CHILL_OVITO is every neighbour inside the cutoff, which is the OVITO Chill+ modifier. Labels match seams_label.

Parameters
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter. Zero and negative keep every atom.
graphSEAMS_GRAPH_CUTOFF or SEAMS_GRAPH_MUTUAL.
ruleSEAMS_CHILL_PUBLISHED or SEAMS_CHILL_OVITO.
labelsCaller buffer of labels_len ints.
labels_lenMust be at least the frame count.
counts9Nine ints that receive the population of each label, or NULL.
Returns
SEAMS_OK; SEAMS_ERR_NULL for a NULL sys or labels; SEAMS_ERR_STATE when sys holds no frame; SEAMS_ERR_RANGE for a short labels buffer or a non-positive or non-finite cutoff; SEAMS_ERR_ARG for an unknown rule or graph; SEAMS_ERR_NOMEM; SEAMS_ERR_INTERNAL.
Handle access
Non-const: writes each atom's CHILL+ label into the stored frame and clears the handle's error slot on entry. Coordinates, cell, types, and ids are not changed.
Ownership
The caller owns labels and counts9.
Thread safety
Exclusive use of sys.
Example
int counts[9];
labels, n, counts);
SEAMS_API seams_status seams_chill_plus_n(seams_system *sys, double cutoff, int type, int graph, int rule, int *labels, size_t labels_len, int counts9[9])
CHILL+ labels into a buffer of known length.
@ SEAMS_CHILL_PUBLISHED
Nguyen and Molinero, four closest neighbours.
Definition seams.h:202
@ SEAMS_GRAPH_CUTOFF
Every neighbour inside the cutoff.
Definition seams.h:208

◆ seams_last_error_message()

SEAMS_API const char * seams_last_error_message ( void )

Thread-local detail of the last failing call on this thread.

The string is empty after a successful call on this thread. Prefer seams_handle_error() when the failing call had a handle: that copy survives a later call on another handle. seams_last_error() is the ABI 1 spelling and returns the same string.

Returns
Pointer to a thread-local string. Never NULL.
Ownership
Owned by the library. Valid until the next call on this thread that sets or clears the error.
Thread safety
The storage is thread-local.
Example
fprintf(stderr, "%s: %s\n", seams_status_string(rc), seams_last_error_message());
SEAMS_API const char * seams_status_string(seams_status status)
Short name of a status code.
SEAMS_API const char * seams_last_error_message(void)
Thread-local detail of the last failing call on this thread.
SEAMS_API seams_status seams_system_natoms(const seams_system *sys, size_t *n)
Number of points in the frame.
seams_status
Status codes.
Definition seams.h:153

◆ seams_neighbours_nrows()

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

Number of neighbour rows.

Parameters
nbNeighbour handle.
nReceives the row count.
Returns
SEAMS_OK, or SEAMS_ERR_NULL when nb or n is NULL.
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.
Thread safety
Read-only: may run alongside other const calls on nb, and not alongside a non-const call on nb.
Example
size_t rows = 0;
SEAMS_API seams_status seams_neighbours_nrows(const seams_neighbours *nb, size_t *n)
Number of neighbour rows.

◆ seams_q4q6_n()

SEAMS_API seams_status seams_q4q6_n ( seams_system * sys,
double cutoff,
int type,
double * q4,
size_t q4_len,
double * q6,
size_t q6_len )

Local q4 and q6 on the cutoff shell into buffers of known length.

Parameters
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
q4Local q4, or NULL.
q4_lenLength of q4. Ignored when q4 is NULL.
q6Local q6, or NULL. q4 and q6 may not both be NULL.
q6_lenLength of q6. Ignored when q6 is NULL.
Returns
SEAMS_OK, or SEAMS_ERR_NULL, SEAMS_ERR_STATE, SEAMS_ERR_RANGE for a short buffer or a bad cutoff, SEAMS_ERR_NOMEM, SEAMS_ERR_INTERNAL.
Handle access
Non-const only because the call clears the handle's error slot on entry; it reads the frame and nothing else on the handle. The q_lm work arrays belong to the calling thread, so calls on different handles may run at the same time.
Ownership
The caller owns q4 and q6.
Thread safety
Exclusive use of sys. Any q call on another handle may run beside it.
Example
seams_q4q6_n(sys, 3.5, 0, q4, n, q6, n);
SEAMS_API seams_status seams_q4q6_n(seams_system *sys, double cutoff, int type, double *q4, size_t q4_len, double *q6, size_t q6_len)
Local q4 and q6 on the cutoff shell into buffers of known length.

◆ seams_rings_histogram_n()

SEAMS_API seams_status seams_rings_histogram_n ( const seams_rings * rings,
int * counts,
size_t counts_len )

Count primitive rings by size into a buffer of known length.

Parameters
ringsRing handle.
countsCaller buffer. counts[k] receives the number of rings of size k. Sizes outside the buffer are ignored.
counts_lenLength of counts. Must be positive.
Returns
SEAMS_OK, or SEAMS_ERR_NULL, SEAMS_ERR_RANGE when counts_len is 0.
Ownership
The caller owns counts.
Thread safety
Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings.
Example
int hist[13];
seams_rings_histogram_n(rings, hist, 13);
SEAMS_API seams_status seams_rings_histogram_n(const seams_rings *rings, int *counts, size_t counts_len)
Count primitive rings by size into a buffer of known length.

◆ seams_rings_labels_n()

SEAMS_API seams_status seams_rings_labels_n ( const seams_rings * rings,
int * sizes,
size_t sizes_len,
int * symmetry,
size_t symmetry_len )

Size and symmetry of each ring into buffers of known length.

Parameters
ringsRing handle.
sizesOne int per ring, or NULL.
sizes_lenLength of sizes. Ignored when sizes is NULL.
symmetryOne seams_ring_symmetry code per ring, or NULL. The two pointers may not both be NULL.
symmetry_lenLength of symmetry. Ignored when symmetry is NULL.
Returns
SEAMS_OK, or SEAMS_ERR_NULL, SEAMS_ERR_RANGE when a buffer is shorter than the ring count, SEAMS_ERR_NOMEM, SEAMS_ERR_INTERNAL.
Ownership
The caller owns both arrays.
Thread safety
Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings.
Example
size_t nr = 0;
seams_rings_nrings(rings, &nr);
int *sym = malloc(nr * sizeof *sym);
seams_rings_labels_n(rings, NULL, 0, sym, nr);
free(sym);
SEAMS_API seams_status seams_rings_labels_n(const seams_rings *rings, int *sizes, size_t sizes_len, int *symmetry, size_t symmetry_len)
Size and symmetry of each ring into buffers of known length.
SEAMS_API seams_status seams_rings_nrings(const seams_rings *rings, size_t *n)
Number of primitive rings.

◆ seams_rings_nrings()

SEAMS_API seams_status seams_rings_nrings ( const seams_rings * rings,
size_t * n )

Number of primitive rings.

Parameters
ringsRing handle.
nReceives the ring count.
Returns
SEAMS_OK, or SEAMS_ERR_NULL when rings or n is NULL.
Ownership
The caller owns rings; the call borrows it. n is caller storage that the call fills. The library keeps no pointer to any argument.
Thread safety
Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings.
Example
size_t nr = 0;
seams_rings_nrings(rings, &nr);

◆ seams_system_natoms()

SEAMS_API seams_status seams_system_natoms ( const seams_system * sys,
size_t * n )

Number of points in the frame.

Parameters
sysFrame handle.
nReceives the atom count.
Returns
SEAMS_OK, SEAMS_ERR_NULL when sys or n is NULL, or SEAMS_ERR_STATE when sys holds no frame. *n is unchanged on failure.
Ownership
The caller owns sys; the call borrows it. n is caller storage that the call fills. The library keeps no pointer to any argument.
Thread safety
Read-only: may run alongside other const calls on sys, and not alongside a non-const call on sys.
Example
size_t n = 0;
if (seams_system_natoms(sys, &n) == SEAMS_OK) {
labels = malloc(n * sizeof *labels);
free(labels);
}
@ SEAMS_OK
The call succeeded.
Definition seams.h:154