Task #2045: API design and language bindings
C++ extension module for Python bindings
gmxapi Python package includes a
_gmxapi submodule that provides bindings to the GROMACS library. This issue tracks the implementation of that submodule. Scope of this issue is intended to be limited to the set up of the bindings framework and build environment.
Criteria for completion:
To limit the scope of this Redmine issue, consider this task complete when the C++ extension is built as part of the package described in https://redmine.gromacs.org/issues/2893.
pybind11 is proposed because it is lightweight, performant, modern, well-maintained, and allows GROMACS development to remain C++-based as much as possible. A GROMACS C++ developer should be able to trouble-shoot API bindings or expose incremental functionality with minimal reference to Python or other non-C++ syntax.
Idiomatic Python packaging for the
gmxapi package will undoubtedly be expanded.
scikit-build provides a convenient bridge between Python packaging tools and CMake C++ project environments.
The library target for the bindings module depends on the public (installed) interface of a GROMACS library with position-independent-code.
In this issue, the GROMACS repository becomes the upstream source of updates to the package historically available from https://github.com/kassonlab/gmxapi, in which the C++ extension module is
Note: pybind11 is a template header library that helps C++11 code interact with the Python C API. Projects are expected to bundle the pybind11 headers and not to rely on the pybind11 namespace for ABI compatibility with other code. The bundled pybind11 headers should not need to be updated except to take advantage of new functionality, incorporate bug fixes, or address (rare) C API changes in new Python versions.
Use pybind11 to make a minimal C++ Python extension.
- Bundle pybind11 2.2.4 headers
- Create the `gmxapi._gmxapi` submodule as a C++ extension module.
Add GROMACS library dependency to gmxapi package.
The `gmxapi` Python package has a C++ extension module configured and
built through CMake. This change links the C++ extension module to the
GROMACS library external interface.
No new code is introduced. This change just establishes that a Python
package can be built, installed, and imported with dynamic linking to
an installed GROMACS library.
Basic mdrun operation for Python gmxapi.
Add wrapper code and bindings so that the Python module can invoke
mdrun through the C++ API of the GROMACS installation.
Python bindings for mdrun.
This change makes a near-exact copy of the mdrun Python
bindings from gmxapi 0.0.7.
This establishes a base from which to transition Python bindings
development from GitHub to the GROMACS repository, so Python wrappers,
interface updates, and other changes are deferred to separate commits.
The provided interface largely opaque except for arguments passed the
same way as mdrun command line flags.
GROMACS must be built with GMXAPI=ON.
Python wrapping code for gmxapi mdrun bindings.
Expose the mdrun bindings to the Python interface. Imports workflow.py
and context.py from 0.0.7.4 tagged release of external project at
https://github.com/kassonlab/gmxapi with minimal modifications.
#5 Updated by Eric Irrgang 6 months ago
- Description updated (diff)
We can consider whether there are cases in which we should plan to exclude the pybind11 headers from source distributions in related issue https://redmine.gromacs.org/issues/2896. If we do that, we should test against the minimum pybind11 release we expected to build against (see https://redmine.gromacs.org/issues/2756)
The initial patches under the current issue assume pybind11 2.2 syntax and bundle the 2.2.4 patch level.
#9 Updated by Eric Irrgang 6 months ago
Initial port of Python bindings for mdrun is verified at https://travis-ci.org/kassonlab/gromacs-gmxapi/builds/515340999 but testing is blocked on #2894.