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

doc/mass.html

@@ -65,9 +65,9 @@ is normally not used.
 </P>
 <P>If you define a <A HREF = "atom_style.html">hybrid atom style</A> which includes one
 (or more) sub-styles which require per-type mass and one (or more)
-sub-styles which require per-atom mass, then you must define both.  In
+sub-styles which require per-atom mass, then you must define both.
-this case the per-type mass will be ignored; only the per-atom mass
+However, in this case the per-type mass will be ignored; only the
-will be used by LAMMPS.
+per-atom mass will be used by LAMMPS.
 </P>
 <P><B>Restrictions:</B>
 </P>

doc/mass.txt

@@ -62,9 +62,9 @@ is normally not used.
 
 If you define a "hybrid atom style"_atom_style.html which includes one
 (or more) sub-styles which require per-type mass and one (or more)
-sub-styles which require per-atom mass, then you must define both.  In
+sub-styles which require per-atom mass, then you must define both.
-this case the per-type mass will be ignored; only the per-atom mass
+However, in this case the per-type mass will be ignored; only the
-will be used by LAMMPS.
+per-atom mass will be used by LAMMPS.
 
 [Restrictions:]
 

doc/min_modify.html

@@ -32,30 +32,29 @@
 <P><B>Description:</B>
 </P>
 <P>This command sets parameters that affect the energy minimization
-algorithms.  The various settings may affect the convergence rate and
+algorithms selected by the <A HREF = "min_style.html">min_style</A> command.  The
-overall number of force evaluations required by a minimization, so
+various settings may affect the convergence rate and overall number of
-users can experiment with these parameters to tune their
+force evaluations required by a minimization, so users can experiment
-minimizations.
+with these parameters to tune their minimizations.
 </P>
-<P>The minimization algorithms have an outer iteration (conjugate
+<P>The <I>cg</I> and <I>sd</I> minimization styles have an outer iteration and an
-gradient or steepest descent) and an inner iteration which is steps
+inner iteration which is steps along a one-dimensional line search in
-along a one-dimensional line search in a particular search direction.
+a particular search direction.  The <I>dmax</I> parameter is how far any
-The <I>dmax</I> parameter is how far any atom can move in a single line
+atom can move in a single line search in any dimension (x, y, or z).
-search in any dimension (x, y, or z).  Thus a value of 0.1 in real
+Thus a value of 0.1 in real <A HREF = "units.html">units</A> means no atom will move
-<A HREF = "units.html">units</A> means no atom will move further than 0.1 Angstroms
+further than 0.1 Angstroms in a single outer iteration.  This prevents
-in a single outer iteration.  This prevents highly overlapped atoms
+highly overlapped atoms from being moved long distances (e.g. through
-from being moved long distances (e.g. through another atom) due to
+another atom) due to large forces.
-large forces.
 </P>
-<P>The choice of line search algorithm can be selected via the <I>line</I>
+<P>The choice of line search algorithm for the <I>cg</I> and <I>sd</I> minimization
-keyword.  The default backtracking search is very robust and should
+styles can be selected via the <I>line</I> keyword.  The default
-always find a local energy minimum.  However, it will "converge" when
+backtracking search is robust and should always find a local energy
-it can no longer reduce the energy of the system.  Individual atom
+minimum.  However, it will "converge" when it can no longer reduce the
-forces may still be larger than desired at this point, because the
+energy of the system.  Individual atom forces may still be larger than
-energy change is measured as the difference of two large values
+desired at this point, because the energy change is measured as the
-(energy before and energy after) and that difference may be smaller
+difference of two large values (energy before and energy after) and
-than machine epsilon even if atoms could move in the gradient
+that difference may be smaller than machine epsilon even if atoms
-direction to reduce forces further.
+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

doc/min_modify.txt

@@ -27,30 +27,29 @@ min_modify dmax 0.2 :pre
 [Description:]
 
 This command sets parameters that affect the energy minimization
-algorithms.  The various settings may affect the convergence rate and
+algorithms selected by the "min_style"_min_style.html command.  The
-overall number of force evaluations required by a minimization, so
+various settings may affect the convergence rate and overall number of
-users can experiment with these parameters to tune their
+force evaluations required by a minimization, so users can experiment
-minimizations.
+with these parameters to tune their minimizations.
 
-The minimization algorithms have an outer iteration (conjugate
+The {cg} and {sd} minimization styles have an outer iteration and an
-gradient or steepest descent) and an inner iteration which is steps
+inner iteration which is steps along a one-dimensional line search in
-along a one-dimensional line search in a particular search direction.
+a particular search direction.  The {dmax} parameter is how far any
-The {dmax} parameter is how far any atom can move in a single line
+atom can move in a single line search in any dimension (x, y, or z).
-search in any dimension (x, y, or z).  Thus a value of 0.1 in real
+Thus a value of 0.1 in real "units"_units.html means no atom will move
-"units"_units.html means no atom will move further than 0.1 Angstroms
+further than 0.1 Angstroms in a single outer iteration.  This prevents
-in a single outer iteration.  This prevents highly overlapped atoms
+highly overlapped atoms from being moved long distances (e.g. through
-from being moved long distances (e.g. through another atom) due to
+another atom) due to large forces.
-large forces.
 
