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

d-SEAMS stable C API, ABI 1. More...

#include "seams_version.h"
#include <stddef.h>

Go to the source code of this file.

Macros

#define SEAMS_ABI   1
 ABI generation of this header.
#define SEAMS_API
 Marks a symbol exported by libseams.
#define SEAMS_DEPRECATED(msg)
 Marks an entry point kept for ABI 1 callers.

Typedefs

typedef enum seams_status seams_status
 Status codes.
typedef enum seams_label seams_label
 CHILL and CHILL+ atom labels.
typedef enum seams_ring_symmetry seams_ring_symmetry
 Ring topology.
typedef enum seams_chill_rule seams_chill_rule
 CHILL+ definition.
typedef enum seams_graph seams_graph
 Neighbour graph.
typedef enum seams_cage_label seams_cage_label
 Per-atom cage membership from the hexagonal and double-diamond search.
typedef enum seams_site_kind seams_site_kind
 Site kind.
typedef struct seams_system seams_system
 One frame.
typedef struct seams_neighbours seams_neighbours
 One neighbour list.
typedef struct seams_rings seams_rings
 One primitive-ring set.
typedef struct seams_cage_set seams_cage_set
 Hexagonal and double-diamond membership.
typedef struct seams_brine seams_brine
 One planar ice/brine front measurement.
typedef struct seams_topo seams_topo
 Topological fingerprint of one bonded frame.

Enumerations

enum  seams_status {
  SEAMS_OK = 0 , SEAMS_ERR_NULL = 1 , SEAMS_ERR_RANGE = 2 , SEAMS_ERR_BOX = 3 ,
  SEAMS_ERR_ARG = 4 , SEAMS_ERR_STATE = 5 , SEAMS_ERR_NOMEM = 6 , SEAMS_ERR_INTERNAL = 7
}
 Status codes. More...
enum  seams_label {
  SEAMS_LABEL_CUBIC = 0 , SEAMS_LABEL_HEXAGONAL = 1 , SEAMS_LABEL_WATER = 2 , SEAMS_LABEL_INTERFACIAL = 3 ,
  SEAMS_LABEL_CLATHRATE = 4 , SEAMS_LABEL_INTERCLATHRATE = 5 , SEAMS_LABEL_UNCLASSIFIED = 6 , SEAMS_LABEL_RECUBIC = 7 ,
  SEAMS_LABEL_REHEX = 8
}
 CHILL and CHILL+ atom labels. More...
enum  seams_ring_symmetry {
  SEAMS_RING_UNCLASSIFIED = 0 , SEAMS_RING_DDC = 1 , SEAMS_RING_HC_BASAL = 2 , SEAMS_RING_HC_PRISMATIC = 3 ,
  SEAMS_RING_BOTH_BASAL = 4 , SEAMS_RING_BOTH_PRISMATIC = 5 , SEAMS_RING_PRISM = 6 , SEAMS_RING_DEFORMED_PRISM = 7 ,
  SEAMS_RING_MIXED_PRISM = 8 , SEAMS_RING_PENTAGON = 9 , SEAMS_RING_HEXAGON = 10 , SEAMS_RING_OTHER = 11
}
 Ring topology. More...
enum  seams_chill_rule { SEAMS_CHILL_PUBLISHED = 0 , SEAMS_CHILL_OVITO = 1 }
 CHILL+ definition. More...
enum  seams_graph { SEAMS_GRAPH_CUTOFF = 0 , SEAMS_GRAPH_MUTUAL = 1 , SEAMS_GRAPH_SEEDED = 2 }
 Neighbour graph. More...
enum  seams_cage_label { SEAMS_CAGE_WATER = 0 , SEAMS_CAGE_HEX = 1 , SEAMS_CAGE_CUBIC = 2 , SEAMS_CAGE_BOTH = 3 }
 Per-atom cage membership from the hexagonal and double-diamond search. More...
enum  seams_site_kind {
  SEAMS_SITE_UNSPECIFIED = 0 , SEAMS_SITE_CATION = 1 , SEAMS_SITE_ANION = 2 , SEAMS_SITE_TAIL = 3 ,
  SEAMS_SITE_DONOR_H = 4 , SEAMS_SITE_ACCEPTOR = 5 , SEAMS_SITE_POLAR = 6 , SEAMS_SITE_APOLAR = 7 ,
  SEAMS_SITE_WATER_O = 8 , SEAMS_SITE_WATER_H = 9 , SEAMS_SITE_SOLVENT = 10
}
 Site kind. More...

