Skip to content

About

The d-SEAMS topological ice score as a PLUMED action: cage counts and the largest ice cluster on the fly

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

dseams-plumed

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

Install

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 test

Without 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 libdir

LOAD FILE= takes that path, or a relative path to build/libdseams_plumed.so from the working directory of the run.

Keywords

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.

Components

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

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

Topology keys

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

Inside LAMMPS

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.

Driver tests

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.txt

driver_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.

Changelog

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.

Citation

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},
}

Continuous integration

Every push to main builds the module against the pinned engine in the pixi environment and runs the driver tests (pixi run test).

About

The d-SEAMS topological ice score as a PLUMED action: cage counts and the largest ice cluster on the fly

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages