Rings¶
Primitive rings and their histogram.
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
/* Ice Ih has 256 primitive six-rings at 3.5 angstroms. */
#include "seams.h"
#include <stdio.h>
#include <stdlib.h>
int main(void) {
seams_system *sys = seams_system_create();
seams_rings *rings = NULL;
int hist[13] = {0};
int sized[13] = {0};
size_t nrings = 0;
if (seams_system_read(sys, "input/traj/ice1h.lammpstrj", 1, -1) != SEAMS_OK) {
return 1;
}
if (seams_rings_find(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, 6, &rings) != SEAMS_OK ||
seams_rings_histogram(rings, hist, 13) != SEAMS_OK) {
fprintf(stderr, "%s\n", seams_last_error());
return 1;
}
if (seams_rings_nrings(rings, &nrings) != SEAMS_OK || nrings != 256 ||
seams_rings_histogram_n(rings, sized, 13) != SEAMS_OK || sized[6] != 256) {
fprintf(stderr, "nrings %zu hist6 %d\n", nrings, sized[6]);
return 1;
}
int *sizes = calloc(nrings, sizeof(int));
int *symmetry = calloc(nrings, sizeof(int));
if (sizes == NULL || symmetry == NULL) {
return 1;
}
if (seams_rings_labels_n(rings, sizes, nrings, symmetry, nrings) != SEAMS_OK) {
fprintf(stderr, "%s\n", seams_last_error_message());
return 1;
}
int basal = 0;
int prismatic = 0;
int hexagon = 0;
for (size_t i = 0; i < nrings; ++i) {
if (sizes[i] != 6) {
fprintf(stderr, "ring %zu size %d\n", i, sizes[i]);
return 1;
}
if (symmetry[i] == SEAMS_RING_HC_BASAL) {
++basal;
} else if (symmetry[i] == SEAMS_RING_HC_PRISMATIC) {
++prismatic;
} else if (symmetry[i] == SEAMS_RING_HEXAGON) {
++hexagon;
} else {
fprintf(stderr, "ring %zu symmetry %d\n", i, symmetry[i]);
return 1;
}
}
if (basal != 64 || prismatic != 141 || hexagon != 51) {
fprintf(stderr, "symmetry %d %d %d\n", basal, prismatic, hexagon);
return 1;
}
printf("rings6 %d\n", hist[6]);
free(sizes);
free(symmetry);
seams_rings_destroy(rings);
seams_system_destroy(sys);
return hist[6] == 256 ? 0 : 1;
}
seams_ring_symmetry_name¶
const char *seams_ring_symmetry_name(int symmetry)
Name of a ring-symmetry code.
symmetryA ::seams_ring_symmetry value.
Returns: Static string. Unknown codes return “unknown”.
@par Ownership The caller does not free it. @par Thread safety Pure. @par Example @code printf(“%s\n”, seams_ring_symmetry_name(SEAMS_RING_DDC)); @endcode
seams_rings_find¶
seams_status seams_rings_find(seams_system *sys, double cutoff, int type, int graph, int max_depth, seams_rings **out)
Primitive rings (Franzblau) up to a maximum size.
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
graph::SEAMS_GRAPH_CUTOFF or ::SEAMS_GRAPH_MUTUAL.
max_depthLargest ring size, from 3 through 12.
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.
@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_rings_destroy(). @par Thread safety Exclusive use of sys. @par Example @code seams_rings *rings = NULL; if (seams_rings_find(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, 6, &rings) == SEAMS_OK) { seams_rings_destroy(rings); } @endcode
seams_rings_destroy¶
void seams_rings_destroy(seams_rings *rings)
Free a ring set.
ringsHandle from seams_rings_find(), or NULL. NULL is ignored.
@par Ownership Releases the handle and every ring it holds. @par Thread safety The caller must not use rings after this returns. @par Example @code seams_rings_destroy(rings); @endcode
seams_rings_count¶
int seams_rings_count(const seams_rings *rings)
Number of primitive rings, as an int.
ringsRing handle, or NULL.
Returns: The ring count, or 0 when rings is NULL.
ABI 1 query. seams_rings_nrings() reports errors.
@par Ownership The caller owns rings; the call borrows it. The library keeps no pointer to any argument. @par Thread safety Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings. @par Example @code int nr = seams_rings_count(rings); @endcode
seams_rings_histogram¶
seams_status seams_rings_histogram(const seams_rings *rings, int *counts, int counts_len)
Count primitive rings by size, with an int length.
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.
ABI 1 entry. New callers use seams_rings_histogram_n().
@par Ownership The caller owns counts. @par Thread safety Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings. @par Example @code int hist[13]; seams_rings_histogram(rings, hist, 13); @endcode
seams_rings_labels¶
seams_status seams_rings_labels(const seams_rings *rings, int *sizes, int *symmetry)
Size and symmetry of each ring, without buffer lengths.
ringsRing handle.
sizesOne int per ring, or NULL.
symmetryOne ::seams_ring_symmetry code per ring, or NULL. The two pointers may not both be NULL.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_NOMEM, ::SEAMS_ERR_INTERNAL.
ABI 1 entry. Each non-NULL buffer has length seams_rings_count(rings). New callers use seams_rings_labels_n(), which checks the lengths.
@par Ownership The caller owns both arrays. @par Thread safety Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings. The first symmetry request fills a cache on the handle under a lock; later requests only read it. @par Example @code seams_rings_labels(rings, sizes, symmetry); @endcode
seams_rings_vertices¶
seams_status seams_rings_vertices(const seams_rings *rings, int index, int *atoms, size_t cap, size_t *n_out)
Atom indices of one ring.
ringsRing handle.
indexRing index, from 0 to seams_rings_count(rings) - 1.
atomsCaller buffer, or NULL to query.
capCapacity of atoms. Ignored when atoms is NULL.
n_outReceives the vertex count.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_RANGE.
@par Ownership The caller owns atoms. Indices are positions in the frame. @par Thread safety Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings. @par Example @code int atoms[12]; size_t len = 0; seams_rings_vertices(rings, 0, atoms, 12, &len); @endcode
seams_rings_chordless¶
seams_status seams_rings_chordless(const seams_neighbours *nb, int size, int *rings, size_t rings_len, size_t *n_rings, int *per_atom, size_t per_atom_len)
Chordless cycles of one size.
nbGraph from seams_neighbours_build().
sizeCycle length, from 3 through 12.
ringsCaller buffer of size times the cycle count ints, or NULL to skip the list.
rings_lenLength of rings in ints. Ignored when rings is NULL.
n_ringsReceives the cycle count. Required when rings is not NULL.
per_atomCaller buffer of one int per atom, or NULL. Receives the number of cycles through each atom.
per_atom_lenLength of per_atom. Ignored when per_atom is NULL.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_RANGE, ::SEAMS_ERR_NOMEM, ::SEAMS_ERR_INTERNAL. rings, n_rings and per_atom may not all be NULL. A short rings buffer returns ::SEAMS_ERR_RANGE after n_rings and per_atom are written.
A cycle is chordless when no edge of the graph joins two of its vertices that are not next to each other on the cycle. Every primitive ring is chordless; a chordless cycle need not be primitive. Each cycle is written once as size atom indices: it starts at its lowest index and runs towards the smaller of that atom’s two cycle neighbours. Cycles are sorted lexicographically, so the list does not depend on the thread count. @par Ownership The caller owns rings and per_atom. Indices are positions in the frame. @par Thread safety Exclusive use of nb. @par Example @code size_t n_six = 0; seams_rings_chordless(nb, 6, NULL, 0, &n_six, NULL, 0); @endcode
seams_rings_fraction¶
seams_status seams_rings_fraction(const seams_rings *rings, int size, double *fraction)
Fraction of atoms that sit on a ring.
ringsRing handle.
sizeRing size to count. Zero counts atoms that sit on any ring.
fractionReceives a value in [0, 1].
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_NOMEM.
@par Ownership The caller owns rings; the call borrows it. fraction 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 rings, and not alongside a non-const call on rings. @par Example @code double f6 = 0; seams_rings_fraction(rings, 6, &f6); @endcode
seams_rings_nrings¶
seams_status seams_rings_nrings(const seams_rings *rings, size_t *n)
Number of primitive rings.
ringsRing handle.
nReceives the ring count.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL when rings or n is NULL.
@par 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. @par Thread safety Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings. @par Example @code size_t nr = 0; seams_rings_nrings(rings, &nr); @endcode
seams_rings_labels_n¶
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.
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.
@par Ownership The caller owns both arrays. @par Thread safety Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings. @par Example @code 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); @endcode
seams_rings_histogram_n¶
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.
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.
@par Ownership The caller owns counts. @par Thread safety Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings. @par Example @code int hist[13]; seams_rings_histogram_n(rings, hist, 13); @endcode