Package ffx.algorithms.optimize

Class RotamerOptimization

java.lang.Object
ffx.algorithms.optimize.RotamerOptimization
All Implemented Interfaces:
Terminatable
public class RotamerOptimization extends Object implements Terminatable
Optimize protein side-chain conformations and nucleic acid backbone conformations using rotamers.
Since:
1.0
Author:
Michael J. Schnieders, Jacob M. Litman, Stephen D. LuCore, Mallory R. Tollefson

  • Field Details

    • molecularAssembly

      protected final MolecularAssembly molecularAssembly
      MolecularAssembly to perform rotamer optimization on.

    • potential

      protected final Potential potential
      The Potential to evaluate during rotamer optimization.

    • algorithmListener

      protected final AlgorithmListener algorithmListener
      AlgorithmListener who should receive updates as the optimization runs.

    • library

      protected RotamerLibrary library
      RotamerLibrary instance.

  • Constructor Details

    • RotamerOptimization

      public RotamerOptimization(MolecularAssembly molecularAssembly, Potential potential, AlgorithmListener algorithmListener)
      RotamerOptimization constructor.
      Parameters:
      molecularAssembly - The MolecularAssembly to search rotamers for.
      potential - a Potential object.
      algorithmListener - AlgorithmListener to update the GUI.

  • Method Details

    • setWriteEnergyRestart

      public void setWriteEnergyRestart(boolean writeEnergyRestart)
      Set the writeEnergyRestart flag.
      Parameters:
      writeEnergyRestart - If true, write out an energy restart file.

    • checkNeighboringPair

      public boolean checkNeighboringPair(int i, int j)
      Checks if residue i is considered to be interacting with residue j, and thus has non-null elements in the pair energies matrix.
      Parameters:
      i - A residue index.
      j - A residue index j != i.
      Returns:
      If i and j interact.

    • checkNeighboringTriple

      public boolean checkNeighboringTriple(int i, int j, int k)
      Checks if residue i is considered to be interacting with residue j, that residue k is interacting with either i or j, and thus i-j-k has non-null elements in the triple energy matrix.
      Parameters:
      i - A residue index.
      j - A residue index j != i.
      k - A residue index k != i, k != j.
      Returns:
      If i, j, and k form an interacting triple.

    • checkValidMove

      public boolean checkValidMove(int i, int ri, int[] currentRots)
      Checks the pair elimination array to see if this permutation has been eliminated.
      Parameters:
      i - Residue number
      ri - Rotamer number
      currentRots - Array of current rotamers indeces.
      Returns:
      If valid

    • computeBackboneEnergy

      public double computeBackboneEnergy(Residue[] residues) throws ArithmeticException
      Computes the environment/backbone energy, defined as energy with all sidechains under consideration turned off in their 0th rotamer.
      Parameters:
      residues - Residues under optimization.
      Returns:
      Backbone energy Eenv/bb.
      Throws:
      ArithmeticException - If an exception in calculating energy is found.

    • computeEnergy

      public double computeEnergy(Residue[] residues, int[] rotamers, boolean print)
      Uses existing backbone, self, 2-Body, and 3-body energies from rotamerEnergies() to calculate an approximate energy for a rotamer permutation.
      Parameters:
      residues - Current window of optimization.
      rotamers - Set of rotamers to calculate an approximate energy for.
      print - Verbosity flag
      Returns:
      Approximate permutation energy (backbone + selfs + pairs + trimers).

    • currentEnergy

      public double currentEnergy(Residue[] resArray) throws ArithmeticException
      Calculates the energy at the current state.
      Parameters:
      resArray - Array of residues in current energy term.
      Returns:
      Energy of the current state.
      Throws:
      ArithmeticException

    • currentEnergyWrapper

      public double currentEnergyWrapper(List<Residue> resList) throws ArithmeticException
      Wrapper intended for use with RotamerMatrixMC.
      Parameters:
      resList - Reside list.
      Returns:
      Returns the current energy.
      Throws:
      ArithmeticException - Thrown if there is an arithmetic exception computing the energy.

    • currentFFXPE

      public double currentFFXPE()
      Forces the use of a ForceFieldEnergyOpenMM's underlying ForceFieldEnergy.
      Returns:
      Current potential energy as calculated by FFX reference platform.

    • formatEnergy

      public String formatEnergy(double energy)
      Utility method for formatting energies, using 16 spaces with 8 digits of precision.
      Parameters:
      energy - Energy to format.
      Returns:
      A string representing the energy.

    • getApproximate

      public double getApproximate()

    • getBackboneEnergy

      public double getBackboneEnergy()

    • getEliminatedRotamers

      public EliminatedRotamers getEliminatedRotamers()

    • getEnergyExpansion

      public EnergyExpansion getEnergyExpansion()

    • getEnsemble

      public List<ResidueState[]> getEnsemble()
      getEnsemble.
      Returns:
      a List object.

    • setEnsemble

      public void setEnsemble(int ensemble)
      setEnsemble.
      Parameters:
      ensemble - a int.

    • getResidues

      public List<Residue> getResidues()
      Return the residue list.
      Returns:
      a List object.

    • setResidues

      public void setResidues(List<Residue> residueList)
      Set the residue list.
      Parameters:
      residueList - a List object.

    • getRestartFile

      public File getRestartFile()
      Returns the restart file.
      Returns:
      energyRestartFile File with saved side-chain energies.

    • goldsteinPairSumOverK

      public double goldsteinPairSumOverK(Residue[] residues, int lb, int ub, int i, int riA, int riB, int j, int rjC, int rjD, List<Residue> blockedResidues, int[] possK)

    • logIfRank0

      public void logIfRank0(String msg)

    • logIfRank0

      public void logIfRank0(String msg, Level level)

    • optimize

      public double optimize(RotamerOptimization.Algorithm algorithm)
      Perform the rotamer optimization using the specified algorithm.
      Parameters:
      algorithm - a RotamerOptimization.Algorithm object.
      Returns:
      the lowest energy found.

    • optimize

      public double optimize()
      Execute the rotamer optimization.
      Returns:
      The lowest energy found.

    • rotamerOptimization

      public double rotamerOptimization(MolecularAssembly molecularAssembly, Residue[] residues, int i, double lowEnergy, int[] optimum)
      A brute-force global optimization over side-chain rotamers using a recursive algorithm.
      Parameters:
      molecularAssembly - a MolecularAssembly object.
      residues - an array of Residue objects.
      i - a int.
      lowEnergy - a double.
      optimum - an array of
      invalid reference 
      int
      objects.
      Returns:
      the current energy.

    • setPHRestraint

      public void setPHRestraint(double pHRestraint)

    • setpH

      public void setpH(double pH)

    • setRecomputeSelf

      public void setRecomputeSelf(boolean recomputeSelf)

    • setOnlyProtons

      public void setOnlyProtons(boolean onlyProtons)

    • getPHRestraint

      public double getPHRestraint()

    • getPH

      public double getPH()

    • setApproxBoxLength

      public void setApproxBoxLength(double approxBoxLength)
      Sets the approximate dimensions of boxes, over-riding numXYZBoxes in determining box size. Rounds box size up and number of boxes down to get a whole number of boxes along each axis.
      Parameters:
      approxBoxLength - Optional box dimensions parameter (Angstroms).

    • setBoxBorderSize

      public void setBoxBorderSize(double boxBorderSize)
      Sets the amount of overlap between adjacent boxes for box optimization.
      Parameters:
      boxBorderSize - Box overlap in Angstroms.

    • setBoxEnd

      public void setBoxEnd(int boxEnd)
      Set the ending box index.
      Parameters:
      boxEnd - a int.

    • setBoxInclusionCriterion

      public void setBoxInclusionCriterion(int boxInclusionCriterion)
      Sets behavior for how Residues are added to boxOptCells; 1 uses just reference atom (C alpha for protein, N1/9 for nucleic acids), 2 uses any atom, 3 uses any atom in any rotamer.
      Parameters:
      boxInclusionCriterion - Criterion to use

    • setBoxStart

      public void setBoxStart(int boxStart)
      Set the starting box index.
      Parameters:
      boxStart - a int.

    • setCoordinatesToEnsemble

      public void setCoordinatesToEnsemble(int ensnum)
      setCoordinatesToEnsemble.
      Parameters:
      ensnum - a int.

    • setDecomposeOriginal

      public void setDecomposeOriginal(boolean decomposeOriginal)
      Sets the decompose-original flag.
      Parameters:
      decomposeOriginal - If true, decompose the energy of the structure without optimizing.

    • setDirection

      public void setDirection(RotamerOptimization.Direction direction)
      Set the optimization direction to forward or backward.
      Parameters:
      direction - a RotamerOptimization.Direction object.

    • setDistanceCutoff

      public void setDistanceCutoff(double distance)
      Set the cut-off distance for inclusion of residues in sliding box and window methods.
      Parameters:
      distance - a double.

    • setEnergyRestartFile

      public void setEnergyRestartFile(File file)
      Setter for the field energyRestartFile.
      Parameters:
      file - a File object.

    • setEnsemble

      public void setEnsemble(int ensemble, double ensembleBuffer)
      setEnsemble.
      Parameters:
      ensemble - a int.
      ensembleBuffer - a double.

    • setIncrement

      public void setIncrement(int increment)
      Set the residue increment for sliding window.
      Parameters:
      increment - a int.

    • setMaxRotCheckDepth

      public void setMaxRotCheckDepth(int maxRotCheckDepth)
      Control the depth of self-consistency checking with a rotamer is eliminated.
      Parameters:
      maxRotCheckDepth - a int.

    • setMinimumNumberAcceptedNARotamers

      public void setMinimumNumberAcceptedNARotamers(int minNumberAcceptedNARotamers)
      Set the minimum number of accepted nucleic acid rotamers.
      Parameters:
      minNumberAcceptedNARotamers - a int.

    • setMonteCarlo

      public void setMonteCarlo(boolean monteCarlo, int nMCsteps)
      Sets the option to use a number of Monte Carlo steps for final optimization.
      Parameters:
      monteCarlo - If Monte Carlo is to be considered
      nMCsteps - Number of steps to be taken

    • setMonteCarloTesting

      public void setMonteCarloTesting(boolean bool)
      Sets the monteCarloTesting boolean in RotamerOptimization.java to true or false. This should only be set to true when monte carlo is being tested through the ManyBodyTest script. When true, the method sets a seed for the pseudo-random number generator and allows the monte carlo rotamer optimization to be deterministic.
      Parameters:
      bool - True or false.

    • setNucleicCorrectionThreshold

      public void setNucleicCorrectionThreshold(double nucleicCorrectionThreshold)
      The nucleic acid correction threshold.
      Parameters:
      nucleicCorrectionThreshold - a double.

    • setNucleicPruningFactor

      public void setNucleicPruningFactor(double nucleicPruningFactor)
      Also sets derivative pruning factors.
      Parameters:
      nucleicPruningFactor - a double.

    • setNumXYZBoxes

      public void setNumXYZBoxes(int[] numXYZBoxes)
      Sets the number of boxes in the x, y, and z axes if the box optimization is to be carried out.
      Parameters:
      numXYZBoxes - Int[3] of number of boxes in x, y, z.

    • setPairClashThreshold

      public void setPairClashThreshold(double pairClashThreshold)
      Setter for the field pairClashThreshold.
      Parameters:
      pairClashThreshold - a double.

    • setPrintFiles

      public void setPrintFiles(boolean printFiles)
      Sets whether rotamer optimization should print out any files, or act solely to optimize a structure in memory.
      Parameters:
      printFiles - a boolean.

    • setPruning

      public void setPruning(int set)
      Sets level of pruning: 0 for fully off, 1 for only singles, 2 for single and pair pruning.
      Parameters:
      set - Pruning option.

    • setResiduesIgnoreNull

      public void setResiduesIgnoreNull(List<Residue> residues)
      Accepts a list of residues but throws out null residues. Used by the -lR flag.
      Parameters:
      residues - a List object.

    • setRevert

      public void setRevert(boolean revert)
      Set the algorithm to revert to starting coordinates if the energy increases.
      Parameters:
      revert - a boolean.

    • setRotamerLibrary

      public void setRotamerLibrary(RotamerLibrary lib)

    • setSingletonClashThreshold

      public void setSingletonClashThreshold(double singletonClashThreshold)
      setSingletonClashThreshold.
      Parameters:
      singletonClashThreshold - a double.

    • setSuperpositionThreshold

      public void setSuperpositionThreshold(double superpositionThreshold)
      Setter for the field superpositionThreshold.
      Parameters:
      superpositionThreshold - a double.

    • setThreeBodyCutoff

      public void setThreeBodyCutoff(double threeBodyCutoffDist)
      Sets the threeBodyCutoffDist. All three-body energies where the rotamers have a separation distance larger than the cutoff are set to 0.
      Parameters:
      threeBodyCutoffDist - Separation distance at which the interaction of three side-chains is assumed to have an energy of 0.

    • setThreeBodyEnergy

      public void setThreeBodyEnergy(boolean threeBodyTerm)
      Flag to control use of 3-body energy terms.
      Parameters:
      threeBodyTerm - a boolean.

    • setTwoBodyCutoff

      public void setTwoBodyCutoff(double twoBodyCutoffDist)
      Sets the twoBodyCutoffDist. All two-body energies where the rotamers have a separation distance larger than the cutoff are set to 0.
      Parameters:
      twoBodyCutoffDist - Separation distance at which the interaction of two side-chains is assumed to have an energy of 0.

    • setUseGoldstein

      public void setUseGoldstein(boolean useGoldstein)
      Specify use of Goldstein optimization.
      Parameters:
      useGoldstein - a boolean.

    • setWindowSize

      public void setWindowSize(int windowSize)
      Setter for the field windowSize.
      Parameters:
      windowSize - a int.

    • terminate

      public void terminate()
      This should be implemented as a blocking interrupt; when the method returns the Terminatable algorithm has reached a clean termination point. For example, between minimize or molecular dynamics steps.
      Specified by:
      terminate in interface Terminatable

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • turnOffAllResidues

      public void turnOffAllResidues(Residue[] residues)

    • turnOffResidue

      public void turnOffResidue(Residue residue)

    • turnOnAllResidues

      public void turnOnAllResidues(Residue[] residues)

    • turnOnResidue

      public void turnOnResidue(Residue residue, int ri)

    • turnRotamerPairEliminationOff

      public void turnRotamerPairEliminationOff()
      ONLY FOR UNIT TESTING. Sets a boolean to turn the pair elimination criteria off.

    • turnRotamerSingleEliminationOff

      public void turnRotamerSingleEliminationOff()
      ONLY FOR UNIT TESTING. Sets a boolean to turn the self elimination criteria off.

    • partitionFunction

      public void partitionFunction(Residue[] residues, int i, int[] currentRotamers) throws Exception
      A global optimization over side-chain rotamers using a recursive algorithm and information about eliminated rotamers, rotamer pairs and rotamer triples.
      Parameters:
      residues - Residue array.
      i - Current number of permutations.
      currentRotamers - Current rotamer list.
      Throws:
      Exception

    • getRefEnergy

      public double getRefEnergy()
      Get reference energy for partition function boltzmann weights
      Returns:
      ref energy

    • getTotalBoltzmann

      public double getTotalBoltzmann()
      Get the total boltzmann weight for an ensemble
      Returns:
      total boltzmann

    • getFraction

      public double[][] getFraction()
      Get the ensemble average of protonated rotamers for all titratable sites
      Returns:
      fraction of protonated residues

    • getPopulationBoltzmann

      public double[][] getPopulationBoltzmann()
      Get the Protonated Boltzmann for all sites
      Returns:
      fraction of protonated residues

    • getPopulations

      public void getPopulations(Residue[] residues, int i, int[] currentRotamers) throws Exception
      Calculate Populations for Residues
      Parameters:
      residues - residue array
      i - int
      currentRotamers - empty array
      Throws:
      Exception - too many permutations to continue

    • getOptimumRotamers

      public int[] getOptimumRotamers()
      Return an integer array of optimized rotamers following rotamer optimization.
      Returns:
      The optimal rotamer array.