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

Primitive rings (Franzblau) and their labels. More...

Functions

SEAMS_API 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.
SEAMS_API void seams_rings_destroy (seams_rings *rings)
 Free a ring set.
SEAMS_API int seams_rings_count (const seams_rings *rings)
 Number of primitive rings, as an int.
SEAMS_API seams_status seams_rings_histogram (const seams_rings *rings, int *counts, int counts_len)
 Count primitive rings by size, with an int length.
SEAMS_API seams_status seams_rings_labels (const seams_rings *rings, int *sizes, int *symmetry)
 Size and symmetry of each ring, without buffer lengths.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API seams_status seams_rings_fraction (const seams_rings *rings, int size, double *fraction)
 Fraction of atoms that sit on a ring.

Detailed Description

Primitive rings (Franzblau) and their labels.

Function Documentation

◆ seams_rings_chordless()

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

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.

Parameters
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.
Ownership
The caller owns rings and per_atom. Indices are positions in the frame.
Thread safety
Exclusive use of nb.
Example
size_t n_six = 0;
seams_rings_chordless(nb, 6, NULL, 0, &n_six, NULL, 0);
SEAMS_API 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.

◆ seams_rings_count()

SEAMS_API int seams_rings_count ( const seams_rings * rings)

Number of primitive rings, as an int.

ABI 1 query. seams_rings_nrings() reports errors.

Parameters
ringsRing handle, or NULL.
Returns
The ring count, or 0 when rings is NULL.
Ownership
The caller owns rings; the call borrows it. 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
int nr = seams_rings_count(rings);
SEAMS_API int seams_rings_count(const seams_rings *rings)
Number of primitive rings, as an int.

◆ seams_rings_destroy()

SEAMS_API void seams_rings_destroy ( seams_rings * rings)

Free a ring set.

Parameters
ringsHandle from seams_rings_find(), or NULL. NULL is ignored.
Ownership
Releases the handle and every ring it holds.
Thread safety
The caller must not use rings after this returns.
Example
SEAMS_API void seams_rings_destroy(seams_rings *rings)
Free a ring set.

◆ seams_rings_find()

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

Parameters
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
graphSEAMS_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.
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_rings_destroy().
Thread safety
Exclusive use of sys.
Example
seams_rings *rings = NULL;
if (seams_rings_find(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, 6, &rings) == SEAMS_OK) {
}
SEAMS_API 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.
struct seams_rings seams_rings
One primitive-ring set.
Definition seams.h:245
@ SEAMS_OK
The call succeeded.
Definition seams.h:154
@ SEAMS_GRAPH_CUTOFF
Every neighbour inside the cutoff.
Definition seams.h:208

◆ seams_rings_fraction()

SEAMS_API seams_status seams_rings_fraction ( const seams_rings * rings,
int size,
double * fraction )

Fraction of atoms that sit on a ring.

Parameters
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.
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.
Thread safety
Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings.
Example
double f6 = 0;
seams_rings_fraction(rings, 6, &f6);
SEAMS_API seams_status seams_rings_fraction(const seams_rings *rings, int size, double *fraction)
Fraction of atoms that sit on a ring.

◆ seams_rings_histogram()

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

Count primitive rings by size, with an int length.

ABI 1 entry. New callers use seams_rings_histogram_n().

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.
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(rings, hist, 13);
SEAMS_API seams_status seams_rings_histogram(const seams_rings *rings, int *counts, int counts_len)
Count primitive rings by size, with an int length.

◆ seams_rings_labels()

SEAMS_API seams_status seams_rings_labels ( const seams_rings * rings,
int * sizes,
int * symmetry )

Size and symmetry of each ring, without buffer lengths.

ABI 1 entry. Each non-NULL buffer has length seams_rings_count(rings). New callers use seams_rings_labels_n(), which checks the lengths.

Parameters
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.
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. The first symmetry request fills a cache on the handle under a lock; later requests only read it.
Example
seams_rings_labels(rings, sizes, symmetry);
SEAMS_API seams_status seams_rings_labels(const seams_rings *rings, int *sizes, int *symmetry)
Size and symmetry of each ring, without buffer lengths.

◆ seams_rings_vertices()

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

Parameters
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.
Ownership
The caller owns atoms. Indices are positions in the frame.
Thread safety
Read-only: may run alongside other const calls on rings, and not alongside a non-const call on rings.
Example
int atoms[12];
size_t len = 0;
seams_rings_vertices(rings, 0, atoms, 12, &len);
SEAMS_API 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.