OpenMM

This class implements nonbonded interactions between particles, including a Coulomb force to represent electrostatics and a LennardJones force to represent van der Waals interactions. More...
#include <NonbondedForce.h>
Public Types  
enum  NonbondedMethod { NoCutoff = 0, CutoffNonPeriodic = 1, CutoffPeriodic = 2, Ewald = 3, PME = 4 } 
This is an enumeration of the different methods that may be used for handling long range nonbonded forces. More...  
Public Member Functions  
NonbondedForce ()  
Create a NonbondedForce. More...  
int  getNumParticles () const 
Get the number of particles for which force field parameters have been defined. More...  
int  getNumExceptions () const 
Get the number of special interactions that should be calculated differently from other interactions. More...  
NonbondedMethod  getNonbondedMethod () const 
Get the method used for handling long range nonbonded interactions. More...  
void  setNonbondedMethod (NonbondedMethod method) 
Set the method used for handling long range nonbonded interactions. More...  
double  getCutoffDistance () const 
Get the cutoff distance (in nm) being used for nonbonded interactions. More...  
void  setCutoffDistance (double distance) 
Set the cutoff distance (in nm) being used for nonbonded interactions. More...  
bool  getUseSwitchingFunction () const 
Get whether a switching function is applied to the LennardJones interaction. More...  
void  setUseSwitchingFunction (bool use) 
Set whether a switching function is applied to the LennardJones interaction. More...  
double  getSwitchingDistance () const 
Get the distance at which the switching function begins to reduce the LennardJones interaction. More...  
void  setSwitchingDistance (double distance) 
Set the distance at which the switching function begins to reduce the LennardJones interaction. More...  
double  getReactionFieldDielectric () const 
Get the dielectric constant to use for the solvent in the reaction field approximation. More...  
void  setReactionFieldDielectric (double dielectric) 
Set the dielectric constant to use for the solvent in the reaction field approximation. More...  
double  getEwaldErrorTolerance () const 
Get the error tolerance for Ewald summation. More...  
void  setEwaldErrorTolerance (double tol) 
Set the error tolerance for Ewald summation. More...  
void  getPMEParameters (double &alpha, int &nx, int &ny, int &nz) const 
Get the parameters to use for PME calculations. More...  
void  setPMEParameters (double alpha, int nx, int ny, int nz) 
Set the parameters to use for PME calculations. More...  
int  addParticle (double charge, double sigma, double epsilon) 
Add the nonbonded force parameters for a particle. More...  
void  getParticleParameters (int index, double &charge, double &sigma, double &epsilon) const 
Get the nonbonded force parameters for a particle. More...  
void  setParticleParameters (int index, double charge, double sigma, double epsilon) 
Set the nonbonded force parameters for a particle. More...  
int  addException (int particle1, int particle2, double chargeProd, double sigma, double epsilon, bool replace=false) 
Add an interaction to the list of exceptions that should be calculated differently from other interactions. More...  
void  getExceptionParameters (int index, int &particle1, int &particle2, double &chargeProd, double &sigma, double &epsilon) const 
Get the force field parameters for an interaction that should be calculated differently from others. More...  
void  setExceptionParameters (int index, int particle1, int particle2, double chargeProd, double sigma, double epsilon) 
Set the force field parameters for an interaction that should be calculated differently from others. More...  
void  createExceptionsFromBonds (const std::vector< std::pair< int, int > > &bonds, double coulomb14Scale, double lj14Scale) 
Identify exceptions based on the molecular topology. More...  
bool  getUseDispersionCorrection () const 
Get whether to add a contribution to the energy that approximately represents the effect of LennardJones interactions beyond the cutoff distance. More...  
void  setUseDispersionCorrection (bool useCorrection) 
Set whether to add a contribution to the energy that approximately represents the effect of LennardJones interactions beyond the cutoff distance. More...  
int  getReciprocalSpaceForceGroup () const 
Get the force group that reciprocal space interactions for Ewald or PME are included in. More...  
void  setReciprocalSpaceForceGroup (int group) 
Set the force group that reciprocal space interactions for Ewald or PME are included in. More...  
void  updateParametersInContext (Context &context) 
Update the particle and exception parameters in a Context to match those stored in this Force object. More...  
Public Member Functions inherited from Force  
Force ()  
virtual  ~Force () 
int  getForceGroup () const 
Get the force group this Force belongs to. More...  
void  setForceGroup (int group) 
Set the force group this Force belongs to. More...  
Protected Member Functions  
ForceImpl *  createImpl () const 
When a Context is created, it invokes this method on each Force in the System. More...  
Protected Member Functions inherited from Force  
ForceImpl &  getImplInContext (Context &context) 
Get the ForceImpl corresponding to this Force in a Context. More...  
ContextImpl &  getContextImpl (Context &context) 
Get the ContextImpl corresponding to a Context. More...  
This class implements nonbonded interactions between particles, including a Coulomb force to represent electrostatics and a LennardJones force to represent van der Waals interactions.
It optionally supports periodic boundary conditions and cutoffs for long range interactions. LennardJones interactions are calculated with the LorentzBerthelot combining rule: it uses the arithmetic mean of the sigmas and the geometric mean of the epsilons for the two interacting particles.
To use this class, create a NonbondedForce object, then call addParticle() once for each particle in the System to define its parameters. The number of particles for which you define nonbonded parameters must be exactly equal to the number of particles in the System, or else an exception will be thrown when you try to create a Context. After a particle has been added, you can modify its force field parameters by calling setParticleParameters(). This will have no effect on Contexts that already exist unless you call updateParametersInContext().
NonbondedForce also lets you specify "exceptions", particular pairs of particles whose interactions should be computed based on different parameters than those defined for the individual particles. This can be used to completely exclude certain interactions from the force calculation, or to alter how they interact with each other.
Many molecular force fields omit Coulomb and LennardJones interactions between particles separated by one or two bonds, while using modified parameters for those separated by three bonds (known as "14 interactions"). This class provides a convenience method for this case called createExceptionsFromBonds(). You pass to it a list of bonds and the scale factors to use for 14 interactions. It identifies all pairs of particles which are separated by 1, 2, or 3 bonds, then automatically creates exceptions for them.
When using a cutoff, by default LennardJones interactions are sharply truncated at the cutoff distance. Optionally you can instead use a switching function to make the interaction smoothly go to zero over a finite distance range. To enable this, call setUseSwitchingFunction(). You must also call setSwitchingDistance() to specify the distance at which the interaction should begin to decrease. The switching distance must be less than the cutoff distance.
Another optional feature of this class (enabled by default) is to add a contribution to the energy which approximates the effect of all LennardJones interactions beyond the cutoff in a periodic system. When running a simulation at constant pressure, this can improve the quality of the result. Call setUseDispersionCorrection() to set whether this should be used.
enum NonbondedMethod 
This is an enumeration of the different methods that may be used for handling long range nonbonded forces.
NonbondedForce  (  ) 
Create a NonbondedForce.
int addException  (  int  particle1, 
int  particle2,  
double  chargeProd,  
double  sigma,  
double  epsilon,  
bool  replace = false 

) 
Add an interaction to the list of exceptions that should be calculated differently from other interactions.
If chargeProd and epsilon are both equal to 0, this will cause the interaction to be completely omitted from force and energy calculations.
In many cases, you can use createExceptionsFromBonds() rather than adding each exception explicitly.
particle1  the index of the first particle involved in the interaction 
particle2  the index of the second particle involved in the interaction 
chargeProd  the scaled product of the atomic charges (i.e. the strength of the Coulomb interaction), measured in units of the proton charge squared 
sigma  the sigma parameter of the LennardJones potential (corresponding to the van der Waals radius of the particle), measured in nm 
epsilon  the epsilon parameter of the LennardJones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol 
replace  determines the behavior if there is already an exception for the same two particles. If true, the existing one is replaced. If false, an exception is thrown. 
int addParticle  (  double  charge, 
double  sigma,  
double  epsilon  
) 
Add the nonbonded force parameters for a particle.
This should be called once for each particle in the System. When it is called for the i'th time, it specifies the parameters for the i'th particle. For calculating the LennardJones interaction between two particles, the arithmetic mean of the sigmas and the geometric mean of the epsilons for the two interacting particles is used (the LorentzBerthelot combining rule).
charge  the charge of the particle, measured in units of the proton charge 
sigma  the sigma parameter of the LennardJones potential (corresponding to the van der Waals radius of the particle), measured in nm 
epsilon  the epsilon parameter of the LennardJones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol 
void createExceptionsFromBonds  (  const std::vector< std::pair< int, int > > &  bonds, 
double  coulomb14Scale,  
double  lj14Scale  
) 
Identify exceptions based on the molecular topology.
Particles which are separated by one or two bonds are set to not interact at all, while pairs of particles separated by three bonds (known as "14 interactions") have their Coulomb and LennardJones interactions reduced by a fixed factor.
bonds  the set of bonds based on which to construct exceptions. Each element specifies the indices of two particles that are bonded to each other. 
coulomb14Scale  pairs of particles separated by three bonds will have the strength of their Coulomb interaction multiplied by this factor 
lj14Scale  pairs of particles separated by three bonds will have the strength of their LennardJones interaction multiplied by this factor 