Functions

SEAMS_API int seams_abi (void)
 ABI number compiled into this library.
SEAMS_API int seams_version (void)
 Packed release number.
SEAMS_API int seams_version_major (void)
 Major version of the library at run time.
SEAMS_API int seams_version_minor (void)
 Minor version of the library at run time.
SEAMS_API int seams_version_patch (void)
 Patch version of the library at run time.
SEAMS_API const char * seams_version_string (void)
 Version text, for example "2.14.0".
SEAMS_API const char * seams_status_string (seams_status status)
 Short name of a status code.
SEAMS_API const char * seams_last_error (void)
 Thread-local detail of the last failing call on this thread.
SEAMS_API const char * seams_handle_error (const void *handle)
 Detail string stored on a handle.
SEAMS_API const char * seams_label_name (int label)
 Name of a CHILL label.
SEAMS_API const char * seams_ring_symmetry_name (int symmetry)
 Name of a ring-symmetry code.
SEAMS_API seams_status seams_set_num_threads (int n)
 Set the OpenMP team used by later analysis calls.
SEAMS_API int seams_get_num_threads (void)
 Team width the next analysis call will request.
SEAMS_API seams_system * seams_system_create (void)
 Allocate an empty frame.
SEAMS_API void seams_system_destroy (seams_system *sys)
 Free a frame.
SEAMS_API seams_status seams_system_set_atoms (seams_system *sys, const double *xyz, size_t n, const double *box9, size_t box_len, const int *types, const int *ids)
 Store points and a general cell.
SEAMS_API seams_status seams_system_set_frame (seams_system *sys, const double *xyz, int n, const double *box9, const int *types, const int *ids)
 Store points and a general LAMMPS cell, with an int count.
SEAMS_API seams_status seams_system_set_ortho (seams_system *sys, const double *xyz, int n, double ox, double oy, double oz, double lx, double ly, double lz, const int *types, const int *ids)
 Store points and an orthorhombic cell.
SEAMS_API seams_status seams_system_read (seams_system *sys, const char *path, int frame, int type_filter)
 Read one frame from a trajectory file.
SEAMS_API seams_status seams_path_nframes (const char *path, size_t *nframes)
 Number of frames in a trajectory path.
SEAMS_API int seams_system_count (const seams_system *sys)
 Number of points in the frame, as an int.
SEAMS_API seams_status seams_neighbours_build (seams_system *sys, double cutoff, int type, int graph, seams_neighbours **out)
 Build a cutoff or mutual neighbour list.
SEAMS_API void seams_neighbours_destroy (seams_neighbours *nb)
 Free a neighbour list.
SEAMS_API int seams_neighbours_count (const seams_neighbours *nb)
 Number of neighbour rows, as an int.
SEAMS_API seams_status seams_neighbours_csr (const seams_neighbours *nb, const int **offsets, int *n_offsets, const int **cols, int *nnz)
 Borrow the neighbour list as CSR.
SEAMS_API seams_status seams_neighbours_copy (const seams_neighbours *nb, int *offsets, size_t offsets_cap, size_t *n_offsets, int *cols, size_t cols_cap, size_t *nnz)
 Copy the neighbour CSR into caller buffers.
SEAMS_API seams_status seams_chill (seams_system *sys, double cutoff, int type, int graph, int rule, int *labels, size_t labels_len, int counts9[9])
 Original CHILL labels, published or OVITO edges.
SEAMS_API seams_status seams_chill_plus (seams_system *sys, double cutoff, int type, int graph, int rule, int *labels, int counts9[9])
 CHILL+ labels, without a buffer length.
SEAMS_API seams_status seams_ql (seams_system *sys, double cutoff, int type, int order_l, int graph, double *ql, size_t ql_len, double *qlbar, size_t qlbar_len)
 Local Steinhardt q_l, and the Lechner-Dellago average on request.
SEAMS_API seams_status seams_q4q6 (seams_system *sys, double cutoff, int type, double *q4, double *q6)
 Local q4 and q6 on the cutoff shell, without buffer lengths.
