Public API for ForceProviders
Summary
Replace IRestraintPotential with generalized IForceProvider so that MD modules can be implemented externally.
Use cases
A common question from researchers is how to extend GROMACS with custom forces. Often, IForceProvider is a sufficient interface for their needs, but it is not a public API. This means that researchers trying to make a sustainable contribution to the community either need to maintain a fork (or patch), or find a way to get their functionality into the GROMACS core (which risks decreasing the sustainability of the project overall).
Impact
This is an extensibility proposal, aiming to allow more flexibility and agility to researchers and methods developers while decreasing the maintenance burden of the core library.
Detailed description
The IForceProvider interface has been pretty stable since it was updated to rely on a simple set of input and output parameter types. IForceProvider (or something very similar) can be elevated to the public API. We could either refine the input/output parameter types to be ABI-versioned simple structures (that can be extended, but not modified), or we can simply leave them opaque and provide free function accessors, as needed. Many use cases would be met by allowing for input and output iterators on atom location and force data, along with cross-reference info on atom type and global atom index.
As additional requirements are identified, or as more functionality is available to force providers, free functions can be added.
We should clarify the extension/registration protocol for MDModules at run time.
We could add a generalization of the gmx::MdRunner::addRestraint
, but I highly recommend that we instead try to strip away some of the layers between the client and the SimulatorBuilder, and just expose some MDModule builder interface instead (or a simpler wrapper similar to the IRestraintPotential that allows for implementing a IMDModule without having to know the definition of IMDModule).
Externally implemented MDModules could be added to the simulator with minimally modified replacement of the gmx mdrun
entry point code, or through the gmxapi Python bindings (as with IRestraintPotential). (See #4079 (closed) and #3145 (closed))
@eirrgang can offer proposals and sample implementations targeting the 2024 release, if there is project-level agreement that such extensibility is desirable, and if we can clarify the degree of updates to pursue in the call stack between the UI and the ISimulator calls.
Requirements
Public API discussion and review.
Links/references/implementations
Recent and ongoing projects that would benefit from such extensibility likely include QM/MM codes, collective variables related codes, structural refinement codes, and pretty much anything implementing IForceProvider since the original electric field module.
External code using the extension interface would resemble projects based on https://gitlab.com/gromacs/gromacs/-/tree/main/python_packaging/sample_restraint such as https://github.com/kassonlab/brer_plugin, though presumably much of the boiler plate would be moved to template headers in the public API.
See also: