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

doc/Section_commands.html

@@ -318,7 +318,7 @@ of each style or click on the style itself for a full description:
 </P>
 <DIV ALIGN=center><TABLE  BORDER=1 >
 <TR ALIGN="center"><TD ><A HREF = "fix_addforce.html">addforce</A></TD><TD ><A HREF = "fix_aveforce.html">aveforce</A></TD><TD ><A HREF = "fix_ave_atom.html">ave/atom</A></TD><TD ><A HREF = "fix_ave_spatial.html">ave/spatial</A></TD><TD ><A HREF = "fix_ave_time.html">ave/time</A></TD><TD ><A HREF = "fix_bond_break.html">bond/break</A></TD><TD ><A HREF = "fix_bond_create.html">bond/create</A></TD><TD ><A HREF = "fix_bond_swap.html">bond/swap</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "fix_box_relax.html">box</A></TD><TD ><A HREF = "fix_com.html">com</A></TD><TD ><A HREF = "fix_coord_original.html">coord/original</A></TD><TD ><A HREF = "fix_deform.html">deform</A></TD><TD ><A HREF = "fix_deposit.html">deposit</A></TD><TD ><A HREF = "fix_drag.html">drag</A></TD><TD ><A HREF = "fix_dt_reset.html">dt/reset</A></TD><TD ><A HREF = "fix_efield.html">efield</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "fix_box_relax.html">box/relax</A></TD><TD ><A HREF = "fix_com.html">com</A></TD><TD ><A HREF = "fix_coord_original.html">coord/original</A></TD><TD ><A HREF = "fix_deform.html">deform</A></TD><TD ><A HREF = "fix_deposit.html">deposit</A></TD><TD ><A HREF = "fix_drag.html">drag</A></TD><TD ><A HREF = "fix_dt_reset.html">dt/reset</A></TD><TD ><A HREF = "fix_efield.html">efield</A></TD></TR>
 <TR ALIGN="center"><TD ><A HREF = "fix_enforce2d.html">enforce2d</A></TD><TD ><A HREF = "fix_freeze.html">freeze</A></TD><TD ><A HREF = "fix_gravity.html">gravity</A></TD><TD ><A HREF = "fix_gyration.html">gyration</A></TD><TD ><A HREF = "fix_heat.html">heat</A></TD><TD ><A HREF = "fix_indent.html">indent</A></TD><TD ><A HREF = "fix_langevin.html">langevin</A></TD><TD ><A HREF = "fix_lineforce.html">lineforce</A></TD></TR>
 <TR ALIGN="center"><TD ><A HREF = "fix_msd.html">msd</A></TD><TD ><A HREF = "fix_momentum.html">momentum</A></TD><TD ><A HREF = "fix_nph.html">nph</A></TD><TD ><A HREF = "fix_npt.html">npt</A></TD><TD ><A HREF = "fix_npt_asphere.html">npt/asphere</A></TD><TD ><A HREF = "fix_npt_sphere.html">npt/sphere</A></TD><TD ><A HREF = "fix_nve.html">nve</A></TD><TD ><A HREF = "fix_nve_asphere.html">nve/asphere</A></TD></TR>
 <TR ALIGN="center"><TD ><A HREF = "fix_nve_limit.html">nve/limit</A></TD><TD ><A HREF = "fix_nve_noforce.html">nve/noforce</A></TD><TD ><A HREF = "fix_nve_sphere.html">nve/sphere</A></TD><TD ><A HREF = "fix_nvt.html">nvt</A></TD><TD ><A HREF = "fix_nvt_asphere.html">nvt/asphere</A></TD><TD ><A HREF = "fix_nvt_sllod.html">nvt/sllod</A></TD><TD ><A HREF = "fix_nvt_sphere.html">nvt/sphere</A></TD><TD ><A HREF = "fix_orient_fcc.html">orient/fcc</A></TD></TR>

doc/Section_commands.txt

@@ -383,7 +383,7 @@ of each style or click on the style itself for a full description:
 "bond/break"_fix_bond_break.html,
 "bond/create"_fix_bond_create.html,
 "bond/swap"_fix_bond_swap.html,
-"box"_fix_box_relax.html,
+"box/relax"_fix_box_relax.html,
 "com"_fix_com.html,
 "coord/original"_fix_coord_original.html,
 "deform"_fix_deform.html,

doc/compute_pressure.html

@@ -19,7 +19,7 @@
 <LI>pressure = style name of this compute command
 <LI>temp-ID = ID of compute that calculates temperature
 <LI>zero or more keywords may be appended
