Changelog¶
Release notes for the d-SEAMS engine. This repository builds
libyodaLib, the C library libseams (include/seams.h), the
language ABI libseams_lang, and the seams command. Each language
binding is its own package. The current release is 2.14.0.
2.14.0¶
seams.h is ABI 1. Callers moving from
2.13 follow the upgrade guide.
Highlights¶
A frame carries an orthorhombic or triclinic cell. The C API returns neighbours, the published CHILL+ rule and the OVITO rule, q4 and q6, primitive rings, and ring symmetry labels.
CHILL+ defaults to the cutoff neighbour list.
--graph mutualis the mutual four-nearest list.LAMMPS, GROMACS, and OpenMM call the library on the frames a running calculation chooses. The report is the primitive ring census, the published CHILL labels, and the hexagonal and double-diamond cage flags.
The ice label is the scale-free residual of the seventeen-atom shell after the optimal rotation and scale. The shell is the central atom, its four bonded neighbours, and the atoms bonded to those four.
IRA, SOFI, and spglib reports for ice shells, hydrate cages, and rings are optional. The build links them when
-Dwith_iraand-Dwith_spglibfind the libraries.
C API¶
seams_set_num_threads(0) restores the OpenMP width captured at first
use. That width is omp_get_max_threads() when OpenMP is linked, and 1
otherwise. A negative width returns SEAMS_ERR_RANGE.
seams_system_set_positions overwrites the coordinates, and optionally
the cell, of a stored frame. seams_system_box,
seams_system_positions, seams_system_types, and seams_system_ids
copy the stored frame out through a const handle.
Length-checked calls are seams_chill_plus_n, seams_q4q6_n,
seams_rings_labels_n, and seams_rings_histogram_n. The counts are
seams_system_natoms, seams_neighbours_nrows, and
seams_rings_nrings. seams_last_error_message names the last
failure. seams_rings_chordless lists every chordless cycle of one
size from 3 to 12, as sorted canonical rows. On 4096 mW molecules, one
thread, the six-ring census that calls it takes 3.1 ms. The census it
replaces took 20.6 ms.
Every public call returns a seams_status. The library does not call
exit.
Packages¶
Each binding is version 2.14.0.
Language |
Package |
Repository |
|---|---|---|
Python |
|
|
Rust |
crates |
|
Fortran |
fpm Git dependency |
|
Lua, Fennel |
Git source, |
|
R |
package |
|
Julia |
|
The Meson options that built the
bindings in-tree are removed: with_python, with_lua, fennel_lua,
with_fortran, julia_wrap, r_libs_user, and system_libseams.
pydseams 2.14.0 has a Frame handle. read, from_ase, to_ase,
to_solvis, chill_plus, cages, cages_by_signature, steinhardt,
rdf_2d, monolayer_rings, find_prisms, and
pydseams.band.ring_census call libseams_lang. Saved trajectories
other than CON are read with chemfiles when that library is linked.
The formats include xyz, a LAMMPS dump, gro, pdb, dcd, xtc, and Amber
NetCDF.
Engines¶
LAMMPS loads compute dseams as dseamsplugin.so (plugin load), or
from the copy-in sources in extras/lammps. The plugin accepts
cutoff, graph cutoff or graph mutual, rule published or
rule ovito, type I, and mol water. The copy-in sources accept
cutoff, graph, type, and mol. type and mol water score
only the named oxygens. GROMACS uses a module inside mdrun. OpenMM
uses a reporter.
The PLUMED SEAMS collective variable is a separate plugin. The
standalone PLUMED action (dseams-plumed v0.4.1) is indexed in
PLUMED-NEST egg 26.018. Meson
builds it when -Dwith_plumed finds PLUMED. The option defaults to
auto. seams.q6 is the mean local q6, seams.ice is the CHILL+
cubic fraction, and seams.ring is the fraction of atoms on a
primitive six-ring. MODE=all, the default, also reports the
hexagonal count and the six-ring count. MODE=q6 and MODE=q6bar
compute only the mean local q6 or the mean Lechner-Dellago q6-bar.
DUMP=file appends a LAMMPS dump of the coordinates handed to d-SEAMS
and the per-atom value. A restraint can bias q6. Positions are read in
PLUMED’s length unit and converted to angstroms.
Neighbour lists and CHILL+¶
The cutoff list covers restricted triclinic boxes. The orthorhombic list is a parallel cell sort. Each thread counts its atoms, a prefix sum places them, and the pairs are written into one CSR. The pair set does not depend on the thread count. Each OpenMP thread also owns a block of the linkcell weighted cell cut.
On input/traj/exampleTraj.lammpstrj, 250 TIP4P oxygens of LAMMPS type
2:
seams chill-plus input/traj/exampleTraj.lammpstrj --cutoff 3.5 --type 2
seams chill-plus input/traj/exampleTraj.lammpstrj --cutoff 3.5 --type 2 --graph mutual
The cutoff command prints nop 250 interClathrate 9 water 241. The
mutual command prints nop 250 clathrate 1 interClathrate 7 water 242.
Those cutoff counts are a shell-count fix on this frame. The previous
cutoff classification reported 12 interClathrate and 238 water, because
bonds were counted after the list had been cut to four. A crystal row
needs four neighbours inside the cutoff. seams ovito-chill+ averages
q3 on the full shell and skips that neighbour test. Plain CHILL keeps
the four closest neighbours and Moore’s test. A failure to read the
input returns exit status 2.
--pair-types I,J names the site-site pair for seams rdf and
seams cn. Neighbour, CHILL, CHILL+, ring, and cage calls keep water
oxygens with --water-types or --mol (water, or a molecule-id
list such as 1,5-12) and leave ions out of that graph. A type or
molecule id that is absent from the frame is an error.
Cages and symmetry¶
A signature cage is kept when its faces tile a sphere: every vertex
lies on at least three faces that close around it, and \(V - E + F = 2\).
--cage-edge and SEAMS_CAGE_EDGE set the face-edge window, in the
coordinate units of the file. The default is 2.65,3.15. none leaves
the cage bound to the face census. Frame.cages_by_signature and the
Lua edge option take the same window.
seams rings prints the primitive-ring census by size. Primitive rings
are the Franzblau shortest-path census. seams prisms counts perfect
and imperfect prisms of sizes 3 to 6.
Performance¶
On 110592-molecule ice Ic, 8 OpenMP threads run the cutoff list 4.8 times, q4 5.8 times, q6 5.9 times, and the primitive-ring census 6.1 times faster than 1 thread. The CSR, the \(q_l\) values, and the ring counts match at 1, 2, 4, and 8 threads.
When an idle 8-thread OpenMP team is already resident, 8-thread CHILL+
on that ice Ic frame takes 7 ms and the shell match takes 9 ms. The
same calls took 74 ms and 76 ms before the library narrowed its team
to the free cores. SEAMS_FAIR_WIDTH=0 keeps the requested width.
Times on an idle machine are unchanged.
Deprecations¶
--types is a deprecated alias of --pair-types. Both names bind.
Using --types prints a one-line warning on stderr.
seams fingerprint --color-types is the spelling --help shows.
--colour-types remains a hidden alias of that option. A key library
writes colors in its header and still reads a 2.13 file that says
colours.
2.13.0¶
Each bond row is the sorted neighbour ids.
seams cagesreuses a search only when the undirected edge sets match. Differing lists are searched on their own.Cage-edge windows and other decimal options parse in the C locale, so the same decimal text is accepted on every supported toolchain, including a libc++ with no floating
std::from_chars.pydseamslibchill_plustakes no graph argument. The call labels the cutoff neighbour list.
2.12.0¶
Double-diamond cages are a maximum non-conflicting set.
findDDC builds the mutual-conflict graph once. A one-cage component
is kept. A component whose neighbourhoods are the two cliques of a
bipartite line graph is a maximum matching, certified by a König
cover. Any other component is a branch-and-bound maximum independent
set, certified by a clique partition. A degree-one candidate is kept,
and only that one conflict is dropped.
A peripheral set is kept when the seven rings span 14 molecules and each peripheral shares exactly three atoms with the equator. When the product of rings through the even or odd triplets exceeds 256, the chains are built from edges that share at least three atoms, and the lexicographically least assignment that meets the same test is kept.
On cubic mW, 4096 molecules, the certified double-diamond count is 2048, one cage for every two molecules. The search before this certificate reported 2040. On nucleation frame 148 the double-diamond count is 121 and the hexagonal count is 102. The search before the certificate reported 122 double-diamond cages.
On the all-site niu2f1 frame, one thread spends 176.4 s in one run of
findHC, findDDC, and findBySignatures together. TRACE on that
frame spends 1762.064 s. On the mixed-site frame findDDC returns 0.
The search before the 14-molecule rule returned 605243 cages there,
and every hexagon of that frame fails the rule.
The clathrate face-edge window is --cage-edge and SEAMS_CAGE_EDGE,
default 2.65,3.15 in the coordinate units of the file. none turns
the window off.
cages --signature counts a face set as a cage when its faces tile a
sphere: every vertex lies on at least three faces that close around
it, and \(V - E + F = 2\). Rings whose minimum-image bonds add up to a
lattice vector wind through the periodic cell and are dropped first.
On the GenIce structure I unit cell the search reports 2 \(5^{12}\)
cages and 6 \(5^{12}6^{2}\) cages. The search before that test reported
90 \(5^{12}6^{2}\), 4248 \(5^{12}6^{4}\), and 218305 \(5^{12}6^{8}\).
The orthorhombic cutoff list folds coordinates into the cell, bins them one cutoff wide, and shares the 27-cell stencil across the atoms in a cell. Interior cells skip the periodic wrap. CHILL and CHILL+ on the default left-to-right fp64 path evaluate the \(l = 3\) harmonics as real and imaginary parts.
CHILL and CHILL+ default to the cutoff list on the command line, in
the C API, in R, in Julia, and in compute dseams. The mutual
four-nearest list is --graph mutual under that name on each of those
fronts. Those fronts used the mutual list by default before this
release.
This release adds the R package and the Julia package. Both call
libseams_lang.
2.11.0¶
Cutoff neighbour rows and hexagonal and double-diamond cage affiliation run across host threads.
Under
mpiexec, an MPI build shares the--frame/--lastrange of a LAMMPS dump across ranks. Rank 0 prints every frame in order. A run without a launcher, or withSEAMS_MPI=0, stays on one process.Periodic distances use minimage 0.1.4. The linked-cell neighbour search uses linkcell 0.3.10.
The ice XXI library matches the Lee et al. 2026 I-42d oxygen cell (space group \(I\bar{4}2d\), Z = 152, a = b = 20.197 Å, c = 7.891 Å). A hit also requires a tetrahedral four-nearest graph, mean coordination in [3.5, 4.5], and a six-ring census near 112.
2.10.0¶
Rodger F4 and host \(q_{12}\) are per-atom fields, so the Zeron q3/q12 hydrate pair can be read from the command line.
CHILL and CHILL+ default to the mutual four-nearest graph.
--water-typeskeeps the four-neighbour list on the named water types, so substrate and ions stay out of it.Cups and incomplete cages are enumerated on the ring graph. Closed signature counts stay on the closed path.
seams cages --signature --incompletereports the open cages.Stacking planes of the topological unit matching (HC-basal and DDC-equatorial) are reported beside the CHILL+ \(I_{sd}\) bins.
SEAMS_OFFLOAD=1runs those hop-bound cages on a device when one is present, and on the host when none is.SEAMS_OFFLOAD=0stays on the host. CHILL+ itself stays on the host.Hexagonal channels are stacked six-ring prisms. Ice XXI (Lee et al., Nat. Mater. 25, 302, 2026) also requires a tetrahedral 3.5 Å graph and a primitive six-ring on the Z = 152 cell.
compute dseamswrites per-atom CHILL+ from the C API. The example deckextras/lammps/in.dseamsreadsextras/lammps/water.datawithpair_style zero.
2.9.2¶
Every host stage of the ring pipeline runs under OpenMP. From 2048
atoms, when OpenMP is compiled in, the cutoff neighbour list and the
index-ordered list come from nneigh::cellListRowsThreaded. Atoms are
binned in fractional coordinates of the recovered triclinic cell, every
axis needs three cells of perpendicular width one cutoff, and each row
is one thread’s task. The rows equal the minimum-image reference.
neighbourListByIndex runs one row per thread. bench_strong times
every host stage and their sum and keeps the best of five runs.
2.9.1¶
The OpenMP target offload of the Steinhardt kernel compiles with nvc++
23.7 (-mp=gpu) against CUDA 12.2 on an NVIDIA A100. The device path
matches the serial and threaded host paths bit for bit on the FCC
lattice and on input/traj/mW_cubic.lammpstrj. SEAMS_OFFLOAD=0
forces the host path.
2.9.0¶
cage::findBySignature enumerates closed polyhedra from a ring-size
census. seams cages --signature takes a census such as 4:6,6:8 or
a name (sodalite, alpha, 512, 51262, hc, ddc). Named hc
and ddc call findHC and findDDC, so the vertex sets match those
finders.
topo::matchLibraries names atoms against key libraries at several hop
counts. The deepest library that holds an atom’s key wins, and the
report includes the depth that named the atom. seams fingerprint --library accepts a comma-separated list.
site::guestOccupancy places guests in enumerated cages by the
periodic centroid of the cage vertices and counts occupied, multiply
occupied, and free cages. --guest-types names the guest LAMMPS types.
site::shellRingCensus counts, by size, the water-network rings that
pass through an ion’s shell. --per-atom FILE on cages,
fingerprint, and ions appends a LAMMPS dump frame with the engine’s
per-atom decision, for OVITO or VMD.
2.8.0¶
topo::localKey names the isomorphism class of an atom’s rooted
bonded neighbourhood. With nauty linked, the key is the nauty
certificate. Otherwise it is a Weisfeiler-Leman hash.
topo::fingerprint keys a frame by the sorted hashes and the primitive
ring census, so a relabelled configuration shares the key.
--color-types partitions keys by LAMMPS type.
seams fingerprint --emit-library writes a frame’s keys as library
lines. --library names the atoms of a later frame from that file.
seams ions classes ions by their first water shell against the cage
assignment. --hops, --ion-types, and --ion-cutoff are the new
options.
seams cages --graph seeded --complete turns on ring-adjacent
completion. The CLI keeps frame order for a parallel LAMMPS range,
dispatches ranges for XYZ, chemfiles, and readcon input, and writes
versioned JSONL with --format json. --strict-input makes an empty
frame an error. XYZ input accepts coordinate-only rows and records
that frame as frame 1.
CON input uses the embedded readcon reader when the engine is built with it. CON or chemfiles input with the reader absent is refused, and the call does not return an empty frame in its place.
2.7.0¶
ring::seededCageAffiliation takes an optional completion flag.
ring::ringAdjacentCompletion fills the last vertex of any six-ring
whose other vertices carry a cage label, and repeats to a fixed point.
Hexagonal-cage labels and double-diamond-cage labels are two separate
walks. The rule is stated and proved in lean/ with Mathlib: the
completion is the least fixed point above the seed, it is empty on an
empty seed, and it does not depend on the visiting order.
2.6.0¶
Meson links FlexiBLAS when pkg-config or libflexiblas is present, and
otherwise the conda-forge libblas and liblapack packages. Python
callers use pydseamslib from PyPI. The nucleation notebook reads
CageScore fields. The Figshare Lua demos load example_lua from
yodaStruct.
2.5.0¶
--family selects the chemistry. The default is waterIce. chill,
chill-plus, cages, and ions on any other family print the family
name and return exit status 2. seams cn --ions is the cage degree on site::ionCloud. seams pairs counts
mutual-nearest contact pairs. seams domains is the largest polar or
apolar Stoddard component. seams density-z is the type-resolved
\(\rho(z)\), with the slab volume taken from the dump cell matrix.
Running coordination numbers and the first minimum of \(g_{IJ}\) come
from rdf::runningCN and rdf::firstMinimumBin. Dump writers emit
xy, xz, and yz when the cloud carries tilt.
2.4.0¶
seams rdf and seams cn compute partial three-dimensional site-site
\(g_{IJ}(r)\) and coordination numbers under the dump minimum image.
Site chemistry is a site::Table of LAMMPS types, with optional
atom-id overrides. site::ionCloud collapses each ion molecule id to
one unwrapped center-of-mass vertex. Hydrogen bonds accept an explicit
donor-hydrogen index set through populateHbondsFromDonors. seams hbonds --donors treats every hydrogen as a donor candidate. The water
cutoffs on that command are the water criterion.
In-plane RDF normalization uses the dump-cell volume \(|\det H|\) and the restricted-triclinic in-plane area \(l_x \times l_y\).
2.3.4¶
Steinhardt parameters, hydrogen bonds, and cluster wraps use the dump minimum image.
2.3.3¶
Cutoff fallbacks and the skin Verlet refresh use the dump 3 by 3 minimum image.
2.3.2¶
Cutoff lists take the LAMMPS dump 3 by 3 cell. Device ice-score batches
pass lammpsBoxToLinkcell when the dump carries tilt. This release
uses linkcell v0.3.1.
2.3.1¶
neighList, halfNeighList, and the in-plane RDF sampler use the
vesin cell list, the same helper as neighListO. Brute force remains
the fallback. The GPU ice-score workspace is unchanged.
2.3.0¶
The topological unit-matching ice score (mutual four-nearest graph, primitive hexagons, hexagonal and double-diamond cages) runs as a device-resident batch of frames when gpulite and linkcell 0.3.0 are present. CHILL and \(q_{lm}\) stay on the host.
Runtime settings are read from SEAMS_CONFIG or from ./seams.env in
the working directory, then from the environment, then from
command-line flags. seams --print-config prints the resolved table.
Examples call seams, pydseams, and require("dseams"). The 2020
yodaStruct -c and conf.yaml surface is removed in this release.
2.2.5¶
This release uses linkcell v0.2.4. A static libyodaLib links the static
linkcell archive, so a consumer of that archive does not need
liblinkcell.so at link time. Dump floating-point fields parse with
strtod, including on Apple libc++.
2.2.4¶
Periodic k-nearest graphs come from
linkcell v0.2.2.
kNearestNeighbourList and kNearestNeighbourPair write packed
\(n \times k\) nominations. The mutual graph and the union graph come
from one walk. The LAMMPS dump box is the bound spans plus xy, xz,
and yz. periodicDistSq recovers the cell matrix from that box. An
empty frame no longer stops the walker.
2.2.3¶
Help, errors, ice-type counts, and --features are colorized.
NO_COLOR turns the color off.
2.2.2¶
The compiled Python module in this release is pydseams.yoda.
pydseams._core remains an alias.
2.2.1¶
The Nix flake packages
libyodaLibandseams. The package is the Meson build.A live LAMMPS dump session,
nLammpsFramesandforEachLammpsFrame, supportsseams --frame N --last M --jobs J. Each worker opens its own handle.The bond graph is chosen at runtime:
cutoff,knn, orknn-union.seams cages --graphaddsseeded.LAMMPS readers bind
xu,yu,zuandxs,ys,zswhenx,y, andzare absent.
2.2.0¶
The engine command line is seams, with read, chill,
chill-plus, and cages. Lua callers use the dseams library from
yodaStruct. Python callers use pydseams.
2.1.2¶
The CMake-era Nix entry points (default.nix, shell.nix, and
nix/yodaStruct.nix) are removed. They still named the product
yodaStruct. This release builds with pixi.
2.1.1¶
The CHILL interfacial walk uses the same four-neighbour star as
c_ij. Atoms without four recorded bonds are labelled water, matching
CHILL+. Seeded affiliation floods the hexagonal cage and the
double-diamond cage as separate components, so a hexagonal seed does
not keep a double-diamond-only atom.
2.1.0¶
This repository is the C++ engine.
The
yodaStructLua and Fennel command line moves to https://github.com/d-SEAMS/yodaStruct . This release rejects-Dwith_lua=enabledand names that repository. The option itself is removed in 2.14.0.Python bindings stay in https://github.com/d-SEAMS/PydSEAMSlib , where they moved in 2.0.1.
getCorrel,getCorrelPlus,getIceType,getIceTypeNoPrint,getIceTypePlus,getIceTypePlusNoPrint, andreclassifyWaterreturnvoid.
2.0.1¶
The Python bindings move to https://github.com/d-SEAMS/PydSEAMSlib . This repository is the C++ engine. macOS wheels in this release target deployment 14, and macOS x86_64 wheels are no longer built.
2.0.0¶
Meson replaces CMake. The license changes from GPL to MIT. Optional dependencies are vesin neighbour lists, Highway SIMD, chemfiles, and readcon-core. The engine tests are a Catch2 suite.
1.0.0¶
Initial release. Goswami, Goswami, and Singh, J. Chem. Inf. Model., 60, 2169-2177, 10.1021/acs.jcim.0c00031.