seams-core v2.14.0
libyodaLib, the C++ engine of d-SEAMS
Loading...
Searching...
No Matches
Cages and ice shells

Hexagonal and double-diamond cages, signatures, and shell labels. More...

Functions

SEAMS_API seams_status seams_cages_find (seams_system *sys, double cutoff, int type, int graph, int k, int complete, seams_cage_set **out)
 Hexagonal and double-diamond cage membership.
SEAMS_API void seams_cages_destroy (seams_cage_set *cages)
 Free a cage-membership handle.
SEAMS_API seams_status seams_cages_counts (const seams_cage_set *cages, int *n_hex, int *n_cubic, int *n_water, int *n_both)
 Disjoint cage population counts.
SEAMS_API seams_status seams_cages_labels (const seams_cage_set *cages, int *per_atom, size_t len)
 Per-atom cage code.
SEAMS_API seams_status seams_cages_signature (seams_system *sys, double cutoff, int type, int graph, const char *spec, size_t *n_cages, size_t *n_atoms)
 Count closed cages whose ring census matches a signature.
SEAMS_API seams_status seams_system_symmetry (seams_system *sys, double shell_rmsd, int *labels, size_t labels_len)
 Per-atom ice shell label.

Detailed Description

Hexagonal and double-diamond cages, signatures, and shell labels.

Function Documentation

◆ seams_cages_counts()

SEAMS_API seams_status seams_cages_counts ( const seams_cage_set * cages,
int * n_hex,
int * n_cubic,
int * n_water,
int * n_both )

Disjoint cage population counts.

The four counts sum to the number of atoms the search kept.

Parameters
cagesCage handle.
n_hexHexagonal only, or NULL.
n_cubicDouble-diamond only, or NULL.
n_waterNeither cage, or NULL.
n_bothBoth cages, or NULL.
Returns
SEAMS_OK, or SEAMS_ERR_NULL when cages is NULL or every count pointer is NULL.
Ownership
The caller owns cages; the call borrows it. n_hex, n_cubic, n_water and n_both are 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 cages, and not alongside a non-const call on cages.
Example
int hex = 0, cubic = 0;
seams_cages_counts(cages, &hex, &cubic, NULL, NULL);
SEAMS_API seams_status seams_cages_counts(const seams_cage_set *cages, int *n_hex, int *n_cubic, int *n_water, int *n_both)
Disjoint cage population counts.

◆ seams_cages_destroy()

SEAMS_API void seams_cages_destroy ( seams_cage_set * cages)

Free a cage-membership handle.

Parameters
cagesHandle from seams_cages_find() or seams_cages(), or NULL. NULL is ignored.
Ownership
Releases the handle and its per-atom labels.
Thread safety
The caller must not use cages after this returns.
Example
SEAMS_API void seams_cages_destroy(seams_cage_set *cages)
Free a cage-membership handle.

◆ seams_cages_find()

SEAMS_API seams_status seams_cages_find ( seams_system * sys,
double cutoff,
int type,
int graph,
int k,
int complete,
seams_cage_set ** out )

Hexagonal and double-diamond cage membership.

Parameters
sysFrame handle.
cutoffPositive finite cutoff, Angstrom. The seeded graph uses cutoff + 1.5 as the candidate shell.
typeSpecies filter.
graphSEAMS_GRAPH_CUTOFF, SEAMS_GRAPH_MUTUAL, or SEAMS_GRAPH_SEEDED.
kNeighbour count for the seeded graph. Zero selects 4.
completeNon-zero runs ring-adjacent completion on the seeded labels. Ignored for the cutoff and mutual graphs.
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_cages_destroy().
Thread safety
Exclusive use of sys.
Example
seams_cage_set *cages = NULL;
if (seams_cages_find(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, 0, 0, &cages) == SEAMS_OK) {
}
SEAMS_API seams_status seams_cages_find(seams_system *sys, double cutoff, int type, int graph, int k, int complete, seams_cage_set **out)
Hexagonal and double-diamond cage membership.
struct seams_cage_set seams_cage_set
Hexagonal and double-diamond membership.
Definition seams.h:247
@ SEAMS_OK
The call succeeded.
Definition seams.h:154
@ SEAMS_GRAPH_CUTOFF
Every neighbour inside the cutoff.
Definition seams.h:208

◆ seams_cages_labels()

SEAMS_API seams_status seams_cages_labels ( const seams_cage_set * cages,
int * per_atom,
size_t len )

Per-atom cage code.

Parameters
cagesCage handle.
per_atomCaller buffer of seams_cage_label values, one per atom in the frame. Atoms the species filter dropped are SEAMS_CAGE_WATER.
lenLength of per_atom. Must be at least the frame count stored on the handle.
Returns
SEAMS_OK, or SEAMS_ERR_NULL, SEAMS_ERR_RANGE.
Ownership
The caller owns per_atom.
Thread safety
Read-only: may run alongside other const calls on cages, and not alongside a non-const call on cages.
Example
seams_cages_labels(cages, per_atom, n);
SEAMS_API seams_status seams_cages_labels(const seams_cage_set *cages, int *per_atom, size_t len)
Per-atom cage code.

◆ seams_cages_signature()

SEAMS_API seams_status seams_cages_signature ( seams_system * sys,
double cutoff,
int type,
int graph,
const char * spec,
size_t * n_cages,
size_t * n_atoms )

Count closed cages whose ring census matches a signature.

spec is a census such as "512", "51262", or "51264", or the names "hc" and "ddc". n_cages is the number of closed cages. n_atoms is the number of distinct vertices in those cages.

Parameters
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
graphSEAMS_GRAPH_CUTOFF or SEAMS_GRAPH_MUTUAL.
specSignature text. Must be non-NULL.
n_cagesReceives the cage count.
n_atomsReceives the vertex count.
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 owns sys; the call borrows it. spec is read during the call only. n_cages and n_atoms are caller storage that the call fills. The library keeps no pointer to any argument.
Thread safety
Exclusive use of sys.
Example
size_t n_cages = 0, n_atoms = 0;
seams_cages_signature(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, "512", &n_cages, &n_atoms);
SEAMS_API seams_status seams_cages_signature(seams_system *sys, double cutoff, int type, int graph, const char *spec, size_t *n_cages, size_t *n_atoms)
Count closed cages whose ring census matches a signature.

◆ seams_system_symmetry()

SEAMS_API seams_status seams_system_symmetry ( seams_system * sys,
double shell_rmsd,
int * labels,
size_t labels_len )

Per-atom ice shell label.

labels[i] is 0 for ice Ih, 1 for ice Ic, 2 for stacking disorder, or -1 when the shell does not match. A non-positive shell_rmsd selects the library ceiling (the scale-free second-shell residual, 0.15).

Parameters
sysFrame handle.
shell_rmsdPositive scale-free residual ceiling, or a non-positive value for the library ceiling.
labelsCaller buffer.
labels_lenMust be at least the frame count.
Returns
SEAMS_OK, or SEAMS_ERR_NULL, SEAMS_ERR_STATE, SEAMS_ERR_RANGE, SEAMS_ERR_INTERNAL, SEAMS_ERR_NOMEM.
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 owns labels.
Thread safety
Exclusive use of sys.
Example
seams_system_symmetry(sys, 0.0, labels, n);
SEAMS_API seams_status seams_system_symmetry(seams_system *sys, double shell_rmsd, int *labels, size_t labels_len)
Per-atom ice shell label.