Package ffx.potential

Class QuadTopologyEnergy

java.lang.Object
ffx.potential.QuadTopologyEnergy
All Implemented Interfaces:
CrystalPotential, OptimizationInterface, Potential, LambdaInterface
public class QuadTopologyEnergy extends Object implements CrystalPotential, LambdaInterface
Implements an error-canceling quad topology, where two large dual-topology simulation legs are run simultaneously to arrive at a small sum. This implementation permits sharing of coordinates between the dual topology; results in energy function of E(A1, A2, B1, B2) = (1-l)A1 + l*A2 + l*B1 + (1-l)B2. When coordinates are shared, this can entail atoms feeling approximately twice the force as an ordinary atom, possibly requiring a reduced inner timestep.
Since:
1.0
Author:
Jacob M. Litman, Michael J. Schnieders

  • Constructor Details

    • QuadTopologyEnergy

      public QuadTopologyEnergy(DualTopologyEnergy dualTopologyA, DualTopologyEnergy dualTopologyB)
      General structure: first layer will be the "A/B" layer, consisting of the two dual topologies. The second layer will be the "1/2" layer, consisting of the assemblies/ForceFieldEnergies associated with each dual topology. Arrays will be addressed as [A/B=0/1][1/2=0/1].

      For example, if running a dual-force-field calculation, A might be the original molecule, going from AMOEBA to a fixed-charge force field, while B is a modified molecule going from fixed-charge to AMOEBA. Within those, A1 would be AMOEBA-original, A2 would be AMBER-original, B1 would be AMBER-modified, B2 would be AMOEBA-modified.

      This constructor assumes there are no unique atoms in either topology, and pins everything.

      Parameters:
      dualTopologyA - A DualTopologyEnergy
      dualTopologyB - A DualTopologyEnergy

    • QuadTopologyEnergy

      public QuadTopologyEnergy(DualTopologyEnergy dualTopologyA, DualTopologyEnergy dualTopologyB, List<Integer> uniqueAList, List<Integer> uniqueBList)
      General structure: first layer will be the "A/B" layer, consisting of the two dual topologies. The second layer will be the "1/2" layer, consisting of the assemblies/ForceFieldEnergies associated with each dual topology. Arrays will be addressed as [A/B=0/1][1/2=0/1].

      For example, if running a dual-force-field calculation, A might be the original molecule, going from AMOEBA to a fixed-charge force field, while B is a modified molecule going from fixed-charge to AMOEBA. Within those, A1 would be AMOEBA-original, A2 would be AMBER-original, B1 would be AMBER-modified, B2 would be AMOEBA-modified.

      Parameters:
      dualTopologyA - A DualTopologyEnergy
      dualTopologyB - A DualTopologyEnergy
      uniqueAList - Variables unique to A
      uniqueBList - Variables unique to B

  • Method Details

    • 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 both dual topologies are zero at the ends.

      Specified by:
      dEdLZeroAtEnds in interface LambdaInterface
      Returns:
      True if dUdL is guaranteed 0 at endpoints.

    • destroy

      public boolean destroy()
      Destroys this Potential and frees up any associated resources, particularly worker Threads. Default implementation is to return true (assume destruction successful).
      Specified by:
      destroy in interface OptimizationInterface
      Returns:
      If resource reclamation successful, or resources already reclaimed.

    • 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.
      Specified by:
      getAcceleration in interface Potential
      Parameters:
      acceleration - an array of double values.
      Returns:
      an array of double values.

    • 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.
      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.
      Specified by:
      setCrystal in interface CrystalPotential
      Parameters:
      crystal - a Crystal instance.

    • getDualTopA

      public DualTopologyEnergy getDualTopA()
      Returns the first component DualTopologyEnergy.
      Returns:
      Dual topology A.

    • getDualTopB

      public DualTopologyEnergy getDualTopB()
      Returns the second component DualTopologyEnergy.
      Returns:
      Dual topology B.

    • 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.
      Specified by:
      setEnergyTermState in interface Potential
      Parameters:
      state - include FAST varying energy terms, SLOW varying energy terms or BOTH.

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

    • getNumSharedVariables

      public int getNumSharedVariables()
      Returns number of shared variables.
      Returns:
      Shared variables

    • getNumberOfVariables

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

    • getPreviousAcceleration

      public double[] getPreviousAcceleration(double[] previousAcceleration)
      getPreviousAcceleration.
      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.

    • getTotalEnergy

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

    • getUnderlyingPotentials

      public List<Potential> getUnderlyingPotentials()
      Description copied from interface: OptimizationInterface
      Returns a List of Potentials this Potential depends on with a recursive search, excluding the top level of this call. May not be implemented for all Potentials.
      Specified by:
      getUnderlyingPotentials in interface OptimizationInterface
      Returns:
      By default, an empty list.

    • getVariableTypes

      public Potential.VARIABLE_TYPE[] getVariableTypes()
      Get the type of all variables.
      Specified by:
      getVariableTypes in interface Potential
      Returns:
      The VARIABLE_TYPE of each variable.

    • getVelocity

      public double[] getVelocity(double[] velocity)
      getVelocity.
      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[] g)
      Get the gradient of dEdL with respect to each parameter.
      Specified by:
      getdEdXdL in interface LambdaInterface
      Parameters:
      g - - A double array of length the number of parameters in the model (commonly 3 * number of atoms).

    • setAcceleration

      public void setAcceleration(double[] acceleration)
      setAcceleration.
      Specified by:
      setAcceleration in interface Potential
      Parameters:
      acceleration - an array of double values.

    • setParallel

      public void setParallel(boolean parallel)
      setParallel.
      Parameters:
      parallel - a boolean.

    • setPreviousAcceleration

      public void setPreviousAcceleration(double[] previousAcceleration)
      setPreviousAcceleration.
      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

    • setCoordinates

      public void setCoordinates(double[] coordinates)
      Set the current value of the parameters. If the supplied array is null or not large enough, no action is taken.
      Specified by:
      setCoordinates in interface OptimizationInterface
      Parameters:
      coordinates - The array with parameter values.

    • setVelocity

      public void setVelocity(double[] velocity)
      setVelocity.
      Specified by:
      setVelocity in interface Potential
      Parameters:
      velocity - an array of double values.