-<LI>keyword = <I>ke</I> or <I>pair</I> or <I>bond</I> or <I>angle</I> or <I>dihedral</I> or <I>improper</I> or <I>kspace</I> or <I>fix</I> 
+<LI>keyword = <I>ke</I> or <I>pair</I> or <I>bond</I> or <I>angle</I> or <I>dihedral</I> or <I>improper</I> or <I>kspace</I> or <I>fix</I> or <I>virial</I> 
 </UL>
 <P><B>Examples:</B>
 </P>
@@ -59,11 +59,12 @@ tensor:
 <CENTER><IMG SRC = "Eqs/pressure_tensor.jpg">
 </CENTER>
 <P>If no extra keywords are listed, the entire equations above are
-calculated which include a temperature (or kinetic energy) term and
+calculated which include a kinetic energy (temperature) term and the
-the virial as the sum of pair, bond, angle, dihedral, improper, kspace
+virial as the sum of pair, bond, angle, dihedral, improper, kspace
 (long-range), and fix contributions to the force on each atom.  If any
 extra keywords are listed, then only those components are summed to
-compute temperature or ke and/or the virial.
+compute temperature or ke and/or the virial.  The <I>virial</I> keyword
+means include all terms except the kinetic energy <I>ke</I>.
 </P>
 <P>The temperature and kinetic energy tensor is not calculated by this
 compute, but rather by the temperature compute specified with the

doc/compute_pressure.txt

@@ -16,7 +16,7 @@ ID, group-ID are documented in "compute"_compute.html command
 pressure = style name of this compute command
 temp-ID = ID of compute that calculates temperature
 zero or more keywords may be appended
-keyword = {ke} or {pair} or {bond} or {angle} or {dihedral} or {improper} or {kspace} or {fix} :ul
+keyword = {ke} or {pair} or {bond} or {angle} or {dihedral} or {improper} or {kspace} or {fix} or {virial} :ul
 
 [Examples:]
 
@@ -56,11 +56,12 @@ tensor:
 :c,image(Eqs/pressure_tensor.jpg)
 
 If no extra keywords are listed, the entire equations above are
-calculated which include a temperature (or kinetic energy) term and
+calculated which include a kinetic energy (temperature) term and the
-the virial as the sum of pair, bond, angle, dihedral, improper, kspace
+virial as the sum of pair, bond, angle, dihedral, improper, kspace
 (long-range), and fix contributions to the force on each atom.  If any
 extra keywords are listed, then only those components are summed to
-compute temperature or ke and/or the virial.
+compute temperature or ke and/or the virial.  The {virial} keyword
+means include all terms except the kinetic energy {ke}.
 
 The temperature and kinetic energy tensor is not calculated by this
 compute, but rather by the temperature compute specified with the

doc/compute_stress_atom.html

@@ -18,7 +18,7 @@
 <UL><LI>ID, group-ID are documented in <A HREF = "compute.html">compute</A> command
 <LI>stress/atom = style name of this compute command
 <LI>zero or more keywords may be appended
-<LI>keyword = <I>ke</I> or <I>pair</I> or <I>bond</I> or <I>angle</I> or <I>dihedral</I> or <I>improper</I> or <I>fix</I> 
+<LI>keyword = <I>ke</I> or <I>pair</I> or <I>bond</I> or <I>angle</I> or <I>dihedral</I> or <I>improper</I> or <I>fix</I> or <I>virial</I> 
 </UL>
 <P><B>Examples:</B>
 </P>
@@ -67,7 +67,9 @@ command.
 </P>
 <P>If no extra keywords are listed, all of the terms in this formula are
 included in the per-atom stress tensor.  If any extra keywords are
-listed, only those terms are summed to compute the tensor.
+listed, only those terms are summed to compute the tensor.  The
+<I>virial</I> keyword means include all terms except the kinetic energy
+<I>ke</I>.
 </P>
 <P>Note that the stress for each atom is due to its interaction with all
 other atoms in the simulation, not just with other atoms in the group.

doc/compute_stress_atom.txt

@@ -15,7 +15,7 @@ compute ID group-ID stress/atom keyword ... :pre
 ID, group-ID are documented in "compute"_compute.html command
 stress/atom = style name of this compute command
 zero or more keywords may be appended
-keyword = {ke} or {pair} or {bond} or {angle} or {dihedral} or {improper} or {fix} :ul
+keyword = {ke} or {pair} or {bond} or {angle} or {dihedral} or {improper} or {fix} or {virial} :ul
 
 [Examples:]
 
@@ -64,7 +64,9 @@ command.
 
 If no extra keywords are listed, all of the terms in this formula are
 included in the per-atom stress tensor.  If any extra keywords are
-listed, only those terms are summed to compute the tensor.
+listed, only those terms are summed to compute the tensor.  The
+{virial} keyword means include all terms except the kinetic energy
+{ke}.
 
 Note that the stress for each atom is due to its interaction with all
 other atoms in the simulation, not just with other atoms in the group.

doc/fix_box_relax.html

@@ -27,15 +27,16 @@
 </PRE>
 <LI>zero or more keyword/value pairs may be appended to the args 
 
-<LI>keyword = <I>dilate</I> 
+<LI>keyword = <I>dilate</I> or <I>vmax</I> 
 
-<PRE>  <I>dilate</I> value = <I>all</I> or <I>partial</I> 
+<PRE>  <I>dilate</I> value = <I>all</I> or <I>partial</I>
+  <I>vmax</I> value = fraction = max allowed volume change in one iteration 
 </PRE>
 
 </UL>
 <P><B>Examples:</B>
 </P>
-<PRE>fix 1 all box/relax xyz 0.0
+<PRE>fix 1 all box/relax xyz 0.0 vmax 0.001
 fix 2 water box/relax aniso 0.0 0.0 1000.0 dilate partial 
 </PRE>
 <P><B>Description:</B>
@@ -82,24 +83,57 @@ re-scaled.  This can be useful for leaving the coordinates of atoms in
 a solid substrate unchanged and controlling the pressure of a
 surrounding fluid.
 </P>
+<P>The <I>vmax</I> keyword can be used to limit the fractional change in the
+volume of the simulation box that can occur in one iteration of the
+minimizer.  If the pressure is not settling down during the
+minimization this can be because the volume is fluctuating too much.
+The specfied fraction must be greater than 0.0 and should be << 1.0.
+A value of 0.001 means the volume cannot change by more than 1/10 of a
+percent in one iteration for style <I>xyz</I>.  For the other styles it
+means no linear dimension of the simulation box can change by more
+than 1/10 of a percent.
+</P>
+<P>IMPORTANT NOTE: As normally computed, pressure includes a kinetic-
+energy or temperature-dependent component; see the <A HREF = "compute_pressure.html">compute
+pressure</A> command.  However, atom velocities are
+ignored during a minimization, and the applied pressure(s) specified
+with this command are assumed to only be the virial component of the
+pressure (the non-kinetic portion).  Thus if atoms have a non-zero
+temperature and you print the usual thermodynamic pressure, it may not
+appear the system is converging to your specified pressure.  The
+solution for this is to either (a) zero the velocities of all atoms
+before performing the minimization, or (b) make sure you are
+monitoring the pressure without its kinetic component.  The latter
+can be done by outputting the pressure from the fix this command
+creates (see below) or a pressure fix you define yourself.
+</P>
+<P>IMPORTANT NOTE: Because pressure is often a very sensitive function of
+volume, it can be difficult for the minimizer to equilibrate the
+system the desired pressure with high precision.  Some techiniques
+that seem to help are (a) use the "min_modify line quadratic" option
+when minimizing with box relaxtions, and (b) minimize several times in
+succession if need be, to drive the pressure closer to the target
+pressure.  Also note that some systems (e.g. liquids) will not sustain
+an anisotropic applied pressure, which means the minimizer will not
+converge.
+</P>
 <HR>
 
 <P>This fix computes a temperature and pressure each timestep.  The
 temperature is used to compute the kinetic contribution to the
-pressure.  Since atom velocities do not change during minimization,
+pressure, even though this is subsequently ignored by default.  To do
-that contribution will depend on what atom velocities are at the
+this, the fix creates its own computes of style "temp" and "pressure",
-beginning of the minimization procedure, and will remain constant.  To
+as if these commands had been issued:
-do this, the fix creates its own computes of style "temp" and
-"pressure", as if these commands had been issued:
 </P>
 <PRE>compute fix-ID_temp group-ID temp
-compute fix-ID_press group-ID pressure fix-ID_temp 
+compute fix-ID_press group-ID pressure fix-ID_temp virial 
 </PRE>
 <P>See the <A HREF = "compute_temp.html">compute temp</A> and <A HREF = "compute_pressure.html">compute
 pressure</A> commands for details.  Note that the
 IDs of the new computes are the fix-ID + underscore + "temp" or fix_ID
 + underscore + "press", and the group for the new computes is the same
-as the fix group.
+as the fix group.  Also note that the pressure compute does not
+include a kinetic component.
 </P>
 <P>Note that these are NOT the computes used by thermodynamic output (see
 the <A HREF = "thermo_style.html">thermo_style</A> command) with ID = <I>thermo_temp</I>
@@ -111,17 +145,6 @@ custom</A> command using the appropriate compute-ID.
 It also means that changing attributes of <I>thermo_temp</I> or
 <I>thermo_press</I> will have no effect on this fix.
 </P>
-<P>Like other fixes that perform thermostatting, this fix can be used
-with <A HREF = "compute.html">compute commands</A> that calculate a temperature
-after removing a "bias" from the atom velocities.  E.g. removing the
-center-of-mass velocity from a group of atoms or only calculating
-temperature on the x-component of velocity or only calculating
-temperature for atoms in a geometric region.  This is not done by
-default, but only if the <A HREF = "fix_modify.html">fix_modify</A> command is used
-to assign a temperature compute to this fix that includes such a bias
-term.  See the doc pages for individual <A HREF = "compute.html">compute
-commands</A> to determine which ones include a bias.
-</P>
 <HR>
 
 <P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
@@ -132,11 +155,10 @@ files</A>.
 <P>The <A HREF = "fix_modify.html">fix_modify</A> <I>temp</I> and <I>press</I> options are
 supported by this fix.  You can use them to assign a
 <A HREF = "compute.html">compute</A> you have defined to this fix which will be used
-in its temperature and pressure calculation, as described above.  If
+in its temperature and pressure calculation, as described above.  Note
-you do this, note that the kinetic energy derived from the compute
+that as described above, if you assign a pressure compute to this fix
-temperature should be consistent with the virial term computed using
+that includes a kinetic energy component it will affect the
-all atoms for the pressure.  LAMMPS will warn you if you choose to
+minimization, most likely in an undesirable way.
-compute temperature on a subset of atoms.
 </P>
 <P>IMPORTANT NOTE: If both the <I>temp</I> and <I>press</I> keywords are used in a
 single thermo_modify command (or in two separate commands), then the
@@ -156,8 +178,8 @@ the <A HREF = "run.html">run</A> command.
 </P>
 <P>This fix is invoked during <A HREF = "minimize.html">energy minimization</A>, but
 not for the purpose of adding a contribution to the energy or forces
-being minimized.  Instead it alters the box geometry as described
+being minimized.  Instead it alters the simulation box geometry as
-above.
+described above.
 </P>
 <P><B>Restrictions:</B>
 </P>
@@ -171,6 +193,6 @@ periodic.
 </P>
 <P><B>Default:</B>
 </P>
-<P>The keyword default is dilate = all.
+<P>The keyword defaults are dilate = all and vmax = 0.0001.
 </P>
 </HTML>

doc/fix_box_relax.txt

@@ -20,13 +20,14 @@ style = {xyz} or {xy} or {yz} or {xz} or {aniso} :l
     Px,Py,Pz = desired pressure in x,y,z (pressure units) :pre
 
 zero or more keyword/value pairs may be appended to the args :l
-keyword = {dilate} :l
+keyword = {dilate} or {vmax} :l
-  {dilate} value = {all} or {partial} :pre
+  {dilate} value = {all} or {partial}
+  {vmax} value = fraction = max allowed volume change in one iteration :pre
 :ule
 
 [Examples:]
 
-fix 1 all box/relax xyz 0.0
+fix 1 all box/relax xyz 0.0 vmax 0.001
 fix 2 water box/relax aniso 0.0 0.0 1000.0 dilate partial :pre
 
 [Description:]
@@ -73,24 +74,57 @@ re-scaled.  This can be useful for leaving the coordinates of atoms in
 a solid substrate unchanged and controlling the pressure of a
 surrounding fluid.
 
