Public C++ API#
Trajectory analysis tools and pluggable MD extensions
(such as code based on the
gromacs/ headers supported by
For more on using
libgromacs and the installed
refer to the Legacy API documentation.
See also the Trajectory Analysis Framework.
Software that uses new public API facilities (such as
uses CMake and
find_package(gmxapi) to configure a build system to use
gmxapi/ headers and link to the library supporting the
::gmxapi C++ namespace.
gmxapi library conveys an indirect dependency on
a bug in CMake 3.24.0,
find_package(gmxapi) must implicitly call
to avoid a spurious error, even though client software does not generally
need to explicitly use
Gromacs::libgromacs or its details.
Client build system support#
GROMACS relies heavily on CMake
to configure and manage the build system.
The GROMACS installation directly supports CMake configured client software
through configuration and “hints” files installed to
gmx --version (or the appropriate
notes on the original build toolchain that may or may not be sufficient for
configuring the client software build system.
Though not explicitly required, it is highly recommended that client software build with a toolchain that closely matches that of the GROMACS build to avoid binary incompatibilities.
Each GROMACS installation (since 2022) provides a CMake “hints” file that
can be used to initialize your cmake cache with the
For a GROMACS installation in
the hints file for a given
GROMACS_SUFFIX can be found at
The hints file is completely separate from the CMake configuration files that
-C path/to/gromacs-hints$GROMACS_SUFFIX.cmake in your client
cmake configuration command line can help set appropriate compiler
options so that you have a better chance of building a compatible binary.
(I.e. it helps
In addition to hints variables for CMake
find_package, the hints file sets
GMX_CMAKE_VERSION in case the
client build system needs to know the version of CMake that was used to build
the GROMACS installation.
GROMACS uses FindMPI
(the module that supports CMake
find_package(MPI ...)) to locate and
configure compiler and linker options for MPI support. Client software is
advised to do the same.
If software support for MPI was detected by GROMACS when built, the
gromacs-hints file (see above) will define input variables to help
find_package locate the same MPI installation.
If GROMACS is installed from a package built in a different environment, the embedded toolchain information may be inaccurate. This could make the gmx --version output misleading and the gromacs-hints file useless. You may encounter spurious warnings when configuring the client build system, and the client software may or may not interact properly with the GROMACS installation.
In a computing environment with multiple toolchains available (such as a typical High Performance Computing (HPC) cluster), the toolchain may depend on environment variables for consistent behavior. If environment modules were used when setting up the GROMACS build environment (e.g. module load gcc openmpi/gcc), it may be necessary to load the same environment modules before building the client software.
gmxapi CMake package#
The CMake configuration files installed with GROMACS support the
“Config mode” of CMake
gromacs$GROMACS_SUFFIX packages, CMake configuration files only
support a single
gmxapi package name.
gmxapi API and ABI hide most of the differences possible in
from different build options. However, the
interface is affected by the original choice of
GMX_MPI. A stable
interface is available to MPI-enabled client software through the
gmxapi/mpi/gmxapi_mpi.h template header.
Some GROMACS installations include multiple builds.
For instance, there may be a
(according to build-time values of
any one of which might be provided by the
target. Until resolution of Issue 4334, only one version of the
Gromacs::gmxapi is importable from a GROMACS installation.
Each GROMACS installation (with
ON) overwrites the
CMake configuration files for the previously installed gmxapi support.
gmxapipackage provides a single
Gromacs::gmxapitarget that conveys access to the installed
gmxapi/headers. The associated shared object library will be differently named, depending on the build system configuration options. (See
The CMake machinery to support
find_package(GROMACS) has two parts:
FindGROMACS.cmake find module (found in
share/gromacs/template/cmake/ in the installation and
share/template/cmake/ in the source tree), and actual package
configuration files (
gromacs-config.cmake and supporting files
share/cmake/ from input files in
FindGROMACS.cmake is a simple wrapper over the package configuration
files, providing a somewhat more convenient interface to the machinery
that supports multiple suffixed GROMACS installations in
the same installation prefix (see
GROMACS_SUFFIX variable below).
This file is intended to be version-agnostic and remain both forward-
and backward-compatible even between major GROMACS
releases. All version-specific information and the actual details about
the compilation and linking settings is in the package configuration
files. Build systems willing to utilize
FindGROMACS.cmake can create
a local copy of it and use it like it is used in the installed
share/gromacs/template/CMakeLists.txt. The package configuration
files can also be used directly if desired, bypassing
find_package(GROMACS) is able to find configurations for any of the
gromacs_mpi_d CMake package
names. Otherwise, you must use the exact package name that you are looking for.
Provides access to the installed core GROMACS library and
target_link_libraries(foo PRIVATE Gromacs::libgromacs).
Represents the command line executable. For example, to set a local CMake variable
_gmx_executableto the executable path (with the correct
GROMACS_SUFFIX) you can use
get_target_property(_gmx_executable Gromacs::gmx LOCATION)in your
Input options for influencing what to find
This CMake variable can be set before calling
find_package(GROMACS)to specify the GROMACS suffix to search for. If not set, an unsuffixed version is searched for. If using the package configuration files directly, the suffix must be set using
find_package(GROMACS NAMES gromacs<suffix>).
This CMake variable can be set before calling
find_package(GROMACS)to specify whether static or shared libraries are preferred if both are available. It does not affect which GROMACS installation is chosen, but if that installation has both static and shared libraries available (installed from two different builds with the same suffix), then this chooses the library to be returned in
This CMake (cache) variable is a standard mechanism provided by
find_package, and can be used to specify a hint where to search for GROMACS. Also
CMAKE_PREFIX_PATHcan be used for this purpose; see CMake documentation for
find_packagefor more details.
GROMACS_DIRcan also be set as an environment variable, and this is done by
Output variables that specify how the found
libgromacs and header
should be used:
List of include directories necessary to compile against the GROMACS headers. Currently, this includes the path to GROMACS headers.
List of libraries to link with to link against GROMACS. Under the hood, this uses imported CMake targets to represent
List of compile definitions (with
-Din front) that are required to compile the GROMACS headers.
Whether the found GROMACS was compiled in double precision.
Required compiler flags.
Declared macros/functions that can be used for checking for correctness of some settings:
Checks that the found GROMACS is in the expected precision. The parameter
GMX_DOUBLEshould be the name of a cache variable that specified whether double-precision was requested.
Checks that the found GROMACS was compiled with the same compiler that is used by the current CMake system. Currently only