protectedvirtual 
double getCutoffDistance  (  )  const 
Get the cutoff distance (in nm) being used for nonbonded interactions.
If the NonbondedMethod in use is NoCutoff, this value will have no effect.
double getEwaldErrorTolerance  (  )  const 
Get the error tolerance for Ewald summation.
This corresponds to the fractional error in the forces which is acceptable. This value is used to select the reciprocal space cutoff and separation parameter so that the average error level will be less than the tolerance. There is not a rigorous guarantee that all forces on all atoms will be less than the tolerance, however.
For PME calculations, if setPMEParameters() is used to set alpha to something other than 0, this value is ignored.
void getExceptionParameters  (  int  index, 
int &  particle1,  
int &  particle2,  
double &  chargeProd,  
double &  sigma,  
double &  epsilon  
)  const 
Get the force field parameters for an interaction that should be calculated differently from others.
index  the index of the interaction for which to get parameters 
particle1  the index of the first particle involved in the interaction 
particle2  the index of the second particle involved in the interaction 
chargeProd  the scaled product of the atomic charges (i.e. the strength of the Coulomb interaction), measured in units of the proton charge squared 
sigma  the sigma parameter of the LennardJones potential (corresponding to the van der Waals radius of the particle), measured in nm 
epsilon  the epsilon parameter of the LennardJones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol 
NonbondedMethod getNonbondedMethod  (  )  const 
Get the method used for handling long range nonbonded interactions.

