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

    • molecularAssembly

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

    • DEFAULT_CONSTRAINT_TOLERANCE

      public static final double DEFAULT_CONSTRAINT_TOLERANCE
      Default 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 lambdaTerm
      Indicates use of the Lambda state variable.

    • lambdaBondedTerms

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

    • optimizationScaling

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

    • maxDebugGradient

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

  • 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

    • getMolecularAssembly

      public MolecularAssembly 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

      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

    • getAtomArray

      public Atom[] 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

      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)
      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 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 double values.
      Returns:
      an array of double values.

    • 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.

    • 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.

    • 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.

    • 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.

    • 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 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.

    • getPDBHeaderString

      public String getPDBHeaderString()
      Create a PDB REMARK 3 string containing the potential energy terms.
      Returns:
      a String containing the PDB REMARK 3 formatted energy terms.

    • 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.

    • 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 double values.
      Returns:
      an array of double values.

    • 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.

    • getTotalEnergy

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

    • 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 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 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 double values.

    • setCoordinates

      public void setCoordinates(@Nullable double[] coords)
      The coordinate array should only contain active atoms.
      Specified by:
      setCoordinates in interface OptimizationInterface
      Parameters:
      coords - the coordinates to set.

    • 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 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 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 double values.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • logBondedTermsAndRestraints

      public void logBondedTermsAndRestraints()
      Log bonded energy terms and restraints.

    • getRestrainMode

      public ForceFieldEnergy.RestrainMode getRestrainMode()

    • getRestrainGroups

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

    • getTorsionTorsionPotentialEnergy

      public TorsionTorsionPotentialEnergy getTorsionTorsionPotentialEnergy()
      Get the TorsionTorsionPotentialEnergy.
      Returns:
      The TorsionTorsionPotentialEnergy.

    • getAnglePotentialEnergy

      public AnglePotentialEnergy getAnglePotentialEnergy()
      Get the AnglePotentialEnergy.
      Returns:
      The AnglePotentialEnergy.

    • getBondPotentialEnergy

      public BondPotentialEnergy getBondPotentialEnergy()
      Get the BondPotentialEnergy.
      Returns:
      The BondPotentialEnergy.

    • getStretchBendPotentialEnergy

      public StretchBendPotentialEnergy getStretchBendPotentialEnergy()
      Get the StretchBendPotentialEnergy.
      Returns:
      The StretchBendPotentialEnergy.

    • getUreyBradleyPotentialEnergy

      public UreyBradleyPotentialEnergy getUreyBradleyPotentialEnergy()
      Get the UreyBradleyPotentialEnergy.
      Returns:
      The UreyBradleyPotentialEnergy.

    • getOutOfPlaneBendPotentialEnergy

      public OutOfPlaneBendPotentialEnergy getOutOfPlaneBendPotentialEnergy()
      Get the OutOfPlaneBendPotentialEnergy.
      Returns:
      The OutOfPlaneBendPotentialEnergy.

    • getTorsionPotentialEnergy

      public TorsionPotentialEnergy getTorsionPotentialEnergy()
      Get the TorsionPotentialEnergy.
      Returns:
      The TorsionPotentialEnergy.

    • getStretchTorsionPotentialEnergy

      public StretchTorsionPotentialEnergy getStretchTorsionPotentialEnergy()
      Get the StretchTorsionPotentialEnergy.
      Returns:
      The StretchTorsionPotentialEnergy.

    • getAngleTorsionPotentialEnergy

      public AngleTorsionPotentialEnergy getAngleTorsionPotentialEnergy()
      Get the AngleTorsionPotentialEnergy.
      Returns:
      The AngleTorsionPotentialEnergy.

    • getImproperTorsionPotentialEnergy

      public ImproperTorsionPotentialEnergy getImproperTorsionPotentialEnergy()
      Get the ImproperTorsionPotentialEnergy.
      Returns:
      The ImproperTorsionPotentialEnergy.

    • getPiOrbitalTorsionPotentialEnergy

      public PiOrbitalTorsionPotentialEnergy getPiOrbitalTorsionPotentialEnergy()
      Get the PiOrbitalTorsionPotentialEnergy.
      Returns:
      The PiOrbitalTorsionPotentialEnergy.

    • getRestrainPositionPotentialEnergy

      public RestrainPositionPotentialEnergy getRestrainPositionPotentialEnergy()
      Get the RestrainPositionPotentialEnergy.
      Returns:
      The RestrainPositionPotentialEnergy.

    • getRestrainDistancePotentialEnergy

      public RestrainDistancePotentialEnergy getRestrainDistancePotentialEnergy()
      Get the RestrainDistancePotentialEnergy.
      Returns:
      The RestrainDistancePotentialEnergy.

    • getRestrainTorsionPotentialEnergy

      public RestrainTorsionPotentialEnergy getRestrainTorsionPotentialEnergy()
      Get the RestrainTorsionPotentialEnergy.
      Returns:
      The RestrainTorsionPotentialEnergy.