Further analyses¶
Brine fronts, topology, and the remaining exports.
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.
seams_brine_analyse¶
seams_status seams_brine_analyse(seams_system *sys, const int *ice, size_t n_ice, int water_type, int ion_type, int n_bins, int axis, seams_brine **out)
Planar ice/brine front from an ice assignment.
sysFrame handle.
icePer-atom ice flags, length n_ice.
n_iceMust equal the frame count.
water_typeSpecies kept as water, or 0.
ion_typeSpecies kept as ions, or 0 for none.
n_binsBin count along axis, or 0 for 20.
axis0, 1, or 2.
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.
ice[i] is non-zero when atom i is ice. water_type 0 keeps every atom whose type is not ion_type. ion_type 0 means the frame has no ions. n_bins 0 selects 20 bins. axis is 0, 1, or 2. The ice fraction cut is 0.5, and the bulk ice and liquid cuts are 0.85 and 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 frees *out with seams_brine_destroy(). @par Thread safety Exclusive use of sys. @par Example @code seams_brine *front = NULL; if (seams_brine_analyse(sys, ice, n, 1, 2, 0, 2, &front) == SEAMS_OK) { seams_brine_destroy(front); } @endcode
seams_brine_destroy¶
void seams_brine_destroy(seams_brine *front)
Free a brine-front handle.
frontHandle from seams_brine_analyse(), or NULL. NULL is ignored.
@par Ownership Releases the handle and its profile. @par Thread safety The caller must not use front after this returns. @par Example @code seams_brine_destroy(front); @endcode
seams_brine_fronts¶
seams_status seams_brine_fronts(const seams_brine *front, double *z_enter, double *z_exit, double *thickness, int *found)
The two planar crossings of the ice slab.
frontBrine handle.
z_enterWhere the ice fraction crosses the cut on entering the ice along the positive axis, or NULL.
z_exitThe crossing on leaving the ice, or NULL.
thicknessIce run along the axis, or NULL.
foundReceives 1 when both crossings exist, otherwise 0, or NULL.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL when front is NULL or every output pointer is NULL.
Lengths are Angstrom, in the frame’s cell.
@par Ownership The caller owns front; the call borrows it. z_enter, z_exit, thickness and found 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 front, and not alongside a non-const call on front. @par Example @code double thick = 0; int found = 0; seams_brine_fronts(front, NULL, NULL, &thick, &found); @endcode
seams_brine_rejection¶
seams_status seams_brine_rejection(const seams_brine *front, double *c_ice, double *c_liquid, double *k, int *defined)
Molal rejection coefficient k = c_ice / c_liquid.
frontBrine handle.
c_iceBulk ice molality, or NULL.
c_liquidBulk liquid molality, or NULL.
kThe ratio, or NULL. Unchanged when the ratio is undefined.
definedReceives 1 when the liquid bulk contains salt or the ice bulk does not, otherwise 0, or NULL.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL when front is NULL or every output pointer is NULL.
Molality is formula units per kilogram of water.
@par Ownership The caller owns front; the call borrows it. c_ice, c_liquid, k and defined 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 front, and not alongside a non-const call on front. @par Example @code double k = 0; int defined = 0; seams_brine_rejection(front, NULL, NULL, &k, &defined); @endcode
seams_brine_profile¶
seams_status seams_brine_profile(const seams_brine *front, double *z_mid, double *molality, double *ice_fraction, size_t cap, size_t *n_out)
Concentration profile along the front axis.
frontBrine handle.
z_midBin centers, or NULL to skip the column.
molalityBin molalities, or NULL to skip the column.
ice_fractionBin ice fractions, or NULL to skip the column.
capCapacity of each non-NULL column.
n_outReceives the bin count.
Returns: ::SEAMS_OK when every non-NULL column was filled, or when every column pointer was NULL and n_out was written. ::SEAMS_ERR_RANGE when a non-NULL column is short. ::SEAMS_ERR_NULL when front or n_out is NULL.
z_mid is Angstrom. molality is mol/kg. ice_fraction is dimensionless.
@par Ownership The caller owns the columns. @par Thread safety Read-only: may run alongside other const calls on front, and not alongside a non-const call on front. @par Example @code size_t bins = 0; seams_brine_profile(front, NULL, NULL, NULL, 0, &bins); @endcode
seams_brine_pockets¶
seams_status seams_brine_pockets(const seams_brine *front, int *n_pockets, int *reservoir_waters)
Brine pockets trapped in the ice, excluding the liquid reservoir.
frontBrine handle.
n_pocketsReceives the pocket count, or NULL.
reservoir_watersReceives the water count of the liquid reservoir, or NULL.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL when front is NULL or both output pointers are NULL.
@par Ownership The caller owns front; the call borrows it. n_pockets and reservoir_waters 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 front, and not alongside a non-const call on front. @par Example @code int pockets = 0; seams_brine_pockets(front, &pockets, NULL); @endcode
seams_rdf¶
seams_status seams_rdf(seams_system *sys, double rmax, int bins, int type_i, int type_j, double *r, double *g, int *count, size_t cap, size_t *n_out, double *volume)
Partial radial distribution.
sysFrame handle.
rmaxPositive finite outer radius, Angstrom.
binsBin count. Zero selects about rmax / 0.1.
type_iFirst species. Zero and negative keep every atom of a single-species frame, or every atom as one species otherwise.
type_jSecond species. Zero and negative reuse the type_i species.
rBin centers, or NULL to query.
gg(r) per bin, or NULL to query.
countPair count per bin, or NULL to query.
capCapacity of each non-NULL column.
n_outReceives the bin count.
volumeReceives the cell volume, or NULL.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_STATE, ::SEAMS_ERR_RANGE, ::SEAMS_ERR_NOMEM, ::SEAMS_ERR_INTERNAL.
r is Angstrom. g is dimensionless. volume is cubic Angstrom.
@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 the columns. @par Thread safety Exclusive use of sys. @par Example @code size_t bins = 0; seams_rdf(sys, 8.0, 80, 0, 0, NULL, NULL, NULL, 0, &bins, NULL); @endcode
seams_running_cn¶
seams_status seams_running_cn(seams_system *sys, double rmax, int bins, int type_i, int type_j, double *r, double *cn, size_t cap, size_t *n_out)
Running coordination number along the partial RDF.
sysFrame handle.
rmaxPositive finite outer radius, Angstrom.
binsBin count. Zero selects about rmax / 0.1.
type_iCentral species, as in seams_rdf().
type_jCounted species, as in seams_rdf().
rBin centers, Angstrom, or NULL to query.
cnRunning coordination number, or NULL to query.
capCapacity of each non-NULL column.
n_outReceives the bin count.
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 the columns. @par Thread safety Exclusive use of sys. @par Example @code double r[80], cn[80]; size_t bins = 0; seams_running_cn(sys, 8.0, 80, 0, 0, r, cn, 80, &bins); @endcode
seams_coordination¶
seams_status seams_coordination(seams_system *sys, double rmax, int bins, int type_i, int type_j, double *cn)
Coordination number integrated to rmax.
sysFrame handle.
rmaxPositive finite outer radius, Angstrom.
binsBin count. Zero selects about rmax / 0.1.
type_iCentral species, as in seams_rdf().
type_jCounted species, as in seams_rdf().
cnReceives the coordination number.
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 sys; the call borrows it. cn is caller storage that the call fills. The library keeps no pointer to any argument. @par Thread safety Exclusive use of sys. @par Example @code double cn = 0; seams_coordination(sys, 3.5, 0, 1, 1, &cn); @endcode
seams_hbonds¶
seams_status seams_hbonds(seams_system *sys, double cutoff, int oxygen_type, int hydrogen_type, double dist_cutoff, double angle_cutoff, int *n_bonds)
Hydrogen-bond count on one frame.
sysFrame handle.
cutoffPositive finite donor-acceptor cutoff, Angstrom.
oxygen_typeHeavy-atom species. Zero keeps every atom that is not hydrogen_type.
hydrogen_typePositive hydrogen species.
dist_cutoffAcceptor-H distance, Angstrom.
angle_cutoffO-O-H angle, degrees.
n_bondsReceives the number of hydrogen bonds.
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 owns sys; the call borrows it. n_bonds is caller storage that the call fills. The library keeps no pointer to any argument. @par Thread safety Exclusive use of sys. @par Example @code int n_bonds = 0; seams_hbonds(sys, 3.5, 1, 2, 2.4, 30.0, &n_bonds); @endcode
seams_density_axis¶
seams_status seams_density_axis(seams_system *sys, int type, int bins, int axis, double *z, double *rho, size_t cap, size_t *n_out)
Number density along one cell axis.
sysFrame handle.
typeSpecies filter. Zero keeps every atom.
binsBin count. Zero selects about one bin per 0.1 Angstrom.
axis0, 1, or 2.
zBin centers, or NULL to query.
rhoDensity per bin, or NULL to query.
capCapacity of each non-NULL column.
n_outReceives the bin count.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_STATE, ::SEAMS_ERR_RANGE, ::SEAMS_ERR_NOMEM, ::SEAMS_ERR_INTERNAL.
z is Angstrom. rho is number density, atoms per cubic Angstrom.
@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 the columns. @par Thread safety Exclusive use of sys. @par Example @code double z[50], rho[50]; size_t bins = 0; seams_density_axis(sys, 0, 50, 2, z, rho, 50, &bins); @endcode
seams_fingerprint¶
seams_status seams_fingerprint(seams_system *sys, double cutoff, int type, int k, int graph, int hops, int color_types, seams_topo **out)
Topological fingerprint of the bonded graph.
sysFrame handle.
cutoffPositive finite cutoff, Angstrom.
typeSpecies filter.
kNeighbour count for the mutual graph. Zero selects 4.
graph::SEAMS_GRAPH_CUTOFF or ::SEAMS_GRAPH_MUTUAL.
hopsNeighbourhood depth. Zero selects 2.
color_typesNon-zero colors vertices by LAMMPS type.
outReceives a ::seams_topo. 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_fingerprint_destroy(). @par Thread safety Exclusive use of sys. @par Example @code seams_topo *fp = NULL; seams_fingerprint(sys, 3.5, 0, 4, SEAMS_GRAPH_CUTOFF, 2, 0, &fp); seams_fingerprint_destroy(fp); @endcode
seams_fingerprint_destroy¶
void seams_fingerprint_destroy(seams_topo *fp)
Free a fingerprint.
fpHandle from seams_fingerprint(), or NULL. NULL is ignored.
@par Ownership Releases the handle and its key strings. @par Thread safety The caller must not use fp after this returns. @par Example @code seams_fingerprint_destroy(fp); @endcode
seams_fingerprint_key¶
seams_status seams_fingerprint_key(const seams_topo *fp, char *buf, size_t cap, size_t *n_out)
Frame key text.
fpFingerprint handle.
bufCaller buffer of cap bytes, or NULL to query.
capCapacity of buf, including the terminating NUL.
n_outReceives the key length without the terminating NUL.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_RANGE when buf is short.
@par Ownership The caller owns buf. The copy is NUL-terminated. @par Thread safety Read-only: may run alongside other const calls on fp, and not alongside a non-const call on fp. @par Example @code size_t len = 0; seams_fingerprint_key(fp, NULL, 0, &len); char *key = malloc(len + 1); seams_fingerprint_key(fp, key, len + 1, &len); free(key); @endcode
seams_fingerprint_atom¶
seams_status seams_fingerprint_atom(const seams_topo *fp, int index, char *buf, size_t cap, size_t *n_out)
Local key of one atom. Same buffer rule as seams_fingerprint_key().
fpFingerprint handle.
indexAtom index in the frame.
bufCaller buffer of cap bytes, or NULL to query.
capCapacity of buf, including the terminating NUL.
n_outReceives the key length without the terminating NUL.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_RANGE for a bad index or a short buffer.
@par Ownership The caller owns buf. @par Thread safety Read-only: may run alongside other const calls on fp, and not alongside a non-const call on fp. @par Example @code char key[256]; size_t len = 0; seams_fingerprint_atom(fp, 0, key, sizeof key, &len); @endcode
seams_fingerprint_rings¶
seams_status seams_fingerprint_rings(const seams_topo *fp, int *counts, size_t counts_len)
Primitive-ring census stored on the fingerprint.
fpFingerprint handle.
countsCaller buffer. counts[k] receives the number of rings of size k. Sizes past the buffer are dropped.
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 fp, and not alongside a non-const call on fp. @par Example @code int census[13]; seams_fingerprint_rings(fp, census, 13); @endcode
seams_contact_pairs¶
seams_status seams_contact_pairs(seams_system *sys, const char *site_spec, size_t *n_pairs, int *n_cation, int *n_anion)
Mutual nearest unlike contacts of a site table.
sysFrame handle.
site_specText such as “1=cationHead,2=anion”. Must be non-NULL.
n_pairsReceives the contact count, or NULL.
n_cationReceives the cation molecule count, or NULL.
n_anionReceives the anion molecule count, or NULL. At least one of the three outputs must be non-NULL.
Returns: ::SEAMS_OK, or ::SEAMS_ERR_NULL, ::SEAMS_ERR_STATE, ::SEAMS_ERR_ARG, ::SEAMS_ERR_NOMEM, ::SEAMS_ERR_INTERNAL.
Cation and anion counts are molecules in the ion cloud.
@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. site_spec is read during the call only. n_pairs, n_cation and n_anion 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 pairs = 0; seams_contact_pairs(sys, “1=cationHead,2=anion”, &pairs, NULL, NULL); @endcode
seams_domains¶
seams_status seams_domains(seams_system *sys, double cutoff, const char *site_spec, int subset, int *n_subset, int *largest, double *percolation)
Largest domain of a polar or apolar site subset.
sysFrame handle.
cutoffPositive finite cluster cutoff, Angstrom.
site_specSite table text. Must be non-NULL.
subset0 is apolar, 1 is polar.
n_subsetReceives the number of sites in the subset, or NULL.
largestReceives the size of the largest domain, or NULL.
percolationReceives the largest domain size over the subset size, or NULL. At least one output must be non-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 owns sys; the call borrows it. site_spec is read during the call only. n_subset, largest and percolation 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 int largest = 0; seams_domains(sys, 5.0, “1=cationHead,2=anion,3=tail”, 0, NULL, &largest, NULL); @endcode
seams_site_table¶
seams_status seams_site_table(seams_system *sys, const char *spec, int *kinds, size_t len)
Per-atom site kind from a site-table spec.
sysFrame handle.
specSite table text such as “1=cationHead,2=anion”. Must be non-NULL.
kindsOne ::seams_site_kind per atom.
lenLength of kinds. Must be at least the frame count.
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 owns kinds. @par Thread safety Exclusive use of sys. @par Example @code seams_site_table(sys, “1=cationHead,2=anion”, kinds, n); @endcode