Feature #2586

Feature #2585: Infrastructure supporting external API

Versioned libgmxapi target for build, install, headers, docs

Added by Eric Irrgang over 2 years ago. Updated about 1 year ago.

Target version:


gmxapi milestone 2 as described in #2585

Resolution of this issue establishes a framework in which further API infrastructure can be developed.

Proofs of concept for a public C++ API, necessary libgromacs support, and various client code (including a Python interface) have been under development at and

We would like to migrate to development that is more unified with the GROMACS project.

gmxapi development has been spread across multiple repositories and several CMake targets. There are several reasons to continue to manage multiple repositories.

  • It is helpful to limit subproject scope and focus discussion by compartmentalizing major contributions.
  • High level functionality can continue to be developed while integration and implementation details are worked out.
  • Strong separation of dependent subprojects helps track API compatibility at different levels.


  • libgromacs target is minimally affected by near-term #2045 and related tasks
  • a libgmxapi target is introduced to support new external interfaces for C++ client code
  • Optional CMake target: `-DGMXAPI=ON`, default ON so everyone gets compiler feedback if they change a data structure that affects the installed interface
  • New installed C++ headers in gromacs.git
  • Formally deprecate old installed headers, no intent to replace directly
  • Tests on the current state of the installed interface, built by Jenkins
  • Tests should work only on the installed interface - but maybe can mock infrastructure like MPI or GPUs?
  • Installed headers in `gmxapi/` and don’t depend on lower level headers.
    - Public symbols are segregated in the gmxapi:: namespace
    - Gmx symbols confined to private headers and implementation code
    - libgromacs may provide implementations of some gmxapi interfaces.
  • Separate gmxapi documentation target for its API docs and developer docs. To cross-link documentation layers and modules, etc, is it better to mix the generated content or keep it separate? Considerations:
    - Speed of doc builds
    - Clarity of exposure-level of a given symbol or dependent symbols and target audience of documentation
    - Ease of automatically generating dependency graphs; complexity of infrastructure
  • Can @in_public_api be repurposed or do we need more/different marker?
  • Library API provides functions to check library build version. Defines in public headers provide compile-time client API version.
  • HasFeature() function for forward compatibility.
  • Python user interface is maintained externally until required infrastructure is better developed
  • Python package available in a standard GROMACS install is targeted for a future GROMACS release, per #2045

Additional details to discuss

  • Technical details of nesting GROMACS while retaining access to git hash (e.g. which hash built this libgromacs?): cmake external project, submodule, subtree, nesting gromacs in gmxapi or the other way around?

Proposed changes

1. Introduce essentially empty libgmxapi target
2. Invite discussion on near-term target features / interfaces
3. Add to it conservatively
4. CI testing with requirement not to break the implementation. (use to encourage good abstractions, care about API design, and allow more freedom to developers whose client code is now entirely local and not out in the user base somewhere)
5. Ultimately supplant current “public” API

Associated revisions

Revision 030f54b4 (diff)
Added by Eric Irrgang over 2 years ago

Framework in which to build gmxapi.

Establish a clean slate in which to develop the new external GROMACS
interface. Introduces `libgmxapi` and installed headers in
`include/gmxapi/` to provide a stable C++ interface.

Note that this commit has several inconsistencies with the gmxtree
policies, and src/api/cpp/* has been added to
docs/doxygen/suppressions.txt to avoid testing noise while these issues
are resolved. They are mostly of the following sort.

1. includes non-local file as "gmxapi/version.h"
2. does not include "gmxpre.h" first

The public interface is separated into a separate directory that does
not fit the current pattern for installed headers, and there is code
that specifically builds against the public interface that should not
include library headers, like "gmxpre.h". Discussion and tasks to
resolve policy and apply appropriate checks is at Redmine issue #2586
(gmxapi milestone 2)

Refs #2586

Change-Id: I1eb8ea75fdaea77e0ce03f2d312c44db8df16f28


#1 Updated by Gerrit Code Review Bot over 2 years ago

Gerrit received a related patchset '3' for Issue #2586.
Uploader: M. Eric Irrgang ()
Change-Id: gromacs~master~I1eb8ea75fdaea77e0ce03f2d312c44db8df16f28
Gerrit URL:

#2 Updated by Eric Irrgang over 2 years ago

  • Description updated (diff)

#3 Updated by Eric Irrgang over 2 years ago

  • Status changed from New to In Progress

gmxapi library is now built by default (when possible) and headers are installed. Various aspects need further development for GROMACS 2020, including CMake target management, header dependencies and include policies, deprecation of the previous installed GROMACS headers, documentation integration, and integration with existing command-line interface code.

#4 Updated by Eric Irrgang almost 2 years ago

  • Status changed from In Progress to Resolved

This is issue is as complete as it is going to be. The public API is being redefined, as are the library targets and build system.

The internal and external library targets do not have tracked issues yet.

Public API headers may fall under issue #988 or #2045. Public API documentation is nominally covered by issue #2698.

#5 Updated by Eric Irrgang about 1 year ago

  • Status changed from Resolved to Closed

Also available in: Atom PDF