Using GROMACS as a library

Getting started

The GROMACS library (libgromacs) provides a few different alternatives for using it. These are listed here from the highest level of abstraction to the low-level functions.

• If you are writing a trajectory analysis tool, please see Framework for trajectory analysis. Example code for writing trajectory analysis tools should contain all the ingredients to get started. If you have an existing tool written using the analysis template from 4.5 or 4.6 (using the selection engine added in 4.5), you need to do some conversion work to get this work with the new template. This is mostly straightforward, but requires some studying to understand the new framework.
• If you are writing a command line tool for some other purpose, you can use the facilities provided by Command Line Program Management (commandline). There are a few different alternatives, depending on how much control you want to give GROMACS:
  • For C++ code, you can implement gmx::CommandLineOptionsModuleInterface and use gmx::runCommandLineModule() to execute it. This interface assumes the use of the gmx::Options mechanism for declaring command-line options (see Extensible Handling of Options (options)). For a lower-level interface, gmx::CommandLineModuleInterface can be used, but this requires you to implement -h output and command-line parsing yourself (possibly using classes that GROMACS provides).
  • For C code, you can use gmx_run_cmain() to wrap an existing C main method. The only constraint on the provided main method is that it should use parse_common_args() for argument processing. This approach should allow you to convert existing C tools written against pre-5.0 GROMACS (e.g., using the analysis template from 4.0 or earlier) to the new version.
  • If you want more control (for example, you do not want the default command line options added by GROMACS), you can directly initialize GROMACS using gmx::initForCommandLine() before calling other GROMACS routines. This allows you to write your own handling for command line options from scratch. This is also discussed in Command Line Program Management (commandline).
• For most control, you can use gmx::init() to do basic initialization, create your own implementation for gmx::ProgramContextInterface, and set that using gmx::setProgramContext(). This allows you to customize how the GROMACS library shows the name of the program in messages, as well as how it locates its own data files.

If these do not fit your needs, you may need to modify the GROMACS source code yourself. In particular, it is currently relatively difficult to extend the functionality of mdrun without modifying the source code directly. If you think that some particular API would be necessary for your work, and think that it would be easy to expose, please drop a line on the gmx-developers mailing list, or contribute the necessary changes on http://gerrit.gromacs.org/.

Linking against libgromacs

GROMACS is a bit picky on how the headers need to be used: depending on compilation options used for GROMACS, some preprocessor defines may need to be set, the required include path may also depend on compilation options, and some extra libraries may need to be linked. You will also likely need to use the same compiler (or sufficiently similar one that uses the same standard library) that was used to compile GROMACS.

To manage this more easily, GROMACS provides two mechanisms for getting the correct flags for compilation and linking against the GROMACS library:

• pkg-config: GROMACS installs libgromacs.pc file (suffixed with the library suffix) for use with pkg-config if that is present on the system. Sourcing GMXRC adjusts the pkg-config search path such that these files are found automatically. See Makefile.pkg installed with the analysis template for one example of how to use it (to use it with a differently suffixed GROMACS, just replace libgromacs with libgromacs_suffix in the pkg-config calls).
• CMake package configuration files and a find module that allow find_package(GROMACS) to work. See below for details about how to use this in CMake. Sourcing GMXRC sets an environment variable that allows CMake to find the configuration file automatically. See CMakeLists.txt installed with the analysis template for one example of how to use it.

These mechanisms are currently provided on a best-effort basis, but are not routinely tested on a wide range of configurations. Please report any issues with details of how GROMACS was built so that the mechanism can be improved. Known issues:

• pkg-config files are not relocatable, i.e., they hard-code the installation prefix as an absolute path.
• Installing both static and shared libraries with the same suffix to the same installation prefix is guaranteed to work only if both are built with exactly the same configuration options (except for BUILD_SHARED_LIBS) from exactly the same version. There are several files that are shared between the installations in such a case, and the latter installation will overwrite those from the former.
• Further, if both static and shared libraries have been installed in the past to a prefix, then future installations to the same prefix should also install both static and shared libraries. Otherwise, some obsolete CMake package configuration files will be left behind which can lead to finding the old library. Alternatively, you can delete share/cmake/ from the installation directory before doing the install.
• If a mechanism other than the CMake-generated install target is used to install GROMACS over an existing installation, and the build type (e.g., Release vs. Debug) does not match what was previously installed, some obsolete CMake import target definition files are left behind in share/cmake/, and may cause failures whey trying to use the package configuration files.
• If GROMACS is built with GMX_BUILD_OWN_FFTW=ON, the CMake-generated import definitions for libgromacs reference a gmxfftw target that was used in the build to reference the fftw library. As this library only exists in the GROMACS build tree, and the CMake machinery does not write any import definitions for it anywhere, linking will fail with errors about not being able to find a gmxfftw library. So the CMake package configuration files can only be used with GMX_BUILD_OWN_FFTW=OFF.

CMake find_package(GROMACS) details

The CMake machinery to support find_package(GROMACS) has two parts: a 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 installed to share/cmake/ from input files in src/gromacs/).

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 FindGROMACS.cmake.

Input options for influencing what to find:

GROMACS_SUFFIX (only for FindGROMACS.cmake)

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>).

GROMACS_PREFER_STATIC

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 GROMACS_LIBRARIES.

GROMACS_DIR

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_PATH can be used for this purpose; see CMake documentation for find_package for more details. GROMACS_DIR can also be set as an environment variable, and this is done by GMXRC.

Output variables that specify how the found libgromacs and header should be used:

GROMACS_INCLUDE_DIRS

List of include directories necessary to compile against the GROMACS headers. Currently, this includes the path to GROMACS headers, as well as the path to Boost headers that were used to compile GROMACS.

GROMACS_LIBRARIES

List of libraries to link with to link against GROMACS. Under the hood, this uses imported CMake targets to represent libgromacs.

GROMACS_DEFINITIONS

List of compile definitions (with -D in front) that are required to compile the GROMACS headers.

GROMACS_IS_DOUBLE

Whether the found GROMACS was compiled in double precision.

Declared macros/functions that can be used for checking for correctness of some settings:

gromacs_check_double(GMX_DOUBLE)

Checks that the found GROMACS is in the expected precision. The parameter GMX_DOUBLE should be the name of a cache variable that specified whether double-precision was requested.

gromacs_check_compiler(LANG)

Checks that the found GROMACS was compiled with the same compiler that is used by the current CMake system. Currently only LANG=CXX is supported.

Notes on GROMACS API

The headers for the public GROMACS API are installed in include/gromacs/ under the installation directory. The layout reflects the source code layout under the src/gromacs/ directory (see Source code layout). The headers directly under include/gromacs/ do not contain any declarations, but instead include a collection of headers from subdirectories. You should prefer to include these convenience headers instead of individual headers from the subdirectories, since they are much more stable. The individual headers in the subdirectories can be renamed or moved, but the goal is to only rarely change the name of these top-level headers.

Pre-5.0 versions of GROMACS installed (nearly) all headers directly under include/gromacs/. Most of these headers still exist, but now under include/gromacs/legacyheaders/. The long-term goal is to move these to proper module hierarchy or get rid of them, but unfortunately this can take a long time. Thus, you should not expect much stability from the API in these headers. Some have already been moved, so if you do not find your favorite header there, try searching for a declaration from the other subdirectories.

For headers under other subdirectories, some effort has been put to design the API for stability. However, with limited development resources, and the focus of GROMACS being in high performance simulations, all the APIs are subject to change without notice. With each new release (with possible exception of patch releases), you should expect incompatible API changes. This is in particular true until the planned reorganization of the legacyheaders/ subdirectory is complete.

The header version.h (installed as gromacs/version.h) provides defines that calling code can use to check the exact (released) version of GROMACS that installed the headers.

This Doxygen documentation only covers part of the API. In particular, nearly all of include/gromacs/legacyheaders/ is undocumented, as well as code recently moved from there.