SEAMS_API seams_status seams_q6bar (seams_system *sys, double cutoff, int type, double ice_cut, double *q6bar, size_t q6bar_len, double *mean, double *median, int *n_ice)
 Lechner-Dellago q6-bar and the ice count above a cut.
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.
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.
SEAMS_API 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.
SEAMS_API void seams_brine_destroy (seams_brine *front)
 Free a brine-front handle.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API seams_status seams_steinhardt (seams_system *sys, double cutoff, int type, int order_l, double *ql, size_t ql_len, double *qlbar, size_t qlbar_len)
 Local Steinhardt q_l on the cutoff shell, and the average on request.
SEAMS_API seams_status seams_neighbours_knn (seams_system *sys, int k, double cutoff, int type, int mutual, seams_neighbours **out)
 k-nearest neighbour list.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API seams_status seams_coordination (seams_system *sys, double rmax, int bins, int type_i, int type_j, double *cn)
 Coordination number integrated to rmax.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API void seams_fingerprint_destroy (seams_topo *fp)
 Free a fingerprint.
SEAMS_API seams_status seams_fingerprint_key (const seams_topo *fp, char *buf, size_t cap, size_t *n_out)
 Frame key text.
SEAMS_API 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.
SEAMS_API seams_status seams_fingerprint_rings (const seams_topo *fp, int *counts, size_t counts_len)
 Primitive-ring census stored on the fingerprint.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API const char * seams_last_error_message (void)
 Thread-local detail of the last failing call on this thread.
SEAMS_API seams_status seams_system_natoms (const seams_system *sys, size_t *n)
 Number of points in the frame.
SEAMS_API seams_status seams_neighbours_nrows (const seams_neighbours *nb, size_t *n)
 Number of neighbour rows.
SEAMS_API seams_status seams_rings_nrings (const seams_rings *rings, size_t *n)
 Number of primitive rings.
SEAMS_API seams_status seams_chill_plus_n (seams_system *sys, double cutoff, int type, int graph, int rule, int *labels, size_t labels_len, int counts9[9])
 CHILL+ labels into a buffer of known length.
SEAMS_API seams_status seams_q4q6_n (seams_system *sys, double cutoff, int type, double *q4, size_t q4_len, double *q6, size_t q6_len)
 Local q4 and q6 on the cutoff shell into buffers of known length.
SEAMS_API 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.
SEAMS_API 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.
SEAMS_API seams_status seams_system_set_positions (seams_system *sys, const double *xyz, size_t n, const double *box9, size_t box_len)
 Overwrite the coordinates, and optionally the cell, of the stored frame.
SEAMS_API seams_status seams_system_stage_positions (seams_system *sys, int enable)
 Trade memory for a single pass in seams_system_set_positions().
SEAMS_API seams_status seams_system_box (const seams_system *sys, double *box9, size_t box_len)
 Copy the stored cell out as nine LAMMPS numbers.
SEAMS_API seams_status seams_system_positions (const seams_system *sys, double *xyz, size_t len)
 Copy the stored coordinates out.
SEAMS_API seams_status seams_system_types (const seams_system *sys, int *types, size_t len)
 Copy the stored atom types out.
SEAMS_API seams_status seams_system_ids (const seams_system *sys, int *ids, size_t len)
 Copy the stored atom ids out.

Detailed Description

d-SEAMS stable C API, ABI 1.

Opaque handles. A frame is n Cartesian points, in Angstrom, and a LAMMPS cell of nine doubles: ox, oy, oz, lx, ly, lz, xy, xz, yz. Lengths are the edge lengths. A zero tilt is orthorhombic.

Status and errors
Every call that can fail returns a seams_status. Zero is success. A failing call stores a detail string for seams_last_error_message() and, when the call had a handle, for seams_handle_error(). The library never aborts or exits the process, and no C++ exception crosses this boundary: every one is caught and mapped to a status. The only functions that do not return a status are the pure metadata queries (version, names), the destroy functions, and the legacy int count queries kept for ABI 1 callers.
Handles and ownership
Every handle comes from a create, build, find, or analyse call and is released by the matching destroy function. Each destroy function accepts NULL and ignores it. A second destroy of the same pointer is detected, records "double destroy", and frees nothing. A handle built from a frame holds its own copy, so the frame may be destroyed first. The library never returns a buffer the caller must free: outputs are written into caller buffers, and the strings it returns are static or owned by the library.
Buffers
Lengths are size_t. A NULL output buffer with a non-NULL length pointer queries the required count and returns SEAMS_OK. A short non-NULL buffer returns SEAMS_ERR_RANGE and writes nothing into that buffer. The length pointer still receives the required count.
Const correctness
Input arrays are const. A function that takes a const handle is a read-only accessor: on success it writes nothing to the handle, and on failure it writes only the handle's error slot, under a lock. The frame accessors seams_system_count(), seams_system_natoms(), seams_system_box(), seams_system_positions(), seams_system_types() and seams_system_ids(), and every query on a neighbour, ring, cage, brine, or fingerprint handle, are of this kind. A function that takes a non-const seams_system says why in its "Handle access" paragraph. There are three reasons. A load replaces the frame. seams_chill(), seams_chill_plus() and seams_chill_plus_n() write their labels into the frame. Every other analysis clears the handle's error slot on entry, so seams_handle_error() reports that call and no earlier one; that is the only handle state those calls write. None of them changes the stored coordinates, cell, types, or ids.
Thread safety
Distinct handles may be used from distinct threads at the same time. Const-handle calls on one handle may run on several threads at once, provided no call taking that handle non-const runs at the same time. Two non-const calls on one handle must not overlap. When threads share a handle, read failures with seams_last_error_message(), which is thread-local; the handle's slot holds whichever failure landed last. seams_set_num_threads() is process-global.
ABI policy
SEAMS_ABI stays 1 while every shipped function keeps its signature and every shipped enumerator keeps its numeric value. New functions and new enumerators are appended. No public struct carries fields. A later struct, if one is added, starts with a uint32_t size set by the caller to the size of the struct the caller compiled, and the library reads only the prefix that size covers. Only symbols marked SEAMS_API are exported; the library is built with hidden visibility.
Example
#include <seams.h>
#include <stdio.h>
int classify(const double *xyz, size_t n, const double box9[9], int *labels) {
seams_status rc = sys == NULL ? SEAMS_ERR_NOMEM
: seams_system_set_atoms(sys, xyz, n, box9, 9, NULL, NULL);
if (rc == SEAMS_OK) {
labels, n, NULL);
}
if (rc != SEAMS_OK) {
fprintf(stderr, "%s: %s\n", seams_status_string(rc), seams_last_error_message());
}
return (int)rc;
}
SEAMS_API seams_status seams_system_set_atoms(seams_system *sys, const double *xyz, size_t n, const double *box9, size_t box_len, const int *types, const int *ids)
Store points and a general cell.
SEAMS_API seams_system * seams_system_create(void)
Allocate an empty frame.
SEAMS_API void seams_system_destroy(seams_system *sys)
Free a frame.
SEAMS_API const char * seams_status_string(seams_status status)
Short name of a status code.
SEAMS_API seams_status seams_chill_plus_n(seams_system *sys, double cutoff, int type, int graph, int rule, int *labels, size_t labels_len, int counts9[9])
CHILL+ labels into a buffer of known length.
SEAMS_API const char * seams_last_error_message(void)
Thread-local detail of the last failing call on this thread.
seams_status
Status codes.
Definition seams.h:153
struct seams_system seams_system
One frame.
Definition seams.h:241
@ SEAMS_CHILL_PUBLISHED
Nguyen and Molinero, four closest neighbours.
Definition seams.h:202
@ SEAMS_ERR_NOMEM
An allocation failed.
Definition seams.h:160
@ SEAMS_OK
The call succeeded.
Definition seams.h:154
@ SEAMS_GRAPH_CUTOFF
Every neighbour inside the cutoff.
Definition seams.h:208
d-SEAMS stable C API, ABI 1.

The version macros live in seams_version.h, which this header includes: SEAMS_VERSION_MAJOR, SEAMS_VERSION_MINOR, SEAMS_VERSION_PATCH, SEAMS_VERSION_STRING, SEAMS_VERSION_NUMBER.

SPDX-License-Identifier: MIT Copyright (c) d-SEAMS developers

Definition in file seams.h.

Macro Definition Documentation

◆ SEAMS_ABI

#define SEAMS_ABI   1

ABI generation of this header.

Bumped only on a breaking change.

Definition at line 102 of file seams.h.

◆ SEAMS_API

#define SEAMS_API

Marks a symbol exported by libseams.

The library is compiled with hidden visibility and SEAMS_BUILDING defined, so only declarations carrying this macro are exported. Windows consumers get dllimport. Define SEAMS_STATIC when linking a static archive.

Definition at line 131 of file seams.h.

◆ SEAMS_DEPRECATED

#define SEAMS_DEPRECATED ( msg)

Marks an entry point kept for ABI 1 callers.

msg names the replacement.

Definition at line 143 of file seams.h.