========================= Upgrade from 2.13 to 2.14 ========================= These notes start from tag v2.13.0 (``7f310225``). The release notes are `2.14.0 <../reference/release-2.14.rst>`_. 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: .. table:: +-------------+--------------------------------------------------------------+---------------------------------------------------------------+------------------------------------------------------------+ | 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. .. table:: +---------+---------------------------------------------------------------------------------------------------------------------------+ | 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``.