Cages¶
Hexagonal, cubic, and signature cages.
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
/* Every Ice Ih oxygen is in a hexagonal cage and not a cubic one. */
#include "seams.h"
#include <stdio.h>
int main(void) {
seams_system *sys = seams_system_create();
seams_cage_set *cages = NULL;
int hex = 0;
int cubic = 0;
int water = 0;
int both = 0;
if (seams_system_read(sys, "input/traj/ice1h.lammpstrj", 1, -1) != SEAMS_OK) {
return 1;
}
if (seams_cages(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, 4, 0, &cages) != SEAMS_OK ||
seams_cages_counts(cages, &hex, &cubic, &water, &both) != SEAMS_OK) {
fprintf(stderr, "%s\n", seams_last_error());
return 1;
}
printf("cages %d %d %d %d\n", hex, cubic, water, both);
seams_cages_destroy(cages);
seams_system_destroy(sys);
return hex == 128 && cubic == 0 && water == 0 && both == 0 ? 0 : 1;
}
seams_cages_find¶
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.
sysFrame handle.
cutoffPositive finite cutoff, Angstrom. The seeded graph uses cutoff + 1.5 as the candidate shell.
typeSpecies filter.
graph::SEAMS_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.
@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_cages_destroy(). @par Thread safety Exclusive use of sys. @par Example @code seams_cage_set *cages = NULL; if (seams_cages_find(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, 0, 0, &cages) == SEAMS_OK) { seams_cages_destroy(cages); } @endcode
seams_cages_destroy¶
void seams_cages_destroy(seams_cage_set *cages)
Free a cage-membership handle.
cagesHandle from seams_cages_find() or seams_cages(), or NULL. NULL is ignored.
@par Ownership Releases the handle and its per-atom labels. @par Thread safety The caller must not use cages after this returns. @par Example @code seams_cages_destroy(cages); @endcode
seams_cages_counts¶
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.
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.
The four counts sum to the number of atoms the search kept.
@par 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. @par Thread safety Read-only: may run alongside other const calls on cages, and not alongside a non-const call on cages. @par Example @code int hex = 0, cubic = 0; seams_cages_counts(cages, &hex, &cubic, NULL, NULL); @endcode
seams_cages_labels¶
seams_status seams_cages_labels(const seams_cage_set *cages, int *per_atom, size_t len)
Per-atom cage code.
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.
@par Ownership The caller owns per_atom. @par Thread safety Read-only: may run alongside other const calls on cages, and not alongside a non-const call on cages. @par Example @code seams_cages_labels(cages, per_atom, n); @endcode
seams_cages_signature¶
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.
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
graph::SEAMS_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.
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.
@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 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. @par Thread safety Exclusive use of sys. @par Example @code size_t n_cages = 0, n_atoms = 0; seams_cages_signature(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, “512”, &n_cages, &n_atoms); @endcode
seams_system_symmetry¶
seams_status seams_system_symmetry(seams_system *sys, double shell_rmsd, int *labels, size_t labels_len)
Per-atom ice shell label.
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.
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).
@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 owns labels. @par Thread safety Exclusive use of sys. @par Example @code seams_system_symmetry(sys, 0.0, labels, n); @endcode
seams_cages¶
seams_status seams_cages(seams_system *sys, double cutoff, int type, int graph, int k, int complete, seams_cage_set **out)
Hexagonal and double-diamond cages. Same search as seams_cages_find().
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
graph::SEAMS_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 seeded labels.
outReceives a ::seams_cage_set. On failure *out is NULL.
Returns: Same codes as seams_cages_find().
@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_cages_destroy(). @par Thread safety Exclusive use of sys. @par Example @code seams_cage_set *cages = NULL; seams_cages(sys, 3.5, 0, SEAMS_GRAPH_SEEDED, 4, 1, &cages); seams_cages_destroy(cages); @endcode
seams_signature_cages¶
seams_status seams_signature_cages(seams_system *sys, double cutoff, int type, int graph, const char *spec, size_t *n_cages, size_t *n_atoms)
Closed cages of one ring census. Same search as seams_cages_signature().
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
graph::SEAMS_GRAPH_CUTOFF or ::SEAMS_GRAPH_MUTUAL.
specSignature text such as “512” or “hc”. Must be non-NULL.
n_cagesReceives the cage count.
n_atomsReceives the vertex count.
Returns: Same codes as seams_cages_signature().
@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 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. @par Thread safety Exclusive use of sys. @par Example @code size_t n_cages = 0, n_atoms = 0; seams_signature_cages(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, “hc”, &n_cages, &n_atoms); @endcode
seams_signature_cages_edge¶
seams_status seams_signature_cages_edge(seams_system *sys, double cutoff, int type, int graph, const char *spec, const char *edge, size_t *n_cages, size_t *n_atoms)
Closed cages of one ring census with an explicit face-edge window.
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
graph::SEAMS_GRAPH_CUTOFF or ::SEAMS_GRAPH_MUTUAL.
specSignature text such as “512” or “hc”. Must be non-NULL.
edgeFace-edge window, or NULL. “none” turns the window off.
n_cagesReceives the cage count.
n_atomsReceives the vertex count.
Returns: Same codes as seams_cages_signature().
Same search as seams_signature_cages(). edge NULL or “” keeps the default window 2.65,3.15 in the coordinate units of the file. “none” leaves the cage bound to the face census.
@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 owns sys; the call borrows it. spec and edge are 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. @par Thread safety Exclusive use of sys. @par Example @code size_t n_cages = 0, n_atoms = 0; seams_signature_cages_edge(sys, 3.5, 0, SEAMS_GRAPH_CUTOFF, “512”, “none”, &n_cages, &n_atoms); @endcode
seams_prisms¶
seams_status seams_prisms(seams_system *sys, double cutoff, int type, int *perfect, int *imperfect, size_t len)
Perfect and imperfect prism counts by ring size.
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
perfectCaller buffer. perfect[k] receives the perfect k-prisms.
imperfectCaller buffer. imperfect[k] receives the deformed k-prisms.
lenLength of each buffer. At least 7, so that sizes 3 through 6 are filled.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_STATE, ::SEAMS_ERR_RANGE, ::SEAMS_ERR_NOMEM, ::SEAMS_ERR_INTERNAL.
Rings come from the mutual four-nearest graph inside cutoff + 1.5.
@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 owns both buffers. @par Thread safety Exclusive use of sys. @par Example @code int perfect[7], imperfect[7]; seams_prisms(sys, 3.5, 0, perfect, imperfect, 7); @endcode
seams_monolayer¶
seams_status seams_monolayer(seams_system *sys, double cutoff, int type, int max_depth, double sheet_area, int *counts, size_t counts_len)
Primitive-ring histogram of a monolayer.
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
max_depthLargest ring size, at least 3.
sheet_areaSheet area, square Angstrom. Must be positive.
countscounts[k] is the number of rings of size k.
counts_lenMust be at least max_depth + 1.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_STATE, ::SEAMS_ERR_RANGE, ::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 owns counts. @par Thread safety Exclusive use of sys. @par Example @code int counts[7]; seams_monolayer(sys, 3.5, 0, 6, 900.0, counts, 7); @endcode