Package ffx.potential
Class ForceFieldEnergy
java.lang.Object
ffx.potential.ForceFieldEnergy
- All Implemented Interfaces:
CrystalPotential
,OptimizationInterface
,Potential
,LambdaInterface
- Direct Known Subclasses:
OpenMMEnergy
Compute the potential energy and derivatives of a molecular system described by a force field.
- Since:
- 1.0
- Author:
- Michael J. Schnieders
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
RestrainMode specifies how restrain terms are applied for dual topology calculations.Nested classes/interfaces inherited from interface ffx.numerics.Potential
Potential.STATE, Potential.VARIABLE_TYPE
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final double
Default tolerance for numerical methods of solving constraints.boolean
Indicates only bonded energy terms effected by Lambda should be evaluated.protected boolean
Indicates use of the Lambda state variable.final double
If the absolute value of a gradient component is greater than "maxDebugGradient", verbose logging results.protected final MolecularAssembly
The MolecularAssembly associated with this force field energy.protected double[]
Optimization scaling value to use for each degree of freedom. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
ForceFieldEnergy
(MolecularAssembly molecularAssembly) Constructor for ForceFieldEnergy.protected
ForceFieldEnergy
(MolecularAssembly molecularAssembly, int numThreads) Constructor for ForceFieldEnergy. -
Method Summary
Modifier and TypeMethodDescriptionvoid
applyAllConstraintPositions
(double[] xPrior, double[] xNew) Applies constraints to positionsvoid
applyAllConstraintPositions
(double[] xPrior, double[] xNew, double tol) Applies constraints to positionsvoid
attachExtendedSystem
(ExtendedSystem system) Overwrites current esvSystem if present.boolean
Returns true if dUdL is guaranteed to be zero at 0 and 1.boolean
destroy()
Frees up assets associated with this ForceFieldEnergy, such as worker Threads.double
energy()
energy.double
energy
(boolean gradient, boolean print) Compute the potential energy of the system.double
energy
(double[] x) This method is called repeatedly to compute the function energy.double
energy
(double[] x, boolean verbose) This method is called repeatedly to compute the function energy.double
energyAndGradient
(double[] x, double[] g) This method is called repeatedly to compute the function energy and gradient.double
energyAndGradient
(double[] x, double[] g, boolean verbose) This method is called repeatedly to compute the function energy and gradient.static ForceFieldEnergy
energyFactory
(MolecularAssembly assembly) Static factory method to create a ForceFieldEnergy, possibly via FFX or OpenMM implementations.static ForceFieldEnergy
energyFactory
(MolecularAssembly assembly, int numThreads) Static factory method to create a ForceFieldEnergy, possibly via FFX or OpenMM implementations.double[]
getAcceleration
(double[] acceleration) getAcceleration.Get the AnglePotentialEnergy.Angle[]
getAngles
(AngleType.AngleMode angleMode) Getter for the fieldangles
with onlyAngleMode
angles.Get the AngleTorsionPotentialEnergy.Atom[]
Get all atoms that make up this ForceFieldEnergy.Get the BondPotentialEnergy.Returns a copy of the list of constraints this ForceFieldEnergy has.double[]
getCoordinates
(double[] x) Load the current value of the parameters.Get the Crystal instance that specifies the periodic boundary conditions and symmetry.double
Getter for the fieldcutoffPlusBuffer
.double
Get the 2nd partial derivative of the energy with respect to lambda.double
getdEdL()
Get the partial derivative of the energy with respect to lambda.void
getdEdXdL
(double[] gradients) Get the gradient of dEdL with respect to each parameter.Get the Potential Energy terms that is active.double
getEsvBiasEnergy.getExtendedSystem.getGK()
getGK.double[]
getGradient
(double[] g) Returns the gradient array for this ForceFieldEnergy.Get the ImproperTorsionPotentialEnergy.double
Get the current value of the state variable.boolean
Get the lambdaTerm flag.double[]
getMass()
Get the mass of each degree of freedom.Get the MolecularAssembly associated with this ForceFieldEnergy.int
Get the number of variables being operated on.Get the OutOfPlaneBendPotentialEnergy.Getter for the fieldparallelTeam
.Create a PDB REMARK 3 string containing the potential energy terms.int
getPermanentInteractions.double
Getter for the fieldpermanentMultipoleEnergy
.Get the PiOrbitalTorsionPotentialEnergy.Gets the Platform associated with this force field energy.getPmeNode.double
Getter for the fieldpolarizationEnergy
.double[]
getPreviousAcceleration
(double[] previousAcceleration) getPreviousAcceleration.Get the RestrainDistancePotentialEnergy.Getter for the RestrainGroup field.Get the RestrainPositionPotentialEnergy.Get the RestrainTorsionPotentialEnergy.double[]
Get the problem scaling.double
Getter for the fieldsolvationEnergy
.int
getSolvationInteractions.Get the StretchBendPotentialEnergy.Get the StretchTorsionPotentialEnergy.Get the TorsionPotentialEnergy.Get the TorsionTorsionPotentialEnergy.double
Get the total energy of the systemGet the UreyBradleyPotentialEnergy.double
Getter for the fieldvanDerWaalsEnergy
.int
getVanDerWaalsInteractions.Get the type of all variables.getVdwNode.double[]
getVelocity
(double[] velocity) getVelocity.void
Log bonded energy terms and restraints.void
setAcceleration
(double[] acceleration) setAcceleration.void
setCoordinates
(double[] coords) The coordinate array should only contain active atoms.void
setCrystal
(Crystal crystal) Set the Crystal instance that specifies the periodic boundary conditions and symmetry.void
setCrystal
(Crystal crystal, boolean checkReplicatesCell) Set the boundary conditions for this calculation.void
Set the Potential Energy terms that should be active.void
setLambda
(double lambda) Set the current value of the state variable.void
setLambdaTerm
(boolean lambdaTerm) Set the lambdaTerm flag.void
setPreviousAcceleration
(double[] previousAcceleration) setPreviousAcceleration.void
setPrintOnFailure
(boolean onFail, boolean override) Sets the printOnFailure flag; if override is true, over-rides any existing property.void
setScaling
(double[] scaling) Scale the problem.void
setVelocity
(double[] velocity) setVelocity.toString()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface ffx.numerics.OptimizationInterface
getUnderlyingPotentials, scaleCoordinates, scaleCoordinatesAndGradient, unscaleCoordinates
Methods inherited from interface ffx.numerics.Potential
writeAdditionalRestartInfo
-
Field Details
-
molecularAssembly
The MolecularAssembly associated with this force field energy. -
DEFAULT_CONSTRAINT_TOLERANCE
public static final double DEFAULT_CONSTRAINT_TOLERANCEDefault tolerance for numerical methods of solving constraints.- See Also:
-
lambdaTerm
@FFXProperty(name="lambdaterm", clazz=java.lang.Boolean.class, propertyGroup=PotentialFunctionSelection, defaultValue="false", description="Specifies use of the Lambda state variable.") protected boolean lambdaTermIndicates use of the Lambda state variable. -
lambdaBondedTerms
public boolean lambdaBondedTermsIndicates only bonded energy terms effected by Lambda should be evaluated. -
optimizationScaling
protected double[] optimizationScalingOptimization scaling value to use for each degree of freedom. -
maxDebugGradient
public final double maxDebugGradientIf the absolute value of a gradient component is greater than "maxDebugGradient", verbose logging results.
-
-
Constructor Details
-
ForceFieldEnergy
Constructor for ForceFieldEnergy.- Parameters:
molecularAssembly
- aMolecularAssembly
object.
-
ForceFieldEnergy
Constructor for ForceFieldEnergy.- Parameters:
molecularAssembly
- aMolecularAssembly
object.numThreads
- a int.
-
-
Method Details
-
getMolecularAssembly
Get the MolecularAssembly associated with this ForceFieldEnergy.- Returns:
- a
MolecularAssembly
object.
-
setLambdaTerm
public void setLambdaTerm(boolean lambdaTerm) Set the lambdaTerm flag.- Parameters:
lambdaTerm
- The value to set.
-
getLambdaTerm
public boolean getLambdaTerm()Get the lambdaTerm flag.- Returns:
- lambdaTerm.
-
energyFactory
Static factory method to create a ForceFieldEnergy, possibly via FFX or OpenMM implementations.- Parameters:
assembly
- To create FFE over- Returns:
- a
ForceFieldEnergy
object.
-
energyFactory
Static factory method to create a ForceFieldEnergy, possibly via FFX or OpenMM implementations.- Parameters:
assembly
- To create FFE overnumThreads
- Number of threads to use for FFX energy- Returns:
- A ForceFieldEnergy on some Platform
-
getAtomArray
Get all atoms that make up this ForceFieldEnergy.- Returns:
- An array of Atoms.
-
applyAllConstraintPositions
public void applyAllConstraintPositions(double[] xPrior, double[] xNew) Applies constraints to positions- Parameters:
xPrior
- Prior coodinates.xNew
- New coordinates.
-
applyAllConstraintPositions
public void applyAllConstraintPositions(double[] xPrior, double[] xNew, double tol) Applies constraints to positions- Parameters:
xPrior
- Prior coodinates.xNew
- New coordinates.tol
- Constraint Tolerance.
-
attachExtendedSystem
Overwrites current esvSystem if present. Multiple ExtendedSystems is possible but unnecessary; add all ESVs to one system (per FFE, at least).- Parameters:
system
- aExtendedSystem
object.
-
dEdLZeroAtEnds
public boolean dEdLZeroAtEnds()Returns true if dUdL is guaranteed to be zero at 0 and 1. Default implementation is to return false.Returns true if lambda term is not enabled for this ForceFieldEnergy.
- Specified by:
dEdLZeroAtEnds
in interfaceLambdaInterface
- Returns:
- True if dUdL is guaranteed 0 at endpoints.
-
destroy
public boolean destroy()Frees up assets associated with this ForceFieldEnergy, such as worker Threads.- Specified by:
destroy
in interfaceOptimizationInterface
- Returns:
- If successful in freeing up assets.
-
energy
public double energy()energy.- Returns:
- a double.
-
energy
public double energy(boolean gradient, boolean print) Compute the potential energy of the system.- Parameters:
gradient
- If true, compute the Cartesian coordinate gradient.print
- If true, print the energy terms.- Returns:
- the energy in kcal/mol.
-
energy
public double energy(double[] x) This method is called repeatedly to compute the function energy.- Specified by:
energy
in interfaceOptimizationInterface
- Parameters:
x
- Input parameters.- Returns:
- Function value at
x
.
-
energy
public double energy(double[] x, boolean verbose) This method is called repeatedly to compute the function energy. The verbose flag may not be used by all implementations.- Specified by:
energy
in interfaceOptimizationInterface
- Parameters:
x
- Input parameters.verbose
- Display extra information.- Returns:
- Function value at
x
-
energyAndGradient
public double energyAndGradient(double[] x, double[] g) This method is called repeatedly to compute the function energy and gradient.- Specified by:
energyAndGradient
in interfaceOptimizationInterface
- Parameters:
x
- Input parameters.g
- Output gradients with respect to each parameter.- Returns:
- Function value at
x
.
-
energyAndGradient
public double energyAndGradient(double[] x, double[] g, boolean verbose) This method is called repeatedly to compute the function energy and gradient. The verbose flag may not be used by all implementations.- Specified by:
energyAndGradient
in interfaceOptimizationInterface
- Parameters:
x
- Input parameters.g
- Output gradients with respect to each parameter.verbose
- Display extra information.- Returns:
- Function value at
x
.
-
getAcceleration
public double[] getAcceleration(double[] acceleration) getAcceleration.Returns an array of acceleration values for active atoms.
- Specified by:
getAcceleration
in interfacePotential
- Parameters:
acceleration
- an array of double values.- Returns:
- an array of double values.
-
getAngles
Getter for the fieldangles
with onlyAngleMode
angles.- Parameters:
angleMode
- Only angles of this mode will be returned.- Returns:
- an array of
Angle
objects.
-
getConstraints
Returns a copy of the list of constraints this ForceFieldEnergy has.- Specified by:
getConstraints
in interfacePotential
- Returns:
- Copied list of constraints.
-
getCoordinates
public double[] getCoordinates(double[] x) Load the current value of the parameters. If the supplied array is null or not large enough, a new one should be created. The filled array is returned.- Specified by:
getCoordinates
in interfaceOptimizationInterface
- Parameters:
x
- Supplied array.- Returns:
- The array filled with parameter values.
-
getCrystal
Get the Crystal instance that specifies the periodic boundary conditions and symmetry.Getter for the field
crystal
.- Specified by:
getCrystal
in interfaceCrystalPotential
- Returns:
- a Crystal instance.
-
setCrystal
Set the Crystal instance that specifies the periodic boundary conditions and symmetry.Set the boundary conditions for this calculation.
- Specified by:
setCrystal
in interfaceCrystalPotential
- Parameters:
crystal
- a Crystal instance.
-
getCutoffPlusBuffer
public double getCutoffPlusBuffer()Getter for the fieldcutoffPlusBuffer
.- Returns:
- a double.
-
getEnergyTermState
Get the Potential Energy terms that is active.- Specified by:
getEnergyTermState
in interfacePotential
- Returns:
- the STATE
-
setEnergyTermState
Set the Potential Energy terms that should be active.This method is for the RESPA integrator only.
- Specified by:
setEnergyTermState
in interfacePotential
- Parameters:
state
- include FAST varying energy terms, SLOW varying energy terms or BOTH.
-
getEsvBiasEnergy
public double getEsvBiasEnergy()getEsvBiasEnergy.- Returns:
- a double.
-
getExtendedSystem
getExtendedSystem.- Returns:
- a
ExtendedSystem
object.
-
getGK
getGK.- Returns:
- a
GeneralizedKirkwood
object.
-
getGradient
public double[] getGradient(double[] g) Returns the gradient array for this ForceFieldEnergy.- Parameters:
g
- an array of double.- Returns:
- the gradient array.
-
getLambda
public double getLambda()Get the current value of the state variable.- Specified by:
getLambda
in interfaceLambdaInterface
- Returns:
- state
-
setLambda
public void setLambda(double lambda) Set the current value of the state variable. May be ignored if lambda is not being applied.- Specified by:
setLambda
in interfaceLambdaInterface
- Parameters:
lambda
- a double.
-
getMass
public double[] getMass()Get the mass of each degree of freedom. This is required for molecular dynamics. -
getNumberOfVariables
public int getNumberOfVariables()Get the number of variables being operated on.- Specified by:
getNumberOfVariables
in interfaceOptimizationInterface
- Returns:
- Number of variables.
-
getPDBHeaderString
Create a PDB REMARK 3 string containing the potential energy terms.- Returns:
- a String containing the PDB REMARK 3 formatted energy terms.
-
getParallelTeam
Getter for the fieldparallelTeam
.- Returns:
- a
ParallelTeam
object.
-
getPermanentInteractions
public int getPermanentInteractions()getPermanentInteractions.- Returns:
- a int.
-
getPermanentMultipoleEnergy
public double getPermanentMultipoleEnergy()Getter for the fieldpermanentMultipoleEnergy
.- Returns:
- a double.
-
getPlatform
Gets the Platform associated with this force field energy. For the reference platform, always returns FFX.- Returns:
- A Platform.
-
getPmeNode
getPmeNode.- Returns:
- a
ParticleMeshEwald
object.
-
getPolarizationEnergy
public double getPolarizationEnergy()Getter for the fieldpolarizationEnergy
.- Returns:
- a double.
-
getPreviousAcceleration
public double[] getPreviousAcceleration(double[] previousAcceleration) getPreviousAcceleration.Returns an array of previous acceleration values for active atoms.
- Specified by:
getPreviousAcceleration
in interfacePotential
- Parameters:
previousAcceleration
- an array of double values.- Returns:
- an array of double values.
-
getScaling
public double[] getScaling()Get the problem scaling.- Specified by:
getScaling
in interfaceOptimizationInterface
- Returns:
- The scaling value used for each variable.
-
setScaling
public void setScaling(double[] scaling) Scale the problem. A good choice for optimization is the square root of the median eigenvalue of a typical Hessian.- Specified by:
setScaling
in interfaceOptimizationInterface
- Parameters:
scaling
- The scaling value to use for each variable.
-
getSolvationEnergy
public double getSolvationEnergy()Getter for the fieldsolvationEnergy
.- Returns:
- a double.
-
getSolvationInteractions
public int getSolvationInteractions()getSolvationInteractions.- Returns:
- a int.
-
getTotalEnergy
public double getTotalEnergy()Get the total energy of the system- Specified by:
getTotalEnergy
in interfaceOptimizationInterface
- Returns:
- the total energy
-
getVanDerWaalsEnergy
public double getVanDerWaalsEnergy()Getter for the fieldvanDerWaalsEnergy
.- Returns:
- a double.
-
getVanDerWaalsInteractions
public int getVanDerWaalsInteractions()getVanDerWaalsInteractions.- Returns:
- a int.
-
getVariableTypes
Get the type of all variables.Return a reference to each variables type.
- Specified by:
getVariableTypes
in interfacePotential
- Returns:
- The VARIABLE_TYPE of each variable.
-
getVdwNode
getVdwNode.- Returns:
- a
VanDerWaals
object.
-
getVelocity
public double[] getVelocity(double[] velocity) getVelocity.Returns an array of velocity values for active atoms.
- Specified by:
getVelocity
in interfacePotential
- Parameters:
velocity
- an array of double values.- Returns:
- an array of double values.
-
getd2EdL2
public double getd2EdL2()Get the 2nd partial derivative of the energy with respect to lambda.- Specified by:
getd2EdL2
in interfaceLambdaInterface
- Returns:
- d2EdL2
-
getdEdL
public double getdEdL()Get the partial derivative of the energy with respect to lambda.- Specified by:
getdEdL
in interfaceLambdaInterface
- Returns:
- dEdL
-
getdEdXdL
public void getdEdXdL(double[] gradients) Get the gradient of dEdL with respect to each parameter.- Specified by:
getdEdXdL
in interfaceLambdaInterface
- Parameters:
gradients
- - A double array of length the number of parameters in the model (commonly 3 * number of atoms).
-
setAcceleration
public void setAcceleration(double[] acceleration) setAcceleration.The acceleration array should only contain acceleration data for active atoms.
- Specified by:
setAcceleration
in interfacePotential
- Parameters:
acceleration
- an array of double values.
-
setCoordinates
public void setCoordinates(@Nullable double[] coords) The coordinate array should only contain active atoms.- Specified by:
setCoordinates
in interfaceOptimizationInterface
- Parameters:
coords
- the coordinates to set.
-
setCrystal
Set the boundary conditions for this calculation.- Parameters:
crystal
- Crystal to set.checkReplicatesCell
- Check if a replicates cell must be created.
-
setPreviousAcceleration
public void setPreviousAcceleration(double[] previousAcceleration) setPreviousAcceleration.The previousAcceleration array should only contain previous acceleration data for active atoms.
- Specified by:
setPreviousAcceleration
in interfacePotential
- Parameters:
previousAcceleration
- an array of double values.
-
setPrintOnFailure
public void setPrintOnFailure(boolean onFail, boolean override) Sets the printOnFailure flag; if override is true, over-rides any existing property. Essentially sets the default value of printOnFailure for an algorithm. For example, rotamer optimization will generally run into force field issues in the normal course of execution as it tries unphysical self and pair configurations, so the algorithm should not print out a large number of error PDBs.- Parameters:
onFail
- To setoverride
- Override properties
-
setVelocity
public void setVelocity(double[] velocity) setVelocity.The velocity array should only contain velocity data for active atoms.
- Specified by:
setVelocity
in interfacePotential
- Parameters:
velocity
- an array of double values.
-
toString
-
logBondedTermsAndRestraints
public void logBondedTermsAndRestraints()Log bonded energy terms and restraints. -
getRestrainMode
-
getRestrainGroups
Getter for the RestrainGroup field.- Returns:
- Returns RestrainGroup.
-
getTorsionTorsionPotentialEnergy
Get the TorsionTorsionPotentialEnergy.- Returns:
- The TorsionTorsionPotentialEnergy.
-
getAnglePotentialEnergy
Get the AnglePotentialEnergy.- Returns:
- The AnglePotentialEnergy.
-
getBondPotentialEnergy
Get the BondPotentialEnergy.- Returns:
- The BondPotentialEnergy.
-
getStretchBendPotentialEnergy
Get the StretchBendPotentialEnergy.- Returns:
- The StretchBendPotentialEnergy.
-
getUreyBradleyPotentialEnergy
Get the UreyBradleyPotentialEnergy.- Returns:
- The UreyBradleyPotentialEnergy.
-
getOutOfPlaneBendPotentialEnergy
Get the OutOfPlaneBendPotentialEnergy.- Returns:
- The OutOfPlaneBendPotentialEnergy.
-
getTorsionPotentialEnergy
Get the TorsionPotentialEnergy.- Returns:
- The TorsionPotentialEnergy.
-
getStretchTorsionPotentialEnergy
Get the StretchTorsionPotentialEnergy.- Returns:
- The StretchTorsionPotentialEnergy.
-
getAngleTorsionPotentialEnergy
Get the AngleTorsionPotentialEnergy.- Returns:
- The AngleTorsionPotentialEnergy.
-
getImproperTorsionPotentialEnergy
Get the ImproperTorsionPotentialEnergy.- Returns:
- The ImproperTorsionPotentialEnergy.
-
getPiOrbitalTorsionPotentialEnergy
Get the PiOrbitalTorsionPotentialEnergy.- Returns:
- The PiOrbitalTorsionPotentialEnergy.
-
getRestrainPositionPotentialEnergy
Get the RestrainPositionPotentialEnergy.- Returns:
- The RestrainPositionPotentialEnergy.
-
getRestrainDistancePotentialEnergy
Get the RestrainDistancePotentialEnergy.- Returns:
- The RestrainDistancePotentialEnergy.
-
getRestrainTorsionPotentialEnergy
Get the RestrainTorsionPotentialEnergy.- Returns:
- The RestrainTorsionPotentialEnergy.
-