Task #2912
Task #2045: API design and language bindings
C++ extension module for Python bindings
Description
The 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.
Bindings framework¶
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.
Build system¶
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.
Additional information¶
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 gmx.core
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.
Related issues
Associated revisions
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.
Ref: #2912
Change-Id: I1c992c30132df25cf6a91902611cb201962649af
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.
Refs: #2912
Python bindings for mdrun.
This change makes a near-exact copy of the mdrun Python
bindings from gmxapi 0.0.7.
Reference https://github.com/kassonlab/gmxapi/releases/tag/v0.0.7.3
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.
Fixes #2912
Change-Id: I2f51ae8f2369334d06a7ceaa8a4abf3ed9fc444a
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.
Refs #2893
Refs #2912
Refs #3027
Change-Id: I44a66646eceb191a2ec755169671af326f22526a
History
#1 Updated by Eric Irrgang 8 months ago
- Related to Feature #2896: Python packaging added
#2 Updated by Eric Irrgang 8 months ago
- Related to Task #701: Add symbol visibility macros added
#3 Updated by Eric Irrgang 8 months ago
- Related to Task #988: Definition of "public API" added
#4 Updated by Eric Irrgang 8 months ago
- Related to Task #2893: Integrate gmxapi Python package added
#5 Updated by Eric Irrgang 8 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.
#6 Updated by Eric Irrgang 8 months ago
- Related to Task #2756: gmxapi integration testing added
#7 Updated by Gerrit Code Review Bot 8 months ago
Gerrit received a related DRAFT patchset '5' for Issue #2912.
Uploader: M. Eric Irrgang (ericirrgang@gmail.com)
Change-Id: gromacs~master~Iadc8645906c2b89d98fae57b891deac80793b050
Gerrit URL: https://gerrit.gromacs.org/9236
#8 Updated by Gerrit Code Review Bot 8 months ago
Gerrit received a related DRAFT patchset '5' for Issue #2912.
Uploader: M. Eric Irrgang (ericirrgang@gmail.com)
Change-Id: gromacs~master~I1c992c30132df25cf6a91902611cb201962649af
Gerrit URL: https://gerrit.gromacs.org/9322
#9 Updated by Eric Irrgang 8 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.
#10 Updated by Eric Irrgang 8 months ago
- Blocked by Task #2894: Wrap importable Python code. added
#11 Updated by Eric Irrgang 5 months ago
- Status changed from In Progress to Resolved
Applied in changeset 2fcc13067e87478952fea0963c546cde1bf2412d.
Use pybind11 to make a minimal C++ Python extension.
Ref: #2912
Change-Id: Iadc8645906c2b89d98fae57b891deac80793b050