-The choice of line search algorithm can be selected via the {line}
+The choice of line search algorithm for the {cg} and {sd} minimization
-keyword.  The default backtracking search is very robust and should
+styles can be selected via the {line} keyword.  The default
-always find a local energy minimum.  However, it will "converge" when
+backtracking search is robust and should always find a local energy
-it can no longer reduce the energy of the system.  Individual atom
+minimum.  However, it will "converge" when it can no longer reduce the
-forces may still be larger than desired at this point, because the
+energy of the system.  Individual atom forces may still be larger than
-energy change is measured as the difference of two large values
+desired at this point, because the energy change is measured as the
-(energy before and energy after) and that difference may be smaller
+difference of two large values (energy before and energy after) and
-than machine epsilon even if atoms could move in the gradient
+that difference may be smaller than machine epsilon even if atoms
-direction to reduce forces further.
+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

doc/min_style.html

@@ -15,12 +15,12 @@
 </P>
 <PRE>min_style style 
 </PRE>
-<UL><LI>style = <I>cg</I> or <I>sd</I> 
+<UL><LI>style = <I>cg</I> or <I>hftn</I> or <I>sd</I> 
 </UL>
 <P><B>Examples:</B>
 </P>
 <PRE>min_style cg
-min_style sd 
+min_style hftn 
 </PRE>
 <P><B>Description:</B>
 </P>
@@ -35,6 +35,18 @@ variant affects how the direction is chosen and how the CG method is
 restarted when it ceases to make progress.  The PR variant is thought
 to be the most effective CG choice.
 </P>
+<P>Style <I>hftn</I> is a Hessian-free truncated Newton algorithm.  At each
+iteration a quadratic model of the energy potential is solved by a
+conjugate gradient inner iteration.  The Hessian (second derivatives)
+of the energy is not formed directly, but approximated in each
+conjugate search direction by a finite difference directional
+derivative.  When close to an energy minimum, the algorithm behaves
+like a Newton method and exhibits a quadratic convergence rate to high
+accuracy.  In most cases the behavior of <I>hftn</I> is similar to <I>cg</I>,
+but it offers another minimizer alternative if <I>cg</I> seems to perform
+poorly.  This style is not affected by the
+<A HREF = "min_modify.html">min_modify</A> command.
+</P>
 <P>Style <I>sd</I> is a steepest descent algorithm.  At each iteration, the
 search direction is set to the downhill direction corresponding to the
 force vector (negative gradient of energy).  Typically, steepest

doc/min_style.txt

@@ -11,12 +11,12 @@ min_style command :h3
 
 min_style style :pre
 
-style = {cg} or {sd} :ul
+style = {cg} or {hftn} or {sd} :ul
 
 [Examples:]
 
 min_style cg
-min_style sd :pre
+min_style hftn :pre
 
 [Description:]
 
@@ -31,6 +31,18 @@ variant affects how the direction is chosen and how the CG method is
 restarted when it ceases to make progress.  The PR variant is thought
 to be the most effective CG choice.
 
+Style {hftn} is a Hessian-free truncated Newton algorithm.  At each
+iteration a quadratic model of the energy potential is solved by a
+conjugate gradient inner iteration.  The Hessian (second derivatives)
+of the energy is not formed directly, but approximated in each
+conjugate search direction by a finite difference directional
+derivative.  When close to an energy minimum, the algorithm behaves
+like a Newton method and exhibits a quadratic convergence rate to high
+accuracy.  In most cases the behavior of {hftn} is similar to {cg},
+but it offers another minimizer alternative if {cg} seems to perform
+poorly.  This style is not affected by the
+"min_modify"_min_modify.html command.
+
 Style {sd} is a steepest descent algorithm.  At each iteration, the
 search direction is set to the downhill direction corresponding to the
 force vector (negative gradient of energy).  Typically, steepest

doc/shape.html

@@ -85,8 +85,8 @@ all 3 shape components the same.
 <P>If you define a <A HREF = "atom_style.html">hybrid atom style</A> which includes one
 (or more) sub-styles which require per-type shape and one (or more)
 sub-styles which require per-atom diameter, then you must define both.
-In this case the per-type shape will be ignored; only the per-atom
+However, in this case the per-type shape will be ignored; only the
-diameter will be used by LAMMPS.  Note that this means you can not
+per-atom diameter will be used by LAMMPS.  This means you cannot
 currently mix aspherical particles with per-atom diameter particles.
 </P>
 <P><B>Restrictions:</B>

doc/shape.txt

@@ -82,8 +82,8 @@ all 3 shape components the same.
 If you define a "hybrid atom style"_atom_style.html which includes one
 (or more) sub-styles which require per-type shape and one (or more)
 sub-styles which require per-atom diameter, then you must define both.
-In this case the per-type shape will be ignored; only the per-atom
+However, in this case the per-type shape will be ignored; only the
-diameter will be used by LAMMPS.  Note that this means you can not
+per-atom diameter will be used by LAMMPS.  This means you cannot
 currently mix aspherical particles with per-atom diameter particles.
 
 [Restrictions:]