User defined molecular mechanics force terms

These classes are used with DuMMForceFieldSubsystem to permit user-defined functional forms for bonded terms. More...

Classes
class	SimTK::DuMM::CustomBondStretch
	Abstract base class for custom bond stretch terms, that is, functional forms that apply a distance-based force along a 1-2 bond between a pair of atoms. More...
class	SimTK::DuMM::CustomBondBend
	Abstract base class for custom bond bend functions, that is, functional forms that apply an angle-based torque between the two lines formed by a 1-2-3 triple of bonded atoms. More...
class	SimTK::DuMM::CustomBondTorsion
	Abstract base class for custom torsion functions, that is, functional forms that apply a dihedral-angle based torque about the middle bond of a 1-2-3-4 quadruple of bonded atoms. More...

---

Detailed Description

These classes are used with DuMMForceFieldSubsystem to permit user-defined functional forms for bonded terms.

Basic features

• You can make custom bond stretch, bond bend, and bond torsion terms.
• Each term is represented by an abstract base class with a virtual destructor.
• You write one scalar method to calculate energy and one to calculate force.
• You can associate multiple custom bond terms with the same atom classes; in that case the terms are additive.
• You do not have to supply terms for every combination of atom classes that appears in your system; your methods will be called only for combinations for which you have actually supplied a term.
• It is your responsibility to ensure that your force (or torque) method returns the negative gradient of your energy method.

Notes

• DuMM may skip calling your function if the atoms all reside on the same body; that can't affect the motion, but note that the internal energy will not be counted in that case.
• DuMM will take over ownership of the concrete object you supply to its defineCustomBond...() methods; don't delete them yourself.

AmberTorsion example

This demonstrates how the built-in Amber force might be applied as a custom torsion. This is a toy example because this particular form is already built into DuMMForceFieldSubsystem.

 class AmberTorsion : public DuMM::CustomBondTorsion {
 public:
    AmberTorsion(Real amplitudeInKJ, Real phaseInRad, int periodicity)
    :   amplitude(amplitudeInKJ), phase(phaseInRad), periodicity(periodicity) {}
 
    Real calcEnergy(Real dihedralAngleInRad) {
        return amplitude * 
                  ( 1 + std::cos(periodicity * dihedralAngleInRad - phase) );
    }

    // Note: this is MINUS the gradient of the energy function!
    Real calcTorque(Real dihedralAngleInRad) {
        return periodicity * amplitude * 
                  std::sin(periodicity * dihedralAngleInRad - phase);
    }

 private:
    Real amplitude;       // in KJ/mol
    Real phase;           // in radians
    int  periodicity;
 };
 
 #include "SimTKmolmodel.h"
 int main() {
     DuMMForceFieldSubsystem dumm;
     dumm.loadAmber99Parameters();
     // torsion for aliphatic H-C-C-H torsions like those in ethane
     dumm.defineCustomTorsion(
         dumm.getAtomClassIndex("HC"),
         dumm.getAtomClassIndex("CT"),
         dumm.getAtomClassIndex("CT"),
         dumm.getAtomClassIndex("HC"),
         new AmberTorsion(0.150*DuMM::Kcal2KJ, 0*DuMM::Deg2Rad, 3));
     ...
 }