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 |
|---|---|
|
a name from :doc:`potentialnames\` |
|
its options in Angstrom and eV; may repeat |
|
an |
|
the engine’s Cap’n Proto parameters message |
|
the GROMACS box as the cell, or an isolated region |
|
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 energypressure 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_commstops 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
inthandle.- Units
none.
- Outputs
cp2k_create_force_envreturns handles 1 to 16, one per live force environment of the process.- Errors
a handle that names no live force environment stops
mdrunwith<function>: no force environment <handle>.
cp2k_get_version¶
void cp2k_get_version(char *version_str, int str_length);
- Inputs
version_str, a buffer ofstr_lengthbytes.- Units
none.
- Outputs
rgpot <version>, cut to fit and NUL-terminated, where<version>is the Meson project versionlibrgpot_gromacswas 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 inputmdrunwrites from the-qmifile;output_file_path, the log file, or NULL or empty for none.- Units
none.
- Outputs
\*new_force_env, a new handle. The&RGPOTsection 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 PERIODICwith a backend that has free boundaries, and charged MM atoms withoutEMBEDDING 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, andmpi_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_elcoordinates 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_elother 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 ofn_eldoubles.- 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 ofn_eldoubles.- 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 PERIODICwithout 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.