GROMACS

engines/gromacs/seams_ice.cpp is a TrajectoryAnalysisModule. The binary is gmx-seams. It reads a trajectory with the GROMACS reader. analyzeFrame is the trajectory-analysis callback: it converts nm to Angstrom, calls seams_chill_plus, and records the time. The runner invokes that callback once per frame.

gmx-seams -f engines/gromacs/ice.gro -cutoff 3.5

meson test gromacs_mdrun runs engines/gromacs/run_mdrun.sh, and meson test docs_engine_gromacs runs this -f / -cutoff invocation on input/traj/ice1h.lammpstrj. run_mdrun.sh classifies the trajectory gmx mdrun just wrote. Positions are multiplied by 10 on the way into seams_chill_plus. The box conversion is gromacs_box_to_lammps with the same scale.

(
  cd "$work"
  env -u LD_LIBRARY_PATH -u LIBRARY_PATH \
    OMP_NUM_THREADS=1 GMX_MAXBACKUP=-1 \
    gmx grompp -f md.mdp -c ice.gro -p topol.top -o ice.tpr -maxwarn 2
  env -u LD_LIBRARY_PATH -u LIBRARY_PATH \
    OMP_NUM_THREADS=1 GMX_MAXBACKUP=-1 \
    gmx mdrun -s ice.tpr -deffnm ice -nsteps 4 -ntmpi 1
  void analyzeFrame(int, const t_trxframe &fr, t_pbc *, gmx::TrajectoryAnalysisModuleData *pdata) override {
    if (!fr.bX || !fr.bBox) {
      return;
    }
    const gmx::Selection &sel = pdata->parallelSelection(sel_);
    const int n = sel.posCount();
    if (n <= 0) {
      return;
    }
    std::vector<double> xyz(static_cast<std::size_t>(n) * 3);
    for (int i = 0; i < n; ++i) {
      const auto &x = sel.position(i).x();
      xyz[static_cast<std::size_t>(3 * i)] = static_cast<double>(x[0]) * 10.0;
      xyz[static_cast<std::size_t>(3 * i + 1)] = static_cast<double>(x[1]) * 10.0;
      xyz[static_cast<std::size_t>(3 * i + 2)] = static_cast<double>(x[2]) * 10.0;
    }
    double raw[3][3];
    for (int a = 0; a < 3; ++a) {
      for (int b = 0; b < 3; ++b) {
        raw[a][b] = static_cast<double>(fr.box[a][b]);
      }
    }
    double box9[9];
    gromacs_box_to_lammps(raw, box9, 10.0);
    // frame_census calls seams_chill_plus.
    const auto t0 = std::chrono::steady_clock::now();
    const FrameCensus census = frame_census(xyz.data(), n, box9, cutoffA_);
    const auto t1 = std::chrono::steady_clock::now();
    seconds_ += std::chrono::duration<double>(t1 - t0).count();
    frames_ += 1;
    if (!census.ok) {
      failed_ = true;
      return;
    }
    if (!dump_.empty()) {
      writeDump(fr.bStep ? static_cast<long long>(fr.step) : frames_ - 1, sel, xyz, box9,
                census.labels);
    }
    ice_ += census.cubic;
    atoms_ += n;
    hexagonal_ = census.hexagonal;
    six_ = census.six;
    q6_ = census.q6;
  }

ice.gro is two frames of the 64-atom cubic cell. The tool prints overhead_s, the mean seconds per frame, and for the last frame gromacs hexagonal N six-rings M q6 Q. overhead_s is machine-dependent. A topology is not required. gmx-seams runs after gmx mdrun and reads the trajectory that run wrote. Biasing from inside mdrun goes through the PLUMED collective variable, which links the same C API.

-select picks the sites to classify; the default is every atom. A multi-site water model needs its oxygens only, which takes a run input file: gmx-seams -s topol.tpr -f traj.trr -select 'name OW'. -dump file appends a LAMMPS dump frame per analysed frame with the coordinates handed to d-SEAMS, in Angstrom, and the CHILL+ label. Molecules are not made whole, so those coordinates are the ones in the trajectory.

GROMACS 2023 and later install neither the trajectory-analysis headers nor the generated libgromacs_export.h they include. Point the gromacs_legacy_include option at api/legacy/include of the GROMACS source that matches the installed libgromacs; engines/gromacs/compat supplies the export header. gmx-seams builds as C++17, as GROMACS does.

meson test gromacs_e2e builds a TIP4P/Ice ice Ic slab with a liquid layer, runs 200 steps of gmx mdrun, classifies the oxygens of every .trr frame with gmx-seams, and compares the labels with seams chill-plus on the dump and the dumped oxygens with gmx dump. GROMACS will not read a trajectory from a pipe, so this hook runs after mdrun. meson test gromacs_plumed_e2e instead loads the PLUMED collective variable into gmx mdrun -plumed, classifies inside the MD loop, and also requires the same labels from gmx-seams on the same steps. With GROMACS 2024 and PLUMED 2.9 that test sets GMX_DD_SINGLE_RANK=0: under single-rank domain decomposition about 5% of the oxygens reached PLUMED with a neighbouring atom’s coordinates. The test reads the action’s timing from md.log under the PLUMED patch and from PLUMED.OUT under GROMACS 2025 and later, which link PLUMED without it.