Gromacs  2024.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions
gmx::IRestraintPotential Class Referenceabstract

#include <gromacs/restraint/restraintpotential.h>

Inherited by anonymous_namespace{manager.cpp}::DummyRestraint.

Description

Interface for Restraint potentials.

Derive from this interface class to implement a restraint potential. The derived class must implement the evaluate() member function that produces a PotentialPointData instance. For various convenience functions and to decouple the internal library interface from implementations of potentials, it is expected that restraints will be programmed by subclassing gmx::RestraintPotential<> rather than gmx::IRestraintPotential.

For a set of $n$ coordinates, generate a force field according to a scalar potential that is a fun. $F_i = - \nabla_{q_i} \Phi (q_0, q_1, ... q_n; t)$

Potentials implemented with these classes may be long ranged and are appropriate for only a small number of particles to avoid substantial performance impact.

The indices in the above equation refer to the input and output sites specified before the simulation is started. In the current interface, the evaluate() virtual function allows an implementer to calculate the energy and force acting at the first of a pair of sites. The equal and opposite force is applied at the second site.

The potential function is evaluated with a time argument and can be updated during the simulation. For non-time-varying potentials, the time argument may still be useful for internal optimizations, such as managing cached values.

In the simplest and most common case, pairs of sites (atoms or groups) are specified by the user and then, during integration, GROMACS provides the current positions of each pair for the restraint potential to be evaluated. In such a case, the potential can be implemented by overriding evaluate().

Todo:
Template headers can help to build compatible calculation methods with different input requirements. For reference, see https://github.com/kassonlab/sample_restraint
Warning
ABI depends on compile-time value of GMX_DOUBLE, which is usually provided through the build system by target_link_libraries(... Gromacs::libgromacs) in the client's CMakeLists.txt.

Public Member Functions

virtual PotentialPointData evaluate (Vector r1, Vector r2, double t)=0
 Calculate a force vector according to two input positions at a given time. More...
 
virtual void update (gmx::Vector v, gmx::Vector v0, double t)
 Call-back hook for restraint implementations. More...
 
virtual std::vector< int > sites () const =0
 Find out what sites this restraint is configured to act on. More...
 
virtual void bindSession (gmxapi::SessionResources *resources)
 Allow Session-mediated interaction with other resources or workflow elements. More...
 

Member Function Documentation

virtual void gmx::IRestraintPotential::bindSession ( gmxapi::SessionResources *  resources)
inlinevirtual

Allow Session-mediated interaction with other resources or workflow elements.

Parameters
resourcestemporary access to the resources provided by the session for additional configuration.

A module implements this method to receive a handle to resources configured for this particular workflow element.

Todo:
This should be more general than the RestraintPotential interface.
virtual PotentialPointData gmx::IRestraintPotential::evaluate ( Vector  r1,
Vector  r2,
double  t 
)
pure virtual

Calculate a force vector according to two input positions at a given time.

If not overridden by derived class, returns a zero vector.

Parameters
r1position of first site
r2position of second site
tsimulation time in picoseconds
Returns
force vector and potential energy to be applied by calling code.
Todo:
The virtual function call should be replaced by a (table of) function objects retrieved before the run.
virtual std::vector<int> gmx::IRestraintPotential::sites ( ) const
pure virtual

Find out what sites this restraint is configured to act on.

Returns
virtual void gmx::IRestraintPotential::update ( gmx::Vector  v,
gmx::Vector  v0,
double  t 
)
inlinevirtual

Call-back hook for restraint implementations.

An update function to be called on the simulation main rank/thread periodically by the Restraint framework. Receives the same input as the evaluate() method, but is only called on the main rank of a simulation to allow implementation code to be thread-safe without knowing anything about the domain decomposition.

Parameters
vposition of the first site
v0position of the second site
tsimulation time

We give the definition here because we don't want plugins to have to link against libgromacs right now (complicated header maintenance and no API stability guarantees). But once we've had plugin restraints wrap themselves in a Restraint template, we can set update = 0

Todo:
: Provide gmxapi facility for plugin restraints to wrap themselves with a default implementation to let this class be pure virtual.

The documentation for this class was generated from the following file: