GROMACS QM/MM drop-in reference

librgpot_gromacs implements the C API of the CP2K library, which GROMACS calls for its QM group when built with -DGMX_CP2K=ON. The steps are in GROMACS QM/MM drop-in, and why it implements the CP2K interface is in GROMACS QM/MM through the CP2K interface.

The &RGPOT section

The run uses qmmm-cp2k-qmmethod = INPUT and a -qmi file with an &RGPOT section. The keys grompp checks stay as CP2K has them. The &RGPOT keys are:

Key

Value

POTENTIAL Name

a name from :doc:`potentialnames\`

OPTIONS key value …

its options in Angstrom and eV; may repeat

ENGINE path

an rgpot_engine_* library, instead of POTENTIAL

CONFIG path

the engine’s Cap’n Proto parameters message

CELL PERIODIC or NONE

the GROMACS box as the cell, or an isolated region

EMBEDDING NONE

accept charged MM atoms that do not act on QM atoms

Exactly one of POTENTIAL and ENGINE is required. OPTIONS go with POTENTIAL and CONFIG with ENGINE. An engine’s configuration is the flat message the engine ABI takes.

Atoms, charge and multiplicity

mdrun writes the PDB file itself and passes its name in place of COORD_FILE_NAME. The PDB file gives each atom its element and marks it QM or MM. Only QM atoms are passed to the potential; MM atoms get zero force from it and keep whatever the GROMACS force field gives them. grompp already removes the QM-QM nonbonded pairs and bonded terms, so the QM region interacts only through rgpot. A POTENTIAL needs CHARGE 0 and MULTIPLICITY 1. An ENGINE gets both through rgpot_engine_set_charge_spin; when the engine lacks that call or the call returns 3, the input needs CHARGE 0 and MULTIPLICITY 1 too.

Errors

Nothing can be returned through the libcp2k API, so every error stops mdrun with status 1. The message starts with rgpot-gromacs: on standard error and is repeated in the md_cp2k.out file GROMACS names. Examples are an unknown potential or option, a missing &RGPOT section (as with a generated method such as PBE), a QM atom without an element, a &LINK section, a charged MM atom without EMBEDDING NONE, and a failed or non-finite evaluation at any step.

Units and cell

GROMACS sends positions in Bohr and takes energies and forces in atomic units. It converts them with the constants of its units.h, which qmmm_units.hpp copies expression for expression. So GROMACS reports the rgpot energy times 96.48533212331002 kJ/mol per eV and the forces times 964.8533212331002 kJ/(mol nm) per eV/Angstrom, up to rounding.

With a periodic potential and pbc = xyz, the default is CELL PERIODIC: each step the QM atoms are wrapped into the GROMACS box, which goes to the potential as the cell, triclinic or not. GROMACS 2024 and 2025 send the box transposed and 2026 does not; a GROMACS box is lower triangular, so the library tells the two apart from the zeros. CELL NONE, the default for a potential with free boundaries, keeps each QM atom at the image nearest its previous position, so a molecule split by the box stays whole, and centres the region in a cube with sides of at least 100 Angstrom and of twice the region’s extent plus the cutoff plus 10 Angstrom.

Limits

  • No virial: pressure, NPT and gmx energy pressure terms exclude rgpot.

  • No electrostatic embedding: MM charges do not act on the QM region, and no link atoms, so the QM group must be whole molecules or a whole crystal.

  • One thread-MPI rank (-ntmpi 1); OpenMP threads are fine. cp2k_create_force_env_comm stops with an error.

  • Tested with double-precision GROMACS only.

  • The shim wraps atoms every step, as the LAMMPS pair style does. A kernel whose neighbour list has a Verlet skin rebuilds it whenever an atom crosses a cell face, so the cost per MD step exceeds that of repeated calls on one geometry; the benchmark in GROMACS QM/MM drop-in measures both.

C API

engines/gromacs/libcp2k.h declares the functions with CP2K’s signatures (cp2k/src/start/libcp2k.h), leaving out those GROMACS does not call. engines/gromacs/rgpot_gromacs.cpp implements them. Positions and cells are in Bohr, energies in Hartree and forces in Hartree/Bohr, as in CP2K. Every n_el is three values per atom of the PDB file, QM and MM, in its order. A call that fails stops mdrun as described under Errors.

force_env_t

Inputs

none; an int handle.

Units

none.

Outputs

cp2k_create_force_env returns handles 1 to 16, one per live force environment of the process.

Errors

a handle that names no live force environment stops mdrun with <function>: no force environment <handle>.

cp2k_get_version

void cp2k_get_version(char *version_str, int str_length);
Inputs

version_str, a buffer of str_length bytes.

Units

none.

Outputs

rgpot <version>, cut to fit and NUL-terminated, where <version> is the Meson project version librgpot_gromacs was built from.

Errors

none; a null buffer or a length of zero or less writes nothing.

cp2k_init

void cp2k_init(void);
Inputs

none.

Units

none.

Outputs

none; the call does nothing.

Errors

none.

cp2k_init_without_mpi

void cp2k_init_without_mpi(void);
Inputs

none.

Units

none.

Outputs

none; the call does nothing.

Errors

none.

cp2k_finalize

void cp2k_finalize(void);
Inputs

none.

Units

none.

Outputs

none; the call does nothing.

Errors

none.

cp2k_finalize_without_mpi

void cp2k_finalize_without_mpi(void);
Inputs

none.

Units

none.

Outputs

none; the call does nothing.

Errors

none.

cp2k_create_force_env

void cp2k_create_force_env(force_env_t *new_force_env, const char *input_file_path,
                           const char *output_file_path);
Inputs

input_file_path, the CP2K input mdrun writes from the -qmi file; output_file_path, the log file, or NULL or empty for none.

Units

none.

Outputs

\*new_force_env, a new handle. The &RGPOT section selects the potential or engine, which is opened here, and the PDB file the input names gives the atoms. The log file gets the library version, the backend, the atom counts, the energy of the first step in eV and, when the force environment is destroyed, the number of evaluations.

Errors

more than 16 live force environments, a null or empty input_file_path, an input or PDB file that does not parse, a backend that does not open, a charge or multiplicity the backend does not take, CELL PERIODIC with a backend that has free boundaries, and charged MM atoms without EMBEDDING NONE.

cp2k_create_force_env_comm

void cp2k_create_force_env_comm(force_env_t *new_force_env, const char *input_file_path,
                                const char *output_file_path, int mpi_comm);
Inputs

as cp2k_create_force_env, and mpi_comm, a Fortran MPI communicator.

Units

none.

Outputs

none.

Errors

always stops mdrun, with a message asking for a thread-MPI GROMACS with one rank (-ntmpi 1).

cp2k_destroy_force_env

void cp2k_destroy_force_env(force_env_t force_env);
Inputs

force_env, a handle.

Units

none.

Outputs

none; the engine object is destroyed, the log file closed and the handle freed. An engine library stays loaded, because a tensor runtime keeps process-wide state.

Errors

an unknown handle, as under force_env_t.

cp2k_set_positions

void cp2k_set_positions(force_env_t force_env, const double *new_pos, int n_el);
Inputs

force_env; new_pos, n_el coordinates of every QM and MM atom.

Units

Bohr.

Outputs

none; the positions are kept for the next evaluation.

Errors

an unknown handle, or an n_el other than three times the atoms of the PDB file.

cp2k_set_cell

void cp2k_set_cell(force_env_t force_env, const double *new_cell);
Inputs

force_env; new_cell, nine values, the GROMACS box row by row from GROMACS 2026 and transposed from 2024 and 2025.

Units

Bohr.

Outputs

none; the box rows are kept for the next evaluation. A cell of zeros counts as no box.

Errors

an unknown handle, or a cell that is neither lower nor upper triangular.

cp2k_get_natom

void cp2k_get_natom(force_env_t force_env, int *natom);
Inputs

force_env; natom, where the count goes.

Units

none.

Outputs

\*natom, the number of atoms in the PDB file, QM and MM.

Errors

an unknown handle.

cp2k_get_positions

void cp2k_get_positions(force_env_t force_env, double *pos, int n_el);
Inputs

force_env; pos, a buffer of n_el doubles.

Units

Bohr.

Outputs

the positions of the last cp2k_set_positions, unchanged, because the library moves no atom.

Errors

an unknown handle, or a wrong n_el.

cp2k_get_forces

void cp2k_get_forces(force_env_t force_env, double *force, int n_el);
Inputs

force_env; force, a buffer of n_el doubles.

Units

Hartree/Bohr.

Outputs

the forces of the last evaluation on every atom; MM atoms get zero.

Errors

an unknown handle, a wrong n_el, or a call before the first evaluation.

cp2k_get_potential_energy

void cp2k_get_potential_energy(force_env_t force_env, double *e_pot);
Inputs

force_env; e_pot, where the energy goes.

Units

Hartree.

Outputs

\*e_pot, the energy of the last evaluation.

Errors

an unknown handle, or a call before the first evaluation.

cp2k_calc_energy_force

void cp2k_calc_energy_force(force_env_t force_env);
Inputs

force_env.

Units

positions and cell in Bohr in, the stored energy in Hartree and forces in Hartree/Bohr; the potential itself sees Angstrom and returns eV.

Outputs

none; one rgpot evaluation of the QM atoms, with the cell chosen as under Units and cell.

Errors

an unknown handle, a call before cp2k_set_positions, a singular box, CELL PERIODIC without a box, a failed evaluation, or a non-finite energy.

cp2k_calc_energy

void cp2k_calc_energy(force_env_t force_env);
Inputs

force_env.

Units

as cp2k_calc_energy_force.

Outputs

as cp2k_calc_energy_force, forces included.

Errors

as cp2k_calc_energy_force.