Package ffx.xray

Class RefinementMinimize

java.lang.Object
ffx.xray.RefinementMinimize
All Implemented Interfaces:
Terminatable, OptimizationListener
public class RefinementMinimize extends Object implements OptimizationListener, Terminatable
The RefinementMinimize class is responsible for performing energy minimization for refinement tasks. It provides multiple methods for minimization, allowing customization of gradient root mean square (RMS) values, maximum iterations, and matrix conditioning settings if necessary. The class enables iterative optimization with monitoring capabilities through an optional listener, and supports graceful termination during the process.

This class implements both the OptimizationListener and Terminatable interfaces and acts as an intermediary for managing refinement energy computation and convergence behavior.

Since:
1.0
Author:
Timothy D. Fenn, Michael J. Schnieders

  • Constructor Summary

    Constructors
    Constructor
    Description
    RefinementMinimize(DataContainer dataContainer)
    Constructor for the RefinementMinimize class, which initializes the refinement process with a specified data container and no algorithm listener.
    RefinementMinimize(DataContainer dataContainer, AlgorithmListener algorithmListener)
    Constructor for the RefinementMinimize class, initializing the refinement process with a specified data container and an optional algorithm listener for updates.

  • Method Summary

    Modifier and Type
    Method
    Description
    RefinementEnergy
    minimize()
    Minimizes the refinement energy using a default gradient root mean square (RMS) value of 1.0.
    RefinementEnergy
    minimize(double eps)
    Minimizes the refinement energy using a specified gradient root mean square (RMS) value.
    RefinementEnergy
    minimize(double eps, int maxIterations)
    Minimizes the refinement energy using a specified gradient root mean square (RMS) value and maximum number of iterations.
    RefinementEnergy
    minimize(int maxIterations)
    Minimizes the refinement energy with a specified maximum number of iterations, using a gradient RMS value of 1.0 and default matrix conditioning cycles.
    RefinementEnergy
    minimize(int m, double eps, int maxiter)
    Minimizes the refinement energy using the provided matrix conditioning cycles, gradient RMS value, and a maximum number of iterations.
    boolean
    optimizationUpdate(int iter, int nBFGS, int nfun, double grms, double xrms, double f, double df, double angle, LineSearch.LineSearchResult info)
    This method is called by the optimizer after each step.
    void
    terminate()
    This should be implemented as a blocking interrupt; when the method returns the Terminatable algorithm has reached a clean termination point.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • RefinementMinimize

      public RefinementMinimize(DataContainer dataContainer)
      Constructor for the RefinementMinimize class, which initializes the refinement process with a specified data container and no algorithm listener.
      Parameters:
      dataContainer - the data container object containing refinement data and methods

    • RefinementMinimize

      public RefinementMinimize(DataContainer dataContainer, @Nullable AlgorithmListener algorithmListener)
      Constructor for the RefinementMinimize class, initializing the refinement process with a specified data container and an optional algorithm listener for updates.
      Parameters:
      dataContainer - the data container object containing refinement data and methods
      algorithmListener - an optional algorithm listener that provides updates during processing (can be null)

  • Method Details

    • minimize

      public RefinementEnergy minimize()
      Minimizes the refinement energy using a default gradient root mean square (RMS) value of 1.0.
      Returns:
      a RefinementEnergy object representing the result of the minimization process.

    • minimize

      public RefinementEnergy minimize(double eps)
      Minimizes the refinement energy using a specified gradient root mean square (RMS) value.
      Parameters:
      eps - the desired gradient RMS value for the refinement process
      Returns:
      a RefinementEnergy object representing the result of the minimization process

    • minimize

      public RefinementEnergy minimize(int maxIterations)
      Minimizes the refinement energy with a specified maximum number of iterations, using a gradient RMS value of 1.0 and default matrix conditioning cycles.
      Parameters:
      maxIterations - the maximum number of iterations allowed for the minimization process
      Returns:
      a RefinementEnergy object representing the result of the minimization process

    • minimize

      public RefinementEnergy minimize(double eps, int maxIterations)
      Minimizes the refinement energy using a specified gradient root mean square (RMS) value and maximum number of iterations.
      Parameters:
      eps - the desired gradient RMS value for the refinement process
      maxIterations - the maximum number of iterations allowed for the minimization process
      Returns:
      a RefinementEnergy object representing the result of the minimization process

    • minimize

      public RefinementEnergy minimize(int m, double eps, int maxiter)
      Minimizes the refinement energy using the provided matrix conditioning cycles, gradient RMS value, and a maximum number of iterations. The default number of matrix conditioning steps is 7, while 0 is for steepest decent.
      Parameters:
      m - the number of matrix conditioning cycles for the optimization process
      eps - the desired gradient root mean square (RMS) value for convergence
      maxiter - the maximum number of iterations allowed for the minimization process
      Returns:
      a RefinementEnergy object representing the outcome of the minimization process

    • optimizationUpdate

      public boolean optimizationUpdate(int iter, int nBFGS, int nfun, double grms, double xrms, double f, double df, double angle, @Nullable LineSearch.LineSearchResult info)
      This method is called by the optimizer after each step.

      It can be used to log status messages, update the user interface, or gracefully terminate the optimizer.

      Specified by:
      optimizationUpdate in interface OptimizationListener
      Parameters:
      iter - Number of iterations.
      nBFGS - Number of L-BFGS correction vectors.
      nfun - Number of function evaluations.
      grms - RMS gradient at current solution.
      xrms - RMS coordinate change at current solution.
      f - Function value at current solution.
      df - Change in the function value compared to the previous solution.
      angle - Current angle between gradient and search direction.
      info - Result of the line search (null at iteration == 0).
      Returns:
      A return value of false will terminate the optimization.

    • 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