From 9215bce14f1ad7d5a4ecc2fb2fbbd257ca58b1a3 Mon Sep 17 00:00:00 2001 From: jguenole Date: Thu, 24 Oct 2019 15:06:43 +0200 Subject: [PATCH] Updated and simplified documentation --- doc/src/min_modify.txt | 66 +++++++++++++++--------------------------- doc/src/min_style.txt | 8 +++-- 2 files changed, 29 insertions(+), 45 deletions(-) diff --git a/doc/src/min_modify.txt b/doc/src/min_modify.txt index fa15f18a50..2e106f4415 100644 --- a/doc/src/min_modify.txt +++ b/doc/src/min_modify.txt @@ -13,7 +13,7 @@ min_modify command :h3 min_modify keyword values ... :pre one or more keyword/value pairs may be listed :ulb,l -keyword = {dmax} or {line} or {norm} or {alpha_damp} or {discrete_factor} +keyword = {dmax} or {line} or {norm} or {alpha_damp} or {discrete_factor} or {integrator} or {tmax} {dmax} value = max max = maximum distance for line search to move (distance units) {line} value = {backtrack} or {quadratic} or {forcezero} or {spin_cubic} or {spin_none} @@ -25,38 +25,17 @@ keyword = {dmax} or {line} or {norm} or {alpha_damp} or {discrete_factor} {alpha_damp} value = damping damping = fictitious Gilbert damping for spin minimization (adim) {discrete_factor} value = factor - factor = discretization factor for adaptive spin timestep (adim) :pre -:ule - -these keywords apply only to the "min_style"_min_style.html {fire2} :ulb,l -keyword = {integrator} or {tmax} or {tmin} or {delaystep} or {dtgrow} or {dtshrink} - or {alpha0} or {alphashrink} or {halfstepback} or {initialdelay} or {vdfmax} - {integrator} arg = {eulerimplicit} or {eulerexplicit} or {verlet} - eulerimplicit,eulerexplicit,verlet = integration scheme - {tmax} arg = coef - coef = factor defining the maximum timestep - {tmin} arg = coef - coef = factor defining the minimum timestep - {delaystep} arg = delay - delay = number of steps for dynamics delay - {dtgrow} arg = grow - grow = factor increasing the timestep - {dtshrink} arg = shrink - shrink = factor decreasing the timestep - {alpha0} arg = alpha - alpha = coefficient mixing velocities and forces - {alphashrink} arg = shrink - shrink = factor decreasing alpha - {vdfmax} arg = max - max = maximum number of consecutive iterations with P(t) < 0 before forced interruption - {halfstepback} arg = {yes} or {no} - {initialdelay} arg = {yes} or {no} :pre + factor = discretization factor for adaptive spin timestep (adim) + {integrator} value = {eulerimplicit} or {eulerexplicit} or {verlet} + time integration scheme for fire2 minimization + {tmax} value = factor + factor = maximum adaptive timestep for fire2 minimization :pre :ule [Examples:] min_modify dmax 0.2 -min_modify integrator verlet tmax 0.4 :pre +min_modify integrator verlet tmax 4 :pre [Description:] @@ -142,20 +121,23 @@ 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 style {fire2} has several parameters that can be tuned in order -to optimize the relaxation: {integrator}, {tmax}, {tmin}, {delaystep}, {dtgrow}, {dtshrink}, -{alpha0}, and {alphashrink}. -Different Newton {integrator} can be selected: explicit Euler, -semi-implicit Euler (= symplectic Euler) and velocity Verlet. -The parameters {tmax} and {tmin} define the maximum and minimum timestep -allowed during an fire2 minimization. Those are not in time unit, but are -multiplication factor applied to the "timestep"_timestep.html. Thus -{tmax} = 10.0 in metal "units"_units.html means that the maximum value -the timestep can be reached during the relaxation is 10 fs (with the default -"timestep"_timestep.html value). -Note that even with the default parameters being chosen to be reliable in most -cases, adjusting "timestep"_timestep.html, {tmax} and {tmin} should be consider -to optimize the minimization, in particular for large/complex system. +The Newton {integrator} used for {fire2} minimization can be selected to be +either the symplectic Euler ({eulerimplicit}), explicit Euler (eulerexplicit) +or velocity Verlet ({verlet}). Note that explicit Euler is not recommended +as it will lead to results similar to a {fire} minimization. +{tmax} define the maximum value for the adaptive timestep +during a {fire2} minimization. It is multiplication factor applied +to the current "timestep"_timestep.html (not in time unit). For example, +{tmax} = 4.0 in metal "units"_units.html means that the maximum value +the timestep can reach during a minimization is 4fs (with the default +"timestep"_timestep.html value). Note that parameters defaults has been +chosen to be reliable in most cases, but one should consider adjusting +"timestep"_timestep.html and {tmax} to optimize the minimization for large +or complex systems. +Others parameters of the {fire2} minimization can be tuned ({tmin}, {delaystep}, +{dtgrow}, {dtshrink}, {alpha0}, and {alphashrink}). Please refer to the article +describing the {fire2} "min_style"_min_style.html. + An additional stopping criteria {vdfmax} is added 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 diff --git a/doc/src/min_style.txt b/doc/src/min_style.txt index b03c4b1efb..d59850a5df 100644 --- a/doc/src/min_style.txt +++ b/doc/src/min_style.txt @@ -62,9 +62,8 @@ 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. -Style {fire2} is a re-implementation of the style {fire} with -additional optimizations of the method described -in "(Bitzek)"_#Bitzek, including different time integration schemes. +Style {fire2} is an optimization of the style {fire}, including different +time integration schemes, described in "(Guenole)"_#Guenole. Style {spin} is a damped spin dynamics with an adaptive timestep. @@ -142,3 +141,6 @@ Jonsson, Mills, Jacobsen. [(Bitzek)] Bitzek, Koskinen, Gahler, Moseler, Gumbsch, Phys Rev Lett, 97, 170201 (2006). +:link(Guenole) +[(Guenole)] Guenole, Nöhring, Vaid, Houllé, Xie, Prakash, Bitzek, +Preprint, arXiv:190802038 (2019).