The d-SEAMS topological ice score as a PLUMED action.
DSEAMS_CAGES takes a group of oxygen atoms and, every step, builds the
mutual and union four-nearest-neighbour graphs, the primitive six-membered
rings and the seeded cage assignment of d-SEAMS 2.0. With COMPLETE it
fills the last vertex of six-rings whose other vertices carry a label.
The action reports cage occupancy, the largest connected cluster, the
split into ice Ic, ice Ih and mixed, and the four-neighbour star method
CHILL+ on the same frame. Integer counts without derivatives drive
PRINT, COMMITTOR basins and stopping conditions. Cage lengths
inside the engine use the unit A. LENGTH_SCALE converts from the
PLUMED length unit (10 for the default nm, 1 after UNITS LENGTH=A).
LOAD FILE=libdseams_plumed.so
ice: DSEAMS_CAGES ATOMS=1-4096 CUTOFF=3.5 COMPLETE
PRINT ARG=ice.nice,ice.nmax,ice.chillice,ice.chillmax STRIDE=100 FILE=ICE
COMMITTOR ARG=ice.nmax STRIDE=100 BASIN_LL1=0 BASIN_UL1=20 BASIN_LL2=800 BASIN_UL2=100000
Build the shared module against an installed PLUMED. Meson runs
plumed info --include-dir for the headers. The kernel resolves the
symbols when LOAD dlopens the file, so the module does not link
against libplumed. An installed seams-core (pkg-config seams-core)
supplies the engine; the wrap is the fallback.
With pixi (plumed, compilers, meson):
pixi install
pixi run build # build/libdseams_plumed.so
pixi run testWithout pixi, put an installed plumed on PATH and run:
meson setup build --buildtype=release
meson compile -C build
meson install -C build # libdseams_plumed.so into libdirLOAD FILE= takes that path, or a relative path to
build/libdseams_plumed.so from the working directory of the run.
ATOMS (required) names the oxygen atoms of the water molecules.
CUTOFF (default 3.5) sets the neighbour cutoff in A for the CHILL+ graph.
CANDIDATE (default 5.5) sets the candidate shell in A for the four-nearest walk.
K (default 4) sets the neighbours per molecule in the bonded graph.
LENGTH_SCALE (default 10.0) converts the PLUMED length unit to A.
COMPLETE (flag, off) fills the last vertex of six-rings whose other
vertices carry a label.
IONS names ions read against the water assignment. Those ions stay
off the graph.
ION_CUTOFF (default 3.5) sets the radius in A of an ion’s first water shell.
HOPS (default 3) sets the bonds from the centre in each local topology key.
GUESTS lists one atom per guest molecule (methane carbon, THF oxygen,
an ion) and needs SIGNATURE: each guest goes to the nearest cage
centre (the periodic centroid of a cage’s vertices) within
GUEST_RADIUS (default 4 A). noccupied counts cages with a guest,
nmultiple cages with more than one, nfreeguest guests in no cage:
the filled-cage count that hydrate nucleation studies bias and commit
on.
LIBRARY names a topology key library from seams fingerprint --emit-library,
or several, comma separated, built at different hop counts: each molecule
takes the label of the deepest library that holds its key, so a molecule
whose wide neighbourhood is disturbed still gets a name from its inner
shells.
Omit LIBRARY or IONS when unused. The deepest library must be built
at HOPS; two libraries at one hop count, or libraries that differ in
colouring, are errors.
Each component reports an integer count with no derivative.
nice is the occupancy of hexagonal or double-diamond cages.
nmax is the largest connected cluster of cage molecules.
nclus is the number of connected cage clusters.
nic counts double-diamond cage members with no hexagonal label.
nih counts hexagonal cage members with no double-diamond label.
nmixed counts members of both cage types.
chillice counts CHILL+ cubic plus hexagonal molecules.
chillmax is the largest CHILL+ bulk-ice cluster.
chillinterfacial counts CHILL+ interfacial molecules.
sixrings counts primitive six-membered rings on the union graph.
nionice counts ions whose first water shell is all cage molecules.
nionfront counts ions with a mixed first shell.
nionliq counts ions with no cage molecule in the first shell.
nclasses counts distinct local topology classes on the mutual graph.
nnamed counts molecules whose local key the LIBRARY names.
Omit IONS and the three ion components stay 0. Omit LIBRARY and
nnamed stays 0.
Ions stay off the hydrogen-bond network. IONS builds the graph on
the oxygen atoms and reads each ion against that assignment. Water
inside ION_CUTOFF of the ion forms the first shell. An ion sits in
ice if every shell molecule carries a cage label. It sits in liquid if
no shell molecule does. Mixed shells put the ion at the front. The
three ion components report brine rejection at a growing front in an
electrolyte, for example TIP4P/2005 with the Madrid 2019 ions.
LOAD FILE=libdseams_plumed.so
brine: DSEAMS_CAGES ATOMS=1-3000 IONS=3001-3060 ION_CUTOFF=3.5 COMPLETE
PRINT ARG=brine.nice,brine.nmax,brine.nionice,brine.nionfront,brine.nionliq STRIDE=500 FILE=BRINE
Every molecule carries a local topology key: its rooted bonded
neighbourhood on the mutual graph within HOPS bonds (three by default).
nclasses counts the distinct keys in the frame. Point LIBRARY at a
key library written by seams fingerprint --emit-library LABEL, or by
the Python and Lua front ends. Then nnamed counts the molecules whose
key the library names. The same count names a hydrate framework or a
high-pressure ice.
hyd: DSEAMS_CAGES ATOMS=1-2944 LIBRARY=sI_sII.keys,sI_sII_h2.keys HOPS=3 PRINT ARG=hyd.nnamed,hyd.nclasses STRIDE=500 FILE=HYDRATE
Place fix plumed before fix npt or fix press/berendsen. Those
fixes compute the pressure internally. LAMMPS refuses a reversed
order. A minimal mW run logs the score every 500 steps. It stops on
a committor basin:
fix pl all plumed plumedfile plumed.dat outfile plumed.log
fix npt all npt temp 215 215 1000 iso 1 1 10000
Use plumed.dat as above and LENGTH_SCALE=1.0 after UNITS LENGTH=A.
LAMMPS units real matches the A unit of the engine.
Meson registers three plumed driver checks.
The nucleation check lives in tests/driver_check.py. It converts a
LAMMPS dump to xyz and runs the driver with the module loaded. Per
frame it compares nice, nmax, chillice and chillmax with the
engine walk_compare table. Absent a dump, the script uses the mW
cubic fixture under DSEAMS_PLUMED_DATA or the seams-core subproject.
The dump becomes xyz with the cell on the comment line. The check
does not depend on the molfile plugin.
python tests/driver_check.py $(which plumed) build/libdseams_plumed.so \
data/nucleation.lammpstrj results/walks/figshare-nucleation.txtdriver_ions (tests/ion_check.py) places two ions on a cubic-diamond
oxygen lattice. It checks nionice 2, nionfront 0, nionliq 0, with
nice still the remaining lattice.
driver_library (tests/library_check.py) writes a cubic-diamond
lattice, emits its key library with seams fingerprint --emit-library,
and checks that nnamed equals the molecule count and nclasses is
one. Meson registers this test when a seams binary is on PATH.
Released versions live in CHANGELOG.md (Keep a Changelog).
Unreleased notes are files under changelog.d/. Name each
fragment +slug.added.md (or changed, deprecated, removed,
fixed, security). The cut is towncrier build --version X.Y.Z.
Cite the methods paper if you use this module.
Goswami, R.; Goswami, A.; Singh, J. K. d-SEAMS: Deferred Structural Elucidation Analysis for Molecular Simulations. J. Chem. Inf. Model. 2020, 60, 2169-2177. 10.1021/acs.jcim.0c00031 (arXiv:1909.09830).
@Article{Goswami2020,
author = {Goswami, Rohit and Goswami, Amrita and Singh, Jayant Kumar},
title = {{d-SEAMS}: Deferred Structural Elucidation Analysis for Molecular Simulations},
journal = {Journal of Chemical Information and Modeling},
year = {2020},
volume = {60},
number = {4},
pages = {2169-2177},
doi = {10.1021/acs.jcim.0c00031},
}Every push to main builds the module against the pinned engine in the
pixi environment and runs the driver tests (pixi run test).