git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@2604 f3b2605a-c512-4ea7-a41b-209d697bcdaa

doc/min_modify.html

@@ -17,9 +17,11 @@
 </PRE>
 <UL><LI>one or more keyword/value pairs may be listed 
 
-keyword = <I>dmax</I>
+keyword = <I>dmax</I> or <I>line</I>
   <I>dmax</I> value = max
     max = maximum distance for line search to move (distance units)
+  <I>line</I> value = <I>backtrack</I> or <I>quadratic</I>
+    value = style of linesearch to use
 
 </UL>
 <P><B>Examples:</B>
@@ -29,7 +31,7 @@ keyword = <I>dmax</I>
 <P><B>Description:</B>
 </P>
 <P>This command sets parameters that affect the energy minimization
-algorithms.  The various settings may effect the convergence rate and
+algorithms.  The various settings may affect the convergence rate and
 overall number of force evaluations required by a minimization, so
 users can experiment with these parameters to tune their
 minimizations.
@@ -39,10 +41,25 @@ gradient or steepest descent) and an inner iteration which is steps
 along a one-dimensional line search in a particular search direction.
 The <I>dmax</I> parameter is how far any atom can move in a single line
 search in any dimension (x, y, or z).  Thus a value of 0.1 in real
-distance units means no atom will move further than 0.1 Angstroms in a
+<A HREF = "units.html">units</A> means no atom will move further than 0.1 Angstroms
-single outer iteration.  This is typically set to avoid the
+in a single outer iteration.  This prevents highly overlapped atoms
-possibility than one atom will be moved through another due to strong
+from being moved long distances (e.g. through another atom) due to
-overlapping forces.
+large forces.
+</P>
+<P>The choice of line search algorithm can be selected via the <I>line</I>
+keyword.  The default backtracking search is very robust and should
+always find a local energy minimum.  However, it will "converge" when
+it can no longer reduce the energy of the system.  Individual atom
+forces may still be larger than desired at this point, because the
+energy change is measured as the difference of two large values
+(energy before and energy after) and that difference may be smaller
+than machine epsilon even if atoms could move in the gradient
+direction to reduce forces further.
+</P>
+<P>By contast, the <I>quadratic</I> line search algorithm is often able to
+reduce forces closer to 0.0.  It may also be more efficient than the
+backtracking algorithm by requiring fewer energy/force evaluations.
+However, it may not be as robust for some problems.
 </P>
 <P><B>Restrictions:</B> none
 </P>
@@ -52,6 +69,6 @@ overlapping forces.
 </P>
 <P><B>Default:</B>
 </P>
-<P>The option defaults are dmax = 0.1.
+<P>The option defaults are dmax = 0.1 and line = backtrack.
 </P>
 </HTML>

doc/min_modify.txt

@@ -13,9 +13,11 @@ min_modify command :h3
 min_modify keyword values ... :pre
 
 one or more keyword/value pairs may be listed :ulb,l
-keyword = {dmax}
+keyword = {dmax} or {line}
   {dmax} value = max
     max = maximum distance for line search to move (distance units)
+  {line} value = {backtrack} or {quadratic}
+    value = style of linesearch to use
 :ule
 
 [Examples:]
@@ -25,7 +27,7 @@ min_modify dmax 0.2 :pre
 [Description:]
 
 This command sets parameters that affect the energy minimization
-algorithms.  The various settings may effect the convergence rate and
+algorithms.  The various settings may affect the convergence rate and
 overall number of force evaluations required by a minimization, so
 users can experiment with these parameters to tune their
 minimizations.
@@ -35,10 +37,25 @@ gradient or steepest descent) and an inner iteration which is steps
 along a one-dimensional line search in a particular search direction.
 The {dmax} parameter is how far any atom can move in a single line
 search in any dimension (x, y, or z).  Thus a value of 0.1 in real
-distance units means no atom will move further than 0.1 Angstroms in a
+"units"_units.html means no atom will move further than 0.1 Angstroms
-single outer iteration.  This is typically set to avoid the
+in a single outer iteration.  This prevents highly overlapped atoms
-possibility than one atom will be moved through another due to strong
+from being moved long distances (e.g. through another atom) due to
-overlapping forces.
+large forces.
+
+The choice of line search algorithm can be selected via the {line}
+keyword.  The default backtracking search is very robust and should
+always find a local energy minimum.  However, it will "converge" when
+it can no longer reduce the energy of the system.  Individual atom
+forces may still be larger than desired at this point, because the
+energy change is measured as the difference of two large values
+(energy before and energy after) and that difference may be smaller
+than machine epsilon even if atoms could move in the gradient
+direction to reduce forces further.
+
+By contast, the {quadratic} line search algorithm is often able to
+reduce forces closer to 0.0.  It may also be more efficient than the
+backtracking algorithm by requiring fewer energy/force evaluations.
+However, it may not be as robust for some problems.
 
 [Restrictions:] none
 
@@ -48,4 +65,4 @@ overlapping forces.
 
 [Default:]
 
-The option defaults are dmax = 0.1.
+The option defaults are dmax = 0.1 and line = backtrack.