The Energy Minimization class (Minimizers) is a subclass of the Molecular Mechanics (MolMech) class. The Minimizers class is defined in the EnerMinim module in Yup.Methods. The import statement would be some variant of: from Yup.Methods.EnerMinim import Minimizers. Data Attributes Data attribute names are case-sensitive. All of the data attributes can be assigned new values. Some attributes have values that are nearly ideal and will probably not benefit from revaluation. In addition to these data attributes this class also inherits the attributes from the MolMech class, i.e., you can also set the MolMech attributes. Attribute Description GradientNorm The gradient norm target and the preset value is 10-4 in units of kcal/mol/Å. Minimization is terminated when the gradient norm falls below this value. StepSize (SimpleSD and the Davidon line search procedure). The preset value is 10-6 in units of Å2/CEU. Internal units are in use but the units are not meaningful anyway. This is the initial value of the step size. The step size is scaled up or down as the calculation progresses (SimpleSD) or is calculated from a cubic interpolation (Davidon). SD_UpScale (SimpleSD only) The preset value is 1.2. The step size is scaled by this value when a step of the calculation results in the lowering of the potential energy. SD_DownScale (SimpleSD only) The preset value is 0.5. The step size is scaled by this value when a step of the calculation results in the increase of the potential energy or if the energy is unchanged. LS_StepTolerance (Davidon line search only). The preset value is 10-4 in units of Å2/CEU. This is the smallest interval between two interpolations of the optimum step size that is to be considered to be insignificant. LS_NumInnerIter (Line Search only). The preset value is 10. The number of inner loop iterations (interpolation) for the Davidon method. LS_NumOuterIter (Line Search only). The preset value is 10. The number of outer loop iterations (bracketing) for the Davidon method. Methods The Minimizers class defines only the constructor function and two methods. The constructor function requires one argument, the model on which the energy minimization method is to be applied. This is a Model object that is constructed by a force field assembler. Constructor Number of Arguments Return Value Minimizers 1 The new Minimizers object Argument Purpose Preset Value a Model object the model that is to be subjected to the molecular mechanics calculation - The model object must be complete, i.e., the Map, Energy and Coordinates attributes must all be defined. The SimpleSD method carries out an energy minimization calculation using the Steepest Descent method with no line search. In each iteration, a step is taken in the opposite direction to the gradient. The step size is set by the StepSize attribute. The step size is scaled up if the step results in a lower energy and down otherwise. This method is slow but robust. Method Argument Keywords Return Values SimpleSD "numstep", "limit" Tuple of 4 items Argument Type Preset Value numstep Integer - limit None, a group AtomMap, or a list of two integers None Energy minimization can be limited to a portion of a system. Please see the Targeted Simulation section of the Introduction to see how to set limit. The model (or part of the model) is energy minimized using a maximum of numstep iterations. The calculation may be terminated prematurely (which is a good thing) if the gradient norm falls below the value of the GradientNorm attribute. The CGPR method carries out an energy minimization calculation using the Polak-Ribiere (PR+) Conjugate Gradient method. This is generally faster than SimpleSD but the initial coordinates must be near a local minimum. Method Argument Keywords Return Values CGPR "numstep", "limit" Tuple of 4 items Argument Type Preset Value numstep Integer - limit None, a group AtomMap, or a list of two integers None Energy minimization can be limited to a portion of a system. Please see the Targeted Simulation section of the Introduction to see how to set limit. Example >>> from Yup.Models.TestTube.FFA import makechain >>> from Yup.Methods.EnerMinim import Minimizers >>> >>> M = makechain( 1000 ) >>> O = Minimizers( M ) >>> O.ColumnWidth = 0 >>> O.GradientNorm = 1e-2 >>> minimize = O.SimpleSD >>> >>> minimize( 5000 ) In this example, we start with the required imports: the makechain() method from the TestTube force field assembler and the Minimizers class from the Energy Minimization module. The makechain() method assembles the force field for a bead model, and the example asks for a chain of 1000 beads and the Model that is returned is saved in the variable M. M is then passed to the Minimizers() constructor function and the object that is returned is then saved in the variable O. The Energy Minimization object O is then modified: the column width for printout is set to 0 so that numbers are printed with tab separators and the gradient norm is reset to 10-2. After all, the Steepest Descent method is not convergent enough for this setting to be useful. As a convenience the Steepest Descent method is selected and assigned to a variable minimize. Finally, 5000 steps of energy minimization are carried out. Comparisons The following comparison of the two energy minimization methods can help you choose a method. The "Relative Convergence" column lists the performance relative to the reference method (CGPR). The last column lists the number of function-gradient evaluations per iteration. Method Line Search Robust Relative Convergence #Function/Iteration SimpleSD No Yes very slow 1 CGPR Yes No reference 2+ The SimpleSD method is robust because it does not use a line search routine and therefore makes few assumptions about the potential energy function. Each iteration requires only one function-gradient evaluation, but the method is not convergent. The CGPR method uses a line search procedure that models the energy function along a search vector. The model function is much simpler than the potential energy function and its minimum can be found analytically. It is accurate when the structure is near a local minimum. However, when far from a minimum, the model function is no longer a good approximation for the potential energy. Thus, CGPR is not a robust method, but it is much more convergent than SimpleSD. The line search procedure uses two quantities at two sets of coordinates to fit a cubic and the minimum of the cubic can be calculated analytically. The first set of coordinates is from the previous iteration for which the energy and gradients had been evaluated. The second set is taken to be twice the previously determined step size, and the energy and gradients are evaluated at the projected position. The minimum is calculated and another energy-gradient evaluation is carried out. Thus, each iteration of CGPR requires at least two function-gradient evaluations. Introduction Molecular Mechanics Energy Minimization Molecular Dynamics Monte Carlo