Package ffx.potential

Class ForceFieldEnergy

java.lang.Object
ffx.potential.ForceFieldEnergy
All Implemented Interfaces:
CrystalPotential, OptimizationInterface, Potential, LambdaInterface
Direct Known Subclasses:
OpenMMEnergy
public class ForceFieldEnergy extends Object implements CrystalPotential, LambdaInterface
Compute the potential energy and derivatives of a molecular system described by a force field.
Since:
1.0
Author:
Michael J. Schnieders

  • Field Details

    • DEFAULT_CONSTRAINT_TOLERANCE

      public static final double DEFAULT_CONSTRAINT_TOLERANCE
      Default tolerance for numerical methods of solving constraints.
      See Also:

    • molecularAssembly

      protected final MolecularAssembly molecularAssembly
      The MolecularAssembly associated with this force field energy.

    • maxDebugGradient

      public final double maxDebugGradient
      If the absolute value of a gradient component is greater than "maxDebugGradient", verbose logging results.

    • lambdaTerm

      @FFXProperty(name="lambdaterm", clazz=java.lang.Boolean.class, propertyGroup=PotentialFunctionSelection, defaultValue="false", description="Specifies use of the Lambda state variable.") protected boolean lambdaTerm
      Indicates use of the Lambda state variable.

    • optimizationScaling

      protected double[] optimizationScaling
      Optimization scaling value to use for each degree of freedom.

    • lambdaBondedTerms

      public boolean lambdaBondedTerms
      Indicates only bonded energy terms effected by Lambda should be evaluated.

  • Constructor Details

    • ForceFieldEnergy

      protected ForceFieldEnergy(MolecularAssembly molecularAssembly)
      Constructor for ForceFieldEnergy.
      Parameters:
      molecularAssembly - a MolecularAssembly object.

    • ForceFieldEnergy

      protected ForceFieldEnergy(MolecularAssembly molecularAssembly, int numThreads)
      Constructor for ForceFieldEnergy.
      Parameters:
      molecularAssembly - a MolecularAssembly object.
      numThreads - a int.

  • Method Details

    • energyFactory

      public static ForceFieldEnergy energyFactory(MolecularAssembly assembly)
      Static factory method to create a ForceFieldEnergy, possibly via FFX or OpenMM implementations.
      Parameters:
      assembly - To create FFE over
      Returns:
      a ForceFieldEnergy object.

    • energyFactory

      public static ForceFieldEnergy energyFactory(MolecularAssembly assembly, int numThreads)
      Static factory method to create a ForceFieldEnergy, possibly via FFX or OpenMM implementations.
      Parameters:
      assembly - To create FFE over
      numThreads - Number of threads to use for FFX energy
      Returns:
      A ForceFieldEnergy on some Platform

    • 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

      public void attachExtendedSystem(ExtendedSystem system)
      Overwrites current esvSystem if present. Multiple ExtendedSystems is possible but unnecessary; add all ESVs to one system (per FFE, at least).
      Parameters:
      system - a ExtendedSystem 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 interface LambdaInterface
      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 interface OptimizationInterface
      Returns:
      If successful in freeing up assets.

    • energy

      public double energy()
      energy.
      Returns:
      a double.

    • energy

      public double energy(boolean gradient, boolean print)

      energy

    • energy

      public double energy(double[] x)
      This method is called repeatedly to compute the function energy.
      Specified by:
      energy in interface OptimizationInterface
      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 interface OptimizationInterface
      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 interface OptimizationInterface
      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 interface OptimizationInterface
      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 interface Potential
      Parameters:
      acceleration - an array of
      invalid reference 
      double
      objects.
      Returns:
      an array of
      invalid reference 
      double
      objects.

    • getAngleEnergy

      public double getAngleEnergy()
      Getter for the field angleEnergy.
      Returns:
      a double.

    • getAngleTorsionEnergy

      public double getAngleTorsionEnergy()
      Getter for the field angleTorsionEnergy.
      Returns:
      a double.

    • getAngleTorsions

      public AngleTorsion[] getAngleTorsions()
      Getter for the field angleTorsions.
      Returns:
      an array of AngleTorsion objects.

    • getAngles

      public Angle[] getAngles()
      Getter for the field angles. Both normal and in-plane angles are returned.
      Returns:
      an array of Angle objects.

    • getAngleEnergyString

      public String getAngleEnergyString()

    • getInPlaneAngleEnergyString

      public String getInPlaneAngleEnergyString()

    • getAngles

      public Angle[] getAngles(AngleType.AngleMode angleMode)
      Getter for the field angles with only AngleMode angles.
      Parameters:
      angleMode - Only angles of this mode will be returned.
      Returns:
      an array of Angle objects.

    • getNeutralNetworkEnergy

      public double getNeutralNetworkEnergy()
      Getter for the field nnEnergy.
      Returns:
      a double.

    • getBondEnergy

      public double getBondEnergy()
      Getter for the field bondEnergy.
      Returns:
      a double.

    • getBonds

      public Bond[] getBonds()
      Getter for the field bonds.
      Returns:
      an array of Bond objects.

    • getBondEnergyString

      public String getBondEnergyString()

    • getCavitationEnergy

      public double getCavitationEnergy()
      getCavitationEnergy.
      Returns:
      a double.

    • getConstraints

      public List<Constraint> getConstraints()
      Returns a copy of the list of constraints this ForceFieldEnergy has.
      Specified by:
      getConstraints in interface Potential
      Returns:
      Copied list of constraints.

    • getRestrainPositions

      public List<RestrainPosition> getRestrainPositions()
      Getter for the field coordRestraints.
      Returns:
      a List object.

    • 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 interface OptimizationInterface
      Parameters:
      x - Supplied array.
      Returns:
      The array filled with parameter values.

    • getCrystal

      public Crystal getCrystal()
      Get the Crystal instance that specifies the periodic boundary conditions and symmetry.

      Getter for the field crystal.

      Specified by:
      getCrystal in interface CrystalPotential
      Returns:
      a Crystal instance.

    • setCrystal

      public void setCrystal(Crystal crystal)
      Set the Crystal instance that specifies the periodic boundary conditions and symmetry.

      Set the boundary conditions for this calculation.

      Specified by:
      setCrystal in interface CrystalPotential
      Parameters:
      crystal - a Crystal instance.

    • getCutoffPlusBuffer

      public double getCutoffPlusBuffer()
      Getter for the field cutoffPlusBuffer.
      Returns:
      a double.

    • getDispersionEnergy

      public double getDispersionEnergy()
      getDispersionEnergy.
      Returns:
      a double.

    • getElectrostaticEnergy

      public double getElectrostaticEnergy()
      getElectrostaticEnergy.
      Returns:
      a double.

    • getEnergyTermState

      public Potential.STATE getEnergyTermState()
      Get the Potential Energy terms that is active.
      Specified by:
      getEnergyTermState in interface Potential
      Returns:
      the STATE

    • setEnergyTermState

      public void setEnergyTermState(Potential.STATE state)
      Set the Potential Energy terms that should be active.

      This method is for the RESPA integrator only.

      Specified by:
      setEnergyTermState in interface Potential
      Parameters:
      state - include FAST varying energy terms, SLOW varying energy terms or BOTH.

    • getEsvBiasEnergy

      public double getEsvBiasEnergy()
      getEsvBiasEnergy.
      Returns:
      a double.

    • getExtendedSystem

      public ExtendedSystem getExtendedSystem()
      getExtendedSystem.
      Returns:
      a ExtendedSystem object.

    • getGK

      public GeneralizedKirkwood getGK()
      getGK.
      Returns:
      a GeneralizedKirkwood object.

    • getGKEnergy

      public double getGKEnergy()
      getGKEnergy.
      Returns:
      a double.

    • getGradient

      public double[] getGradient(double[] g)
      getGradient
      Parameters:
      g - an array of double.
      Returns:
      an array of
      invalid reference 
      double
      objects.

    • getImproperTorsionEnergy

      public double getImproperTorsionEnergy()
      Getter for the field improperTorsionEnergy.
      Returns:
      a double.

    • getImproperTorsions

      public ImproperTorsion[] getImproperTorsions()
      Getter for the field improperTorsions.
      Returns:
      an array of ImproperTorsion objects.

    • getLambda

      public double getLambda()
      Get the current value of the state variable.
      Specified by:
      getLambda in interface LambdaInterface
      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 interface LambdaInterface
      Parameters:
      lambda - a double.

    • getMass

      public double[] getMass()
      Get the mass of each degree of freedom. This is required for molecular dynamics.
      Specified by:
      getMass in interface Potential
      Returns:
      The mass of each degree of freedom.

    • getNumberOfVariables

      public int getNumberOfVariables()
      Get the number of variables being operated on.
      Specified by:
      getNumberOfVariables in interface OptimizationInterface
      Returns:
      Number of variables.

    • getNumberofAngleTorsions

      public int getNumberofAngleTorsions()
      getNumberofAngleTorsions.
      Returns:
      a int.

    • getNumberofAngles

      public int getNumberofAngles()
      getNumberofAngles.
      Returns:
      a int.

    • getNumberofBonds

      public int getNumberofBonds()
      getNumberofBonds.
      Returns:
      a int.

    • getNumberofImproperTorsions

      public int getNumberofImproperTorsions()
      getNumberofImproperTorsions.
      Returns:
      a int.

    • getNumberofOutOfPlaneBends

      public int getNumberofOutOfPlaneBends()
      getNumberofOutOfPlaneBends.
      Returns:
      a int.

    • getNumberofPiOrbitalTorsions

      public int getNumberofPiOrbitalTorsions()
      getNumberofPiOrbitalTorsions.
      Returns:
      a int.

    • getNumberofStretchBends

      public int getNumberofStretchBends()
      getNumberofStretchBends.
      Returns:
      a int.

    • getNumberofStretchTorsions

      public int getNumberofStretchTorsions()
      getNumberofStretchTorsions.
      Returns:
      a int.

    • getNumberofTorsionTorsions

      public int getNumberofTorsionTorsions()
      getNumberofTorsionTorsions.
      Returns:
      a int.

    • getNumberofTorsions

      public int getNumberofTorsions()
      getNumberofTorsions.
      Returns:
      a int.

    • getNumberofUreyBradleys

      public int getNumberofUreyBradleys()
      getNumberofUreyBradleys.
      Returns:
      a int.

    • getOutOfPlaneBendEnergy

      public double getOutOfPlaneBendEnergy()
      Getter for the field outOfPlaneBendEnergy.
      Returns:
      a double.

    • getOutOfPlaneBends

      public OutOfPlaneBend[] getOutOfPlaneBends()
      Getter for the field outOfPlaneBends.
      Returns:
      an array of OutOfPlaneBend objects.

    • getOutOfPlaneEnergyString

      public String getOutOfPlaneEnergyString()

    • getPDBHeaderString

      public String getPDBHeaderString()
      getPDBHeaderString
      Returns:
      a String object.

    • getParallelTeam

      public ParallelTeam getParallelTeam()
      Getter for the field parallelTeam.
      Returns:
      a ParallelTeam object.

    • getPermanentInteractions

      public int getPermanentInteractions()
      getPermanentInteractions.
      Returns:
      a int.

    • getPermanentMultipoleEnergy

      public double getPermanentMultipoleEnergy()
      Getter for the field permanentMultipoleEnergy.
      Returns:
      a double.

    • getPermanentRealSpaceEnergy

      public double getPermanentRealSpaceEnergy()
      Getter for the field permanentRealSpaceEnergy.
      Returns:
      a double.

    • getPermanentReciprocalMpoleEnergy

      public double getPermanentReciprocalMpoleEnergy()
      getPermanentReciprocalMpoleEnergy.
      Returns:
      a double.

    • getPermanentReciprocalSelfEnergy

      public double getPermanentReciprocalSelfEnergy()
      getPermanentReciprocalSelfEnergy.
      Returns:
      a double.

    • getPiOrbitalTorsionEnergy

      public double getPiOrbitalTorsionEnergy()
      Getter for the field piOrbitalTorsionEnergy.
      Returns:
      a double.

    • getPiOrbitalTorsions

      public PiOrbitalTorsion[] getPiOrbitalTorsions()
      Getter for the field piOrbitalTorsions.
      Returns:
      an array of PiOrbitalTorsion objects.

    • getPiOrbitalTorsionEnergyString

      public String getPiOrbitalTorsionEnergyString()

    • getPlatform

      public Platform getPlatform()
      Gets the Platform associated with this force field energy. For the reference platform, always returns FFX.
      Returns:
      A Platform.

    • getPmeNode

      public ParticleMeshEwald getPmeNode()
      getPmeNode.
      Returns:
      a ParticleMeshEwald object.

    • getPolarizationEnergy

      public double getPolarizationEnergy()
      Getter for the field polarizationEnergy.
      Returns:
      a double.

    • getPreviousAcceleration

      public double[] getPreviousAcceleration(double[] previousAcceleration)
      getPreviousAcceleration.

      Returns an array of previous acceleration values for active atoms.

      Specified by:
      getPreviousAcceleration in interface Potential
      Parameters:
      previousAcceleration - an array of
      invalid reference 
      double
      objects.
      Returns:
      an array of
      invalid reference 
      double
      objects.

    • getRelativeSolvationEnergy

      public double getRelativeSolvationEnergy()
      Getter for the field relativeSolvationEnergy.
      Returns:
      a double.

    • getScaling

      public double[] getScaling()
      Get the problem scaling.
      Specified by:
      getScaling in interface OptimizationInterface
      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 interface OptimizationInterface
      Parameters:
      scaling - The scaling value to use for each variable.

    • getSolvationEnergy

      public double getSolvationEnergy()
      Getter for the field solvationEnergy.
      Returns:
      a double.

    • getSolvationInteractions

      public int getSolvationInteractions()
      getSolvationInteractions.
      Returns:
      a int.

    • getStrenchBendEnergy

      public double getStrenchBendEnergy()
      getStrenchBendEnergy.
      Returns:
      a double.

    • getStretchBends

      public StretchBend[] getStretchBends()
      Getter for the field stretchBends.
      Returns:
      an array of StretchBend objects.

    • getStretchBendEnergyString

      public String getStretchBendEnergyString()

    • getStretchTorsionEnergy

      public double getStretchTorsionEnergy()
      Getter for the field stretchTorsionEnergy.
      Returns:
      a double.

    • getStretchTorsions

      public StretchTorsion[] getStretchTorsions()
      Getter for the field stretchTorsions.
      Returns:
      an array of StretchTorsion objects.

    • getTorsionEnergy

      public double getTorsionEnergy()
      Getter for the field torsionEnergy.
      Returns:
      a double.

    • getTorsionTorsionEnergy

      public double getTorsionTorsionEnergy()
      Getter for the field torsionTorsionEnergy.
      Returns:
      a double.

    • getTorsionTorsions

      public TorsionTorsion[] getTorsionTorsions()
      Getter for the field torsionTorsions.
      Returns:
      an array of TorsionTorsion objects.

    • getTorsions

      public Torsion[] getTorsions()
      Getter for the field torsions.
      Returns:
      an array of Torsion objects.

    • getTotalElectrostaticEnergy

      public double getTotalElectrostaticEnergy()
      getTotalElectrostaticEnergy.
      Returns:
      a double.

    • getTotalEnergy

      public double getTotalEnergy()
      Get the total energy of the system
      Specified by:
      getTotalEnergy in interface OptimizationInterface
      Returns:
      the total energy

    • getUreyBradleyEnergy

      public double getUreyBradleyEnergy()
      Getter for the field ureyBradleyEnergy.
      Returns:
      a double.

    • getUreyBradleys

      public UreyBradley[] getUreyBradleys()
      Getter for the field ureyBradleys.
      Returns:
      an array of UreyBradley objects.

    • getVanDerWaalsEnergy

      public double getVanDerWaalsEnergy()
      Getter for the field vanDerWaalsEnergy.
      Returns:
      a double.

    • getVanDerWaalsInteractions

      public int getVanDerWaalsInteractions()
      getVanDerWaalsInteractions.
      Returns:
      a int.

    • getVariableTypes

      public Potential.VARIABLE_TYPE[] getVariableTypes()
      Get the type of all variables.

      Return a reference to each variables type.

      Specified by:
      getVariableTypes in interface Potential
      Returns:
      The VARIABLE_TYPE of each variable.

    • getVdwNode

      public VanDerWaals 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 interface Potential
      Parameters:
      velocity - an array of
      invalid reference 
      double
      objects.
      Returns:
      an array of
      invalid reference 
      double
      objects.

    • getd2EdL2

      public double getd2EdL2()
      Get the 2nd partial derivative of the energy with respect to lambda.
      Specified by:
      getd2EdL2 in interface LambdaInterface
      Returns:
      d2EdL2

    • getdEdL

      public double getdEdL()
      Get the partial derivative of the energy with respect to lambda.
      Specified by:
      getdEdL in interface LambdaInterface
      Returns:
      dEdL

    • getdEdXdL

      public void getdEdXdL(double[] gradients)
      Get the gradient of dEdL with respect to each parameter.
      Specified by:
      getdEdXdL in interface LambdaInterface
      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 interface Potential
      Parameters:
      acceleration - an array of
      invalid reference 
      double
      objects.

    • setCoordinates

      public void setCoordinates(double[] coords)
      The coordinate array should only contain active atoms.
      Parameters:
      coords - an array of
      invalid reference 
      double
      objects.

    • setCrystal

      public void setCrystal(Crystal crystal, boolean checkReplicatesCell)
      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 interface Potential
      Parameters:
      previousAcceleration - an array of
      invalid reference 
      double
      objects.

    • 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 set
      override - Override properties

    • setVelocity

      public void setVelocity(double[] velocity)
      setVelocity.

      The velocity array should only contain velocity data for active atoms.

      Specified by:
      setVelocity in interface Potential
      Parameters:
      velocity - an array of
      invalid reference 
      double
      objects.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • logBondedTerms

      public void logBondedTerms()
      Log out all bonded energy terms.

    • getRestrainDistances

      public List<RestrainDistance> getRestrainDistances(@Nullable BondType.BondFunction bondFunction)
      Getter for the field restrainDistances.
      Parameters:
      bondFunction - the type of bond function.
      Returns:
      a List object.

    • getRestrainTorsions

      public List<RestraintTorsion> getRestrainTorsions()
      Getter for the field restraintBonds.
      Returns:
      a List object.

    • getRestrainGroups

      public RestrainGroups getRestrainGroups()
      Getter for the RestrainGroup field.
      Returns:
      Returns RestrainGroup.