Module: kenref

Description	Usage
kinetic ensemble refinement of a replica ensemble against NMR observables
Authors: Amr Alhossary and Colin Smith

Details

The KENREF module implements kinetic ensemble refinement: it biases an ensemble of replicas so that NMR observables computed across the ensemble reproduce experimental values. It provides a single action, KENREF, which is a Bias and an ActionAtomistic at the same time — it acts on atomic coordinates directly and takes no ARG.

The numerics live in an external library, KEnRef (https://github.com/Smith-Group/KEnRef), which this module links against. Three energy models are available and are selected by name with the MODEL keyword:

`MODEL`	restrains
`SIGMA`	cross-relaxation rates (interproton NOE build-up)
`PLATEAUS`	NOE plateau values
`RELAX`	longitudinal/transverse relaxation over the ensemble

Because the observables are ensemble averages, RELAX requires at least two replicas; run PLUMED with --multi in the usual way. SIGMA and PLATEAUS also work with a single replica.

Installation

This module is not compiled by default. It requires the KEnRef core library, which supplies both the energy models and the source for this action's constructor. Configure PLUMED with:

./configure --enable-kenref

--enable-kenref and --enable-modules=+kenref are equivalent: either one enables the whole pathway. If kenref_core is already installed, put its prefix on PKG_CONFIG_PATH and configure will find it (the install ships an env.sh that does this for you). Otherwise configure clones KEnRef and delegates the build to KEnRef's own CMake, into kenref-deps/ inside the PLUMED build tree. Point it at a local checkout instead with --with-kenref-src=DIR, or override the clone with KENREF_GIT_URL / KENREF_GIT_TAG.

KEnRef stores Eigen objects inside its own containers, so the module must be compiled with the same Eigen alignment as libkenref_core — that is, the same -march/SIMD width. A mismatch is caught at compile time by a static_assert in KEnRef's headers rather than corrupting memory at run time. The .pc files KEnRef installs carry the right -march, so this is handled for you; you only need to think about it if you assemble the flags by hand.

src/kenref/install.md documents the build in more detail, and src/kenref/build-only.sh automates it.

Where the source lives

This module is deliberately split. KEnRefBias.cpp here holds the stable parts of the action — keyword registration, the PLUMED↔Eigen glue, calculate(), and the action registration — and is maintained in PLUMED. The one-time constructor, which changes whenever KEnRef gains an energy model or alters its parameter schema, is hosted in the KEnRef repository and compiled in through the forwarding translation unit KEnRefBias_setup.cpp.

The point of the split is that adding a model to KEnRef, or changing its input format, does not require a change to PLUMED. KEnRef remains the source of truth for that half; please do not "inline" the forwarder.

For the same reason, the regression tests here are deliberately thin: they check that the action parses, registers, runs and produces its declared components. The numerical correctness of each energy model is validated in KEnRef's own test suite against reference values from the original R implementation, which is where new models should be tested.

Example

An ensemble refinement of GB3 against cross-relaxation rates. EXP_DATA_FOLDER holds the experimental data and the atom-pair definitions; REF is the reference structure used for the Kabsch fit.

Click on the labels of the actions for more information on what each action computes

#SETTINGS MOLFILE=regtest/kenref/rt-kenref-sigma/gb3_frag.pdb
kenrefThe KENREF action with label kenref calculates the following quantities: Quantity    Type    Description  
kenref.bias scalar the instantaneous value of the bias potential
kenref.energy scalar Total KEnRef restraint energy
kenref.rmsd scalar RMSD from reference (after fitting): KENREFRestrains an ensemble of replicas against NMR observables (kinetic ensemble refinement). More details ...
  MODEL The energy model to use (e=SIGMA
  K Force constant=1.0
  N Power scaling factor=0.25
  PROTON_MHZSpectrometer proton field strength in MHz (SIGMA model)=700.0
  EXP_DATA_FOLDERFolder with relaxation spectral-density experimental data (RELAX model)=regtest/kenref/rt-kenref-sigma/
  REFReference structure PDB for alignment=regtest/kenref/rt-kenref-sigma/gb3_frag.pdb Click here to see an extract from this file.
    ×  FILE: regtest/kenref/rt-kenref-sigma/gb3_frag.pdb
    CRYST1   61.224   61.224   61.224  60.00  60.00  90.00 P 1           1
ATOM      1  N   MET     1      36.173  53.535  11.325  1.00  0.00           N
ATOM      2  H1  MET     1      35.621  53.973  10.603  1.00  0.00           H
ATOM      3  H2  MET     1      35.940  53.879  12.246  1.00  0.00           H
ATOM      4  H3  MET     1      37.121  53.791  11.086  1.00  0.00           H
...
ATOM     96 HD23 LEU     5      48.686  45.453  21.597  1.00  0.00           H
ATOM     97  C   LEU     5      46.755  50.244  20.923  1.00  0.00           C
ATOM     98  O   LEU     5      47.305  50.926  20.090  1.00  0.00           O
TER
END
  
  ATOMNAME_MAPPING PDB file with atom-name -> atom-index mapping (also used as reference if REF is omitted)=regtest/kenref/rt-kenref-sigma/gb3_frag.pdb Click here to see an extract from this file.
    ×  FILE: regtest/kenref/rt-kenref-sigma/gb3_frag.pdb
    CRYST1   61.224   61.224   61.224  60.00  60.00  90.00 P 1           1
ATOM      1  N   MET     1      36.173  53.535  11.325  1.00  0.00           N
ATOM      2  H1  MET     1      35.621  53.973  10.603  1.00  0.00           H
ATOM      3  H2  MET     1      35.940  53.879  12.246  1.00  0.00           H
ATOM      4  H3  MET     1      37.121  53.791  11.086  1.00  0.00           H
...
ATOM     96 HD23 LEU     5      48.686  45.453  21.597  1.00  0.00           H
ATOM     97  C   LEU     5      46.755  50.244  20.923  1.00  0.00           C
ATOM     98  O   LEU     5      47.305  50.926  20.090  1.00  0.00           O
TER
END
  
  GUIDE_ATOMSAtoms used for alignment to reference=1,5,18,20,22,35,37,39,56,58,60,78,80,82,97
  MAX_FORCEMaximum force magnitude (default 9999)=999
  FIT_TO_REFERENCE Fit coordinates to reference before calculating energy
  SATURATE_FORCES Clamp forces to MAX_FORCE
...

PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=kenref.bias,kenref.energy,kenref.rmsd FILEthe name of the file on which to output these quantities=kenref.out STRIDE the frequency with which the quantities of interest should be output=1

Note that there is no ARG keyword: KENREF biases coordinates, not collective variables.

Citing KEnRef

The method this module applies, and the KEnRef implementation it calls into, are described in:

A. Alhossary and C. A. Smith, Restraining Interproton Angular and Distance Dynamics with KEnRef, J. Phys. Chem. B 130, 3076-3087 (2026), doi:10.1021/acs.jpcb.5c08554. This paper introduces KEnRef and corresponds to its version 1.0.0.
C. A. Smith, A. Mazur, A. K. Rout, S. Becker, D. Lee, B. L. de Groot, Enhancing NMR derived ensembles with kinetics on multiple timescales, J. Biomol. NMR 74, 27-43 (2019), doi:10.1007/s10858-019-00288-8. This is the kinetic ensemble refinement method that KEnRef implements.

Actions

The following actions are part of this module

Name	Description	Tags
KENREF	Restrains an ensemble of replicas against NMR observables (kinetic ensemble refinement).	BIAS

References

More information about this module is available in the following articles:

Quantity	Type	Description
kenref.bias	scalar	the instantaneous value of the bias potential
kenref.energy	scalar	Total KEnRef restraint energy
kenref.rmsd	scalar	RMSD from reference (after fitting)