diff --git a/doc/src/min_modify.rst b/doc/src/min_modify.rst index 1f137abe6a..1f567b3651 100644 --- a/doc/src/min_modify.rst +++ b/doc/src/min_modify.rst @@ -29,9 +29,9 @@ Syntax *discrete_factor* value = factor factor = discretization factor for adaptive spin timestep (adim) *integrator* value = *eulerimplicit* or *verlet* - time integration scheme for fire2 minimization + time integration scheme for fire minimization *tmax* value = factor - factor = maximum adaptive timestep for fire2 minimization + factor = maximum adaptive timestep for fire minimization (adim) @@ -86,9 +86,9 @@ even if atoms could move in the gradient direction to reduce forces further. The choice of a norm can be modified for the min styles *cg*\ , *sd*\ -, *quickmin*\ , *fire*\ , *spin*\ , *spin/cg* and *spin/lbfgs* using -the *norm* keyword. The default *two* norm computes the 2-norm -(Euclidean length) of the global force vector: +, *quickmin*\ , *fire*\ , *fire/old*\ , *spin*\ , *spin/cg* and +*spin/lbfgs* using the *norm* keyword. The default *two* norm computes +the 2-norm (Euclidean length) of the global force vector: .. image:: Eqs/norm_two.jpg :align: center @@ -109,13 +109,14 @@ all atoms in the system: For the min styles *spin*\ , *spin/cg* and *spin/lbfgs*\ , the force norm is replaced by the spin-torque norm. -Keywords *alpha\_damp* and *discrete\_factor* should only be used when -a :doc:`min\_spin ` command is declared. Keyword -*alpha\_damp* defines an analog of a magnetic Gilbert damping. It -defines a relaxation rate toward an equilibrium for a given magnetic -system. Keyword *discrete\_factor* defines a discretization factor -for the adaptive timestep used in the *spin* minimization. See -:doc:`min\_spin ` for more information about those +Keywords *alpha\_damp* and *discrete\_factor* only make sense when +a :doc:`min_spin ` command is declared. +Keyword *alpha\_damp* defines an analog of a magnetic Gilbert +damping. It defines a relaxation rate toward an equilibrium for +a given magnetic system. +Keyword *discrete\_factor* defines a discretization factor for the +adaptive timestep used in the *spin* minimization. +See :doc:`min_spin ` for more information about those quantities. The choice of a line search algorithm for the *spin/cg* and @@ -128,30 +129,36 @@ procedure. The *spin\_none* is a default value for *line* keyword for both *spin/lbfgs* and *spin/cg*\ . Convergence of *spin/lbfgs* can be more robust if *spin\_cubic* line search is used. -The Newton *integrator* used for *fire2* minimization can be selected +The Newton *integrator* used for *fire* minimization can be selected to be either the symplectic Euler (\ *eulerimplicit*\ ) or velocity Verlet (\ *verlet*\ ). *tmax* define the maximum value for the -adaptive timestep during a *fire2* minimization. It is multiplication +adaptive timestep during a *fire* minimization. It is a multiplication factor applied to the current :doc:`timestep ` (not in time -unit). For example, *tmax* = 4.0 in metal :doc:`units ` means -that the maximum value the timestep can reach during a minimization is -4fs (with the default :doc:`timestep ` value). Note that -parameter defaults has been chosen to be reliable in most cases, but -one should consider adjusting :doc:`timestep ` and *tmax* to +unit). For example, *tmax* = 4.0 with a :doc:`timestep ` of +2fs, means that the maximum value the timestep can reach during a *fire* +minimization is 4fs. +Note that parameter defaults has been chosen to be reliable in most cases, +but one should consider adjusting :doc:`timestep ` and *tmax* to optimize the minimization for large or complex systems. Other -parameters of the *fire2* minimization can be tuned (\ *tmin*\ , +parameters of the *fire* minimization can be tuned (\ *tmin*\ , *delaystep*\ , *dtgrow*\ , *dtshrink*\ , *alpha0*\ , and -*alphashrink*\ ). Please refer to the article describing the *fire2* -:doc:`min\_style `. - -An additional stopping criteria *vdfmax* is added in order to avoid +*alphashrink*\ ). Please refer to the references describing the +:doc:`min\_style ` *fire*. +An additional stopping criteria *vdfmax* is used by *fire* in order to avoid unnecessary looping when it is reasonable to think the system will not -be relaxed further. Note that in this case the system will NOT be -relaxed. This could happen when the system comes to be stuck in a -local basin of the phase space. *vdfmax* is the maximum number of -consecutive iterations with P(t) < 0. For debugging purposes, it is -possible to switch off the inertia correction (\ *halfstepback* = -*no*\ ) and the initial delay (\ *initialdelay* = *no*\ ). +be relaxed further. Note that in this case the system will NOT have +reached your minimization criteria. This could happen when the system +comes to be stuck in a local basin of the phase space. *vdfmax* is +the maximum number of consecutive iterations with P(t) < 0. + +The :doc:`min\_style ` *fire* is an optimized implementation of +:doc:`min\_style ` *fire/old*. It can however behave similarly +to the *fire/old* style by using the following set of parameters: + +.. parsed-literal:: + min_modify integrator eulerexplicit tmax 10.0 tmin 0.0 delaystep 5 & + dtgrow 1.1 dtshrink 0.5 alpha0 0.1 alphashrink 0.99 & + vdfmax 100000 halfstepback no initialdelay no Restrictions """""""""""" @@ -175,7 +182,7 @@ For the *spin*\ , *spin/cg* and *spin/lbfgs* styles, the option defaults are alpha\_damp = 1.0, discrete\_factor = 10.0, line = spin\_none, and norm = euclidean. -For the *fire2* style, the option defaults are integrator = +For the *fire* style, the option defaults are integrator = eulerimplicit, tmax = 10.0, tmin = 0.02, delaystep = 20, dtgrow = 1.1, dtshrink = 0.5, alpha0 = 0.25, alphashrink = 0.99, vdfmax = 2000, halfstepback = yes and initialdelay = yes. diff --git a/doc/src/min_style.rst b/doc/src/min_style.rst index af8aa95425..57cac3dfc6 100644 --- a/doc/src/min_style.rst +++ b/doc/src/min_style.rst @@ -11,7 +11,7 @@ Syntax min_style style -* style = *cg* or *hftn* or *sd* or *quickmin* or *fire* or *fire2* or *spin* or *spin/cg* or *spin/lbfgs* +* style = *cg* or *hftn* or *sd* or *quickmin* or *fire* or *fire/old* or *spin* or *spin/cg* or *spin/lbfgs* Examples """""""" @@ -65,11 +65,22 @@ Style *fire* is a damped dynamics method described in :ref:`(Bitzek) and alters the projection operation to maintain components of the velocity non-parallel to the current force vector. The velocity of each atom is initialized to 0.0 by this style, at the beginning of a -minimization. +minimization. This style correspond to an optimized version described +in :ref:`(Guenole) ` that include different time integration +schemes and defaults parameters. The default parameters can be +modified with the command :doc:`min\_modify `. -Style *fire2* is an optimization of the style *fire*\ , including -different time integration schemes, described in :ref:`(Guenole) -`. + +Style *fire/old* is the original implementation of *fire* in Lammps, +conserved for backward compatibility. The main differences regarding +the current version *fire* are: time integration by Explicit Euler +only, different sequence in maintining velocity components non-parallel +to the current force vector and hard-coded minimization parameters. +A complete description of the differences between *fire/old* and *fire* +can be found in :ref:`(Guenole) ` (where the current *fire* +in lammps is named *fire2.0*). By using an appropriate set of +parameters, *fire* can behave similarly than *fire/old*, as described +in the :doc:`min\_modify ` command. Style *spin* is a damped spin dynamics with an adaptive timestep. @@ -83,7 +94,7 @@ to minimize spin configurations. See the :doc:`min/spin ` doc page for more information about the *spin*\ , *spin/cg* and *spin/lbfgs* styles. -Either the *quickmin*\ , *fire* and *fire2* styles are useful in the +Either the *quickmin*\ , *fire* and *fire/old* styles are useful in the context of nudged elastic band (NEB) calculations via the :doc:`neb ` command. @@ -97,10 +108,12 @@ calculations via the :doc:`neb/spin ` command. defined via the :doc:`timestep ` command. Often they will converge more quickly if you use a timestep about 10x larger than you would normally use for dynamics simulations. + For *fire*, the default timestep is recommended to be equal to + the one you would normally use for dynamics simulations. .. note:: - The *quickmin*\ , *fire*\ , *hftn*\ , and *cg/kk* styles do not yet + The *quickmin*\ , *fire*\ , *fire/old*\ , *hftn*\ , and *cg/kk* styles do not yet support the use of the :doc:`fix box/relax ` command or minimizations involving the electron radius in :doc:`eFF ` models. @@ -174,4 +187,4 @@ Jonsson, Mills, Jacobsen. **(Guenole)** Guenole, Noehring, Vaid, Houlle, Xie, Prakash, Bitzek, -Preprint, arXiv:190802038 (2019). +Comput Mater Sci, (2020), in press (arXiv:190802038). diff --git a/doc/src/minimize.rst b/doc/src/minimize.rst index 7ed77994af..dd3dbef002 100644 --- a/doc/src/minimize.rst +++ b/doc/src/minimize.rst @@ -38,19 +38,20 @@ be in local potential energy minimum. More precisely, the configuration should approximate a critical point for the objective function (see below), which may or may not be a local minimum. -The minimization algorithm used is set by the :doc:`min\_style -` command. Other options are set by the :doc:`min\_modify -` command. Minimize commands can be interspersed with -:doc:`run ` commands to alternate between relaxation and -dynamics. The minimizers bound the distance atoms move in one -iteration, so that you can relax systems with highly overlapped atoms -(large energies and forces) by pushing the atoms off of each other. +The minimization algorithm used is set by the +:doc:`min_style ` command. Other options are set by the +:doc:`min_modify ` command. Minimize commands can be +interspersed with :doc:`run ` commands to alternate between +relaxation and dynamics. The minimizers bound the distance atoms move +in one iteration, so that you can relax systems with highly overlapped +atoms (large energies and forces) by pushing the atoms off of each +other. Alternate means of relaxing a system are to run dynamics with a small or :doc:`limited timestep `. Or dynamics can be run using :doc:`fix viscous ` to impose a damping force that -slowly drains all kinetic energy from the system. The -:doc:`pair\_style soft ` potential can be used to +slowly drains all kinetic energy from the system. The :doc:`pair_style soft ` potential can be used to un-overlap atoms while +running dynamics. un-overlap atoms while running dynamics. Note that you can minimize some atoms in the system while holding the @@ -70,7 +71,7 @@ backtracking method is described in Nocedal and Wright's Numerical Optimization (Procedure 3.1 on p 41). The :doc:`minimization styles ` *quickmin*\ , *fire* and -*fire2* perform damped dynamics using an Euler integration step. Thus +*fire/old* perform damped dynamics using an Euler integration step. Thus they require a :doc:`timestep ` be defined. .. note::