inline 
Get the number of special interactions that should be calculated differently from other interactions.

inline 
Get the number of particles for which force field parameters have been defined.
void getParticleParameters  (  int  index, 
double &  charge,  
double &  sigma,  
double &  epsilon  
)  const 
Get the nonbonded force parameters for a particle.
index  the index of the particle for which to get parameters 
charge  the charge of the particle, measured in units of the proton charge 
sigma  the sigma parameter of the LennardJones potential (corresponding to the van der Waals radius of the particle), measured in nm 
epsilon  the epsilon parameter of the LennardJones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol 
void getPMEParameters  (  double &  alpha, 
int &  nx,  
int &  ny,  
int &  nz  
)  const 
Get the parameters to use for PME calculations.
If alpha is 0 (the default), these parameters are ignored and instead their values are chosen based on the Ewald error tolerance.
alpha  the separation parameter 
nx  the number of grid points along the X axis 
ny  the number of grid points along the Y axis 
nz  the number of grid points along the Z axis 
double getReactionFieldDielectric  (  )  const 
Get the dielectric constant to use for the solvent in the reaction field approximation.
int getReciprocalSpaceForceGroup  (  )  const 
Get the force group that reciprocal space interactions for Ewald or PME are included in.
This allows multiple time step integrators to evaluate direct and reciprocal space interactions at different intervals: getForceGroup() specifies the group for direct space, and getReciprocalSpaceForceGroup() specifies the group for reciprocal space. If this is 1 (the default value), the same force group is used for reciprocal space as for direct space.
double getSwitchingDistance  (  )  const 
Get the distance at which the switching function begins to reduce the LennardJones interaction.
This must be less than the cutoff distance.

