Upgrade from 2.13 to 2.14

These notes start from tag v2.13.0 (7f310225). The release notes are 2.14.0. Rebuild the engine, then relink anything that should call libseams.

C and C++

Add #include "seams.h" and link libseams. The header is C linkage, so a C++ caller uses it as it stands. seams_set_num_threads(0) puts back the OpenMP width the library captured at first use. Frame, neighbour, CHILL+, q4/q6, and ring calls are on that header. A program that already used the C++ classes keeps those classes. BondClassifier is the 2.13 layout.

The language ABI is seams_lang.h and libseams_lang. Use it when the program reads a trajectory path or keeps a frame across calls.

Language bindings

2.14 moves every language binding out of this repository. Each one is its own repository and package, built against the seams-core 2.14.0 tag and versioned 2.14.0:

Language

2.13 location

2.14 repository

Package

Python

PydSEAMSlib (pydseams) and the in-tree dseams module

PydSEAMSlib

pydseamslib: import dseams and import pydseams

Lua, Fennel

yodaStruct (1.x)

yodaStruct

LuaRocks dseams

R

none

dseams-r

dseams

Julia

none

Dseams.jl

Dseams and Seams, over libseams_jll

Rust

none

dseams-rs

crates dseams-sys and dseams

Fortran

none

dseams-fortran

fpm dseams

A Python script keeps working after pip install -U 'pydseamslib==2.14.0'. The per-language upgrade notes (new calls, renamed options, the SEAMS_LANG_LIB and SEAMS_LIB_DIR variables) are in each repository’s changelog. Paths under bindings/ other than bindings/cxx no longer exist in this tree.

Engines

Turn a plugin on by letting Meson find the library, or by setting -Dwith_lammps, -Dwith_gromacs, -Dwith_openmm, or -Dwith_plumed. The default for LAMMPS and GROMACS is auto.

engine

what to change

LAMMPS

The hook reads angstroms. engines/lammps/in.dseams is the deck. The copy-in compute lives under extras/lammps.

GROMACS

gmx-seams reads the lower-triangle cell and scales nanometers to angstroms before CHILL+.

OpenMM

One DseamsReporter. Positions are nanometers and are multiplied by 10. InSitu.observe is the same classification.

PLUMED

The SEAMS collective variable scales internal nanometers to angstroms and returns a q6 derivative per nanometer.

A head-to-head that times PLUMED’s own symfunc has to set PLUMED_NUM_THREADS. The rows in benchmarks/rc3-sitting.csv left that variable unset, so they were measured on one thread. The q6 rows in benchmarks/paper-cells/sitting-large.csv set it, and that time falls as the width grows.

Threads

OMP_NUM_THREADS is still the OpenMP width. seams::teamFor uses one thread below 2048 atoms and four threads below 8192 atoms when the width asked for is larger than four. prepareCompute does not set OMP_WAIT_POLICY, and adoptThreads leaves the OpenMP team running. The orthorhombic cutoff list is shared by published CHILL+ and cutoff q6. Each pair is counted once. An interior cell skips the periodic shift. On one thread a carried ring update copies and sorts directly. Several threads still sort and merge in parallel. A team narrower than the process is bound once to that many cores of the allowed set, and that bind stays for the process.

Deprecations and breaks

--types remains the deprecated alias of --pair-types and still warns.

The fingerprint options use the American spelling. seams fingerprint --color-types is the name help shows. --colour-types is still accepted, as a hidden deprecated alias of that same option, so it does not appear in help and does not warn. In Fortran, frame_fingerprint takes colors. colours is still accepted, as an optional deprecated keyword with the same meaning. Giving both keywords different values is an error. seams_fingerprint takes color_types. Python fingerprint(color_types=...), Rust FingerprintOptions::color_types, and the Lua colors field follow the same rename and do not accept the old names. A key library writes colors in its header. The reader still accepts colours as a deprecated alias of that word, so a 2.13 library file with colours 1 keeps its type colors. The library has no warning channel, so that read is silent.

CHILL and CHILL+ on the default name seeded now score the cutoff list. Pass mutual for the four-nearest graph. seams cages still treats seeded as its own graph. A reader error exits 2. seams steinhardt prints q4 and q6 along with the degrees in --l.