========= The C API ========= ``include/seams.h`` is ABI 1 of ``libseams``. The header is the contract. Language bindings and engine plugins include it and link ``libseams``. They do not include the C++ headers under ``src/include/internal``. What the first cut already did ------------------------------ The shipped surface had opaque ``seams_system``, ``seams_neighbours``, and ``seams_rings`` handles, create and destroy pairs, ``seams_status`` codes, a thread-local ``seams_last_error``, and ``SEAMS_API`` on every export. ``src/meson.build`` compiles that library with ``-fvisibility=hidden``. ``SEAMS_VERSION_MAJOR``, ``SEAMS_VERSION_MINOR``, ``SEAMS_VERSION_PATCH``, and ``SEAMS_VERSION_STRING`` are written from ``project().version``. The same cut stopped short of the libraries it was measured against. - Lengths on the first functions are ``int``. A frame that fits in that width is the ABI 1 frame. New buffers take ``size_t``, and a count that does not fit is ``SEAMS_ERR_RANGE``. - ``seams_neighbours_csr`` hands back pointers owned by the handle. ``seams_neighbours_copy`` is the caller-owned copy. A null buffer queries the length. The old function remains, marked ``SEAMS_DEPRECATED``, and still returns those pointers until ``seams_neighbours_destroy``. - ``seams_last_error`` is the thread-local string, the same shape as ``git_error_last``. ``seams_handle_error`` is the string stored on the handle, the same shape as ``sqlite3_errmsg``. A failing call writes both. The handle string survives a later call on a different handle. - Every entry that can throw is wrapped. A C caller sees a status code. - No public struct has fields. Enumerators keep their numeric values. New enumerators are appended (``SEAMS_GRAPH_SEEDED`` is 2). A later struct, if one is added, starts with a ``uint32_t`` size set by the caller, and the library reads only that prefix. ``SEAMS_ABI`` stays 1 until a shipped signature changes. - ``seams_version`` returns ``SEAMS_VERSION_NUMBER``, packed as ``(major << 16) | (minor << 8) | patch``. One handle is used by one thread. Distinct handles may run together, except ``seams_ql``, ``seams_q4q6``, and ``seams_q6bar``, which share one process-global harmonic scratch. ``seams_set_num_threads`` is process-global and must not run during an analysis. The OpenMP team is then the width every handle requests. What a caller can run --------------------- .. table:: +--------------------------------------------------------------------+------------------------------------------------------------------+ | call | analysis | +====================================================================+==================================================================+ | ``seams_system_set_atoms`` / ``seams_system_set_frame`` | frame from arrays | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_system_read`` / ``seams_path_nframes`` | XYZ, CON, chemfiles, and triclinic dumps; index 1-based | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_neighbours_build`` | cutoff list or mutual four-nearest list | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_rings_find`` | Franzblau rings, depth 3 to 12 | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_ql`` | local q3, q4, q6 (also 8 and 12) and the Lechner-Dellago average | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_q4q6`` | the ABI 1 pair, cutoff shell, local values | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_q6bar`` | averaged q6, mean, median, and the count above the caller's cut | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_chill`` | original CHILL, published inclusive edges or OVITO open edges | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_chill_plus`` | CHILL+, published table or the OVITO modifier | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_cages`` / ``seams_signature_cages`` | hexagonal, double-diamond, and census cages | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_neighbours_knn`` | k-nearest list, mutual or one-way | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_steinhardt`` | cutoff-shell q\_l and the Lechner-Dellago average | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_rdf`` / ``seams_running_cn`` / ``seams_coordination`` | partial RDF and its integral | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_hbonds`` | hydrogen-bond count | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_density_axis`` | number density along one edge | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_fingerprint`` | topological key of the bonded graph | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_prisms`` / ``seams_monolayer`` | prism stacks and sheet rings | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_site_table`` / ``seams_contact_pairs`` / ``seams_domains`` | site spec, unlike contacts, polar domains | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_system_symmetry`` | per-atom ice Ih, ice Ic, stacking disorder, or no match | +--------------------------------------------------------------------+------------------------------------------------------------------+ | ``seams_brine_analyse`` | planar front, rejection coefficient, profile, pockets | +--------------------------------------------------------------------+------------------------------------------------------------------+ A non-positive shell residual selects the library ceiling (0.15 on this release). The nucleation q6-bar cut used by the quickstart is 0.36. Coordinates and cutoffs are Angstrom. The cell is nine doubles: origin, edge lengths, then xy, xz, yz. OVITO and freud --------------- ``tests/capi_ovito_freud.py`` calls ``libseams`` through ctypes. The frames are ice Ih, ice Ic, sI, the TIP4P/ice liquid of 4096 oxygens, the brine slab, and the nucleation frame. The test exits with an error when ``freud`` or ``ovito`` cannot be imported. Pixi installs the PyPI packages ``freud-analysis`` and ``ovito`` into the default environment, and the ``crosscheck`` feature repeats those two pins. The ``capi-crosscheck`` job is the run that installs that feature. .. table:: +-------------------------------------------+----------------------------------------------+ | quantity | agreement | +===========================================+==============================================+ | cutoff neighbours at 3.5 Å | identical rows on all six frames | +-------------------------------------------+----------------------------------------------+ | undirected k nearest, k = 4 | identical rows on all six frames | +-------------------------------------------+----------------------------------------------+ | q4, q6, and q6-bar against OVITO 3.17.2 | at most 2.1e-15 | +-------------------------------------------+----------------------------------------------+ | q4, q6, and q6-bar against freud 3.6.1 | at most 2.2e-5 | +-------------------------------------------+----------------------------------------------+ | CHILL+ against the OVITO modifier | identical labels on all six frames | +-------------------------------------------+----------------------------------------------+ | ice Ih and ice Ic against PTM | identical hexagonal and cubic diamond labels | +-------------------------------------------+----------------------------------------------+ | g(r) against OVITO, multiplied by (N-1)/N | at most 8.7e-15 | +-------------------------------------------+----------------------------------------------+ | cutoff coordination | identical mean degree | +-------------------------------------------+----------------------------------------------+ .. table:: +------------+------+--------+-----------------+------------------------------------+ | frame | n | degree | largest freud q | PTM atoms outside the shared label | +============+======+========+=================+====================================+ | ice Ih | 128 | 4 | 1.7e-7 | 0 | +------------+------+--------+-----------------+------------------------------------+ | ice Ic | 64 | 4 | 3.7e-8 | 0 | +------------+------+--------+-----------------+------------------------------------+ | sI | 46 | 4 | 2.0e-6 | 0 | +------------+------+--------+-----------------+------------------------------------+ | liquid | 4096 | 5.056 | 1.8e-5 | 0 | +------------+------+--------+-----------------+------------------------------------+ | brine | 873 | 4.550 | 9.4e-6 | 58 | +------------+------+--------+-----------------+------------------------------------+ | nucleation | 4096 | 4.514 | 2.2e-5 | 27 | +------------+------+--------+-----------------+------------------------------------+ d-SEAMS keeps a neighbour when the minimum-image distance is strictly below the cutoff. Freud uses the same open ball. OVITO's uniform bond modifier also keeps a pair sitting on the cutoff. Two particles 3.5 Å apart are the witness: OVITO records the bond, and d-SEAMS and freud record none. A separation of 3.5 Å minus 1e-4 is a neighbour in all three. None of the six frames has a pair on that boundary. ``seams_neighbours_knn`` writes an undirected row. With the mutual flag clear, an edge is kept when either atom lists the other among its k nearest. With the flag set, both atoms must list each other. Freud and OVITO return the directed k nearest. Closing those directed lists the same way reproduces the C rows. On four colinear points with k = 1, the second point's one-way row holds both of its adjacent indices, and the mutual row holds only the partner that lists it back. Local q4 and q6 on the cutoff shell match an independent spherical harmonic of one liquid shell to 1e-16, and they match OVITO to the same scale. q6-bar is the Lechner-Dellago norm of the mean q\_6m, with the atom itself in the mean. On three oxygens at cutoff 2.5 Å that average differs from the mean of the scalar q6 values, and ``seams_ql`` follows the q\_6m mean. A single neighbour gives q6 = 1. Freud stores q\_l in float32. Rounding the same q\_6m to float32 before the norm accounts for its residual. The largest residual on these frames is 2.2e-5, on q6 of the nucleation frame. An empty shell is 0 here and in OVITO. ``seams_chill_plus`` with ``SEAMS_CHILL_OVITO`` matches OVITO's Chill+ modifier on every atom. The published 2015 table is a separate rule and is left as it stands. ``seams_system_symmetry`` and OVITO polyhedral template matching, with the cubic and hexagonal diamond structures enabled and an RMSD cutoff of 0.1, name the same atoms on ice Ih and on the generated ice Ic lattice. Ice Ic has a template RMSD below 1e-6. On the brine slab, 58 atoms carry only one of the two labels, and on the nucleation frame 27 do. Each of those atoms sits on a known side of the RMSD cutoff: a kernel crystal that PTM calls other has RMSD above 0.1, and a PTM diamond that the kernel does not name has RMSD below 0.1. The kernel ceiling is the scale-free second-shell residual 0.15. sI and the liquid are unlabeled by both. ``seams_rdf`` normalises a like-species histogram by N(N-1)/2. OVITO and freud's exact mode normalize the directed histogram by N^2. The histograms differ by N/(N-1). Multiplying the d-SEAMS values by (N-1)/N matches OVITO below 1e-14, including the bin centers. On ice Ic the raw integral at 3.5 Å is 4.0635 and the scaled integral is 4, the neighbour degree. Freud refuses an r\_max past half the shortest edge. d-SEAMS still bins minimum-image distances on a 10 Å cell out to 6 Å. The comparison uses 0.45 of the shortest edge, inside the range freud accepts. Freud's float32 distances move a boundary pair by one bin. That residual is 6.9e-4 on the brine g(r) and below 1e-5 on the three crystals. A pair placed just inside a cell of origin (2, 2, 2) Å, on opposite faces of the 10 Å edge, is a neighbour in all three codes. The minimum-image distance is 0.2 Å. Install ------- Meson installs ``seams.h``, ``seams_version.h``, ``libseams.so``, ``seams.pc``, and ``lib/cmake/seams/seams-config.cmake``. .. code:: sh pkg-config --cflags --libs seams ``examples/c`` is a small C program that builds against that install, either with pkg-config or with ``find_package(seams)`` and the imported target ``seams::seams``. ``meson test c_api_installed`` installs into the build tree and compiles that program both ways.