inline 
Get whether to add a contribution to the energy that approximately represents the effect of LennardJones interactions beyond the cutoff distance.
The energy depends on the volume of the periodic box, and is only applicable when periodic boundary conditions are used. When running simulations at constant pressure, adding this contribution can improve the quality of results.
bool getUseSwitchingFunction  (  )  const 
Get whether a switching function is applied to the LennardJones interaction.
If the nonbonded method is set to NoCutoff, this option is ignored.
void setCutoffDistance  (  double  distance  ) 
Set the cutoff distance (in nm) being used for nonbonded interactions.
If the NonbondedMethod in use is NoCutoff, this value will have no effect.
distance  the cutoff distance, measured in nm 
void setEwaldErrorTolerance  (  double  tol  ) 
Set the error tolerance for Ewald summation.
This corresponds to the fractional error in the forces which is acceptable. This value is used to select the reciprocal space cutoff and separation parameter so that the average error level will be less than the tolerance. There is not a rigorous guarantee that all forces on all atoms will be less than the tolerance, however.
For PME calculations, if setPMEParameters() is used to set alpha to something other than 0, this value is ignored.
void setExceptionParameters  (  int  index, 
int  particle1,  
int  particle2,  
double  chargeProd,  
double  sigma,  
double  epsilon  
) 
Set the force field parameters for an interaction that should be calculated differently from others.
If chargeProd and epsilon are both equal to 0, this will cause the interaction to be completely omitted from force and energy calculations.
index  the index of the interaction for which to get parameters 
particle1  the index of the first particle involved in the interaction 
particle2  the index of the second particle involved in the interaction 
chargeProd  the scaled product of the atomic charges (i.e. the strength of the Coulomb interaction), measured in units of the proton charge squared 
sigma  the sigma parameter of the LennardJones potential (corresponding to the van der Waals radius of the particle), measured in nm 
epsilon  the epsilon parameter of the LennardJones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol 
void setNonbondedMethod  (  NonbondedMethod  method  ) 
Set the method used for handling long range nonbonded interactions.
void setParticleParameters  (  int  index, 
double  charge,  
double  sigma,  
double  epsilon  
) 
Set the nonbonded force parameters for a particle.
When calculating the LennardJones interaction between two particles, it uses the arithmetic mean of the sigmas and the geometric mean of the epsilons for the two interacting particles (the LorentzBerthelot combining rule).
index  the index of the particle for which to set parameters 
charge  the charge of the particle, measured in units of the proton charge 
sigma  the sigma parameter of the LennardJones potential (corresponding to the van der Waals radius of the particle), measured in nm 
epsilon  the epsilon parameter of the LennardJones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol 
void setPMEParameters  (  double  alpha, 
int  nx,  
int  ny,  
int  nz  
) 
Set the parameters to use for PME calculations.
If alpha is 0 (the default), these parameters are ignored and instead their values are chosen based on the Ewald error tolerance.
alpha  the separation parameter 
nx  the number of grid points along the X axis 
ny  the number of grid points along the Y axis 
nz  the number of grid points along the Z axis 
void setReactionFieldDielectric  (  double  dielectric  ) 
Set the dielectric constant to use for the solvent in the reaction field approximation.
void setReciprocalSpaceForceGroup  (  int  group  ) 
Set the force group that reciprocal space interactions for Ewald or PME are included in.
This allows multiple time step integrators to evaluate direct and reciprocal space interactions at different intervals: setForceGroup() specifies the group for direct space, and setReciprocalSpaceForceGroup() specifies the group for reciprocal space. If this is 1 (the default value), the same force group is used for reciprocal space as for direct space.
group  the group index. Legal values are between 0 and 31 (inclusive), or 1 to use the same force group that is specified for direct space. 
void setSwitchingDistance  (  double  distance  ) 
Set the distance at which the switching function begins to reduce the LennardJones interaction.
This must be less than the cutoff distance.

inline 
Set whether to add a contribution to the energy that approximately represents the effect of LennardJones interactions beyond the cutoff distance.
The energy depends on the volume of the periodic box, and is only applicable when periodic boundary conditions are used. When running simulations at constant pressure, adding this contribution can improve the quality of results.
void setUseSwitchingFunction  (  bool  use  ) 
Set whether a switching function is applied to the LennardJones interaction.
If the nonbonded method is set to NoCutoff, this option is ignored.
void updateParametersInContext  (  Context &  context  ) 
Update the particle and exception parameters in a Context to match those stored in this Force object.
This method provides an efficient method to update certain parameters in an existing Context without needing to reinitialize it. Simply call setParticleParameters() and setExceptionParameters() to modify this object's parameters, then call updateParametersInState() to copy them over to the Context.
This method has several limitations. The only information it updates is the parameters of particles and exceptions. All other aspects of the Force (the nonbonded method, the cutoff distance, etc.) are unaffected and can only be changed by reinitializing the Context. Furthermore, only the chargeProd, sigma, and epsilon values of an exception can be changed; the pair of particles involved in the exception cannot change. Finally, this method cannot be used to add new particles or exceptions, only to change the parameters of existing ones.