+The {vmax} keyword can be used to limit the fractional change in the
+volume of the simulation box that can occur in one iteration of the
+minimizer.  If the pressure is not settling down during the
+minimization this can be because the volume is fluctuating too much.
+The specfied fraction must be greater than 0.0 and should be << 1.0.
+A value of 0.001 means the volume cannot change by more than 1/10 of a
+percent in one iteration for style {xyz}.  For the other styles it
+means no linear dimension of the simulation box can change by more
+than 1/10 of a percent.
+
+IMPORTANT NOTE: As normally computed, pressure includes a kinetic-
+energy or temperature-dependent component; see the "compute
+pressure"_compute_pressure.html command.  However, atom velocities are
+ignored during a minimization, and the applied pressure(s) specified
+with this command are assumed to only be the virial component of the
+pressure (the non-kinetic portion).  Thus if atoms have a non-zero
+temperature and you print the usual thermodynamic pressure, it may not
+appear the system is converging to your specified pressure.  The
+solution for this is to either (a) zero the velocities of all atoms
+before performing the minimization, or (b) make sure you are
+monitoring the pressure without its kinetic component.  The latter
+can be done by outputting the pressure from the fix this command
+creates (see below) or a pressure fix you define yourself.
+
+IMPORTANT NOTE: Because pressure is often a very sensitive function of
+volume, it can be difficult for the minimizer to equilibrate the
+system the desired pressure with high precision.  Some techiniques
+that seem to help are (a) use the "min_modify line quadratic" option
+when minimizing with box relaxtions, and (b) minimize several times in
+succession if need be, to drive the pressure closer to the target
+pressure.  Also note that some systems (e.g. liquids) will not sustain
+an anisotropic applied pressure, which means the minimizer will not
+converge.
+
 :line
 
 This fix computes a temperature and pressure each timestep.  The
 temperature is used to compute the kinetic contribution to the
-pressure.  Since atom velocities do not change during minimization,
+pressure, even though this is subsequently ignored by default.  To do
-that contribution will depend on what atom velocities are at the
+this, the fix creates its own computes of style "temp" and "pressure",
-beginning of the minimization procedure, and will remain constant.  To
+as if these commands had been issued:
-do this, the fix creates its own computes of style "temp" and
-"pressure", as if these commands had been issued:
 
 compute fix-ID_temp group-ID temp
-compute fix-ID_press group-ID pressure fix-ID_temp :pre
+compute fix-ID_press group-ID pressure fix-ID_temp virial :pre
 
 See the "compute temp"_compute_temp.html and "compute
 pressure"_compute_pressure.html commands for details.  Note that the
 IDs of the new computes are the fix-ID + underscore + "temp" or fix_ID
 + underscore + "press", and the group for the new computes is the same
-as the fix group.
+as the fix group.  Also note that the pressure compute does not
+include a kinetic component.
 
 Note that these are NOT the computes used by thermodynamic output (see
 the "thermo_style"_thermo_style.html command) with ID = {thermo_temp}
@@ -102,17 +136,6 @@ custom"_thermo_style.html command using the appropriate compute-ID.
 It also means that changing attributes of {thermo_temp} or
 {thermo_press} will have no effect on this fix.
 
-Like other fixes that perform thermostatting, this fix can be used
-with "compute commands"_compute.html that calculate a temperature
-after removing a "bias" from the atom velocities.  E.g. removing the
-center-of-mass velocity from a group of atoms or only calculating
-temperature on the x-component of velocity or only calculating
-temperature for atoms in a geometric region.  This is not done by
-default, but only if the "fix_modify"_fix_modify.html command is used
-to assign a temperature compute to this fix that includes such a bias
-term.  See the doc pages for individual "compute
-commands"_compute.html to determine which ones include a bias.
-
 :line
 
 [Restart, fix_modify, output, run start/stop, minimize info:]
@@ -123,11 +146,10 @@ files"_restart.html.
 The "fix_modify"_fix_modify.html {temp} and {press} options are
 supported by this fix.  You can use them to assign a
 "compute"_compute.html you have defined to this fix which will be used
-in its temperature and pressure calculation, as described above.  If
+in its temperature and pressure calculation, as described above.  Note
-you do this, note that the kinetic energy derived from the compute
+that as described above, if you assign a pressure compute to this fix
-temperature should be consistent with the virial term computed using
+that includes a kinetic energy component it will affect the
-all atoms for the pressure.  LAMMPS will warn you if you choose to
+minimization, most likely in an undesirable way.
-compute temperature on a subset of atoms.
 
 IMPORTANT NOTE: If both the {temp} and {press} keywords are used in a
 single thermo_modify command (or in two separate commands), then the
@@ -147,8 +169,8 @@ the "run"_run.html command.
 
 This fix is invoked during "energy minimization"_minimize.html, but
 not for the purpose of adding a contribution to the energy or forces
-being minimized.  Instead it alters the box geometry as described
+being minimized.  Instead it alters the simulation box geometry as
-above.
+described above.
 
 [Restrictions:]
 
@@ -162,4 +184,4 @@ periodic.
 
 [Default:]
 
-The keyword default is dilate = all.
+The keyword defaults are dilate = all and vmax = 0.0001.