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 https://github.com/kassonlab/gromacs-gmxapi https://github.com/kassonlab/gmxapi and https://github.com/kassonlab/sample_restraint

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.

Proposal¶

• 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