From b7efab22779359087f38e5502bbc9631ca59598c Mon Sep 17 00:00:00 2001
From: sjplimp <sjplimp@f3b2605a-c512-4ea7-a41b-209d697bcdaa>
Date: Mon, 17 Jun 2013 16:08:18 +0000
Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@10081
 f3b2605a-c512-4ea7-a41b-209d697bcdaa

---
 doc/fix_efield.html | 95 ++++++++++++++++++++++++++++++++++++---------
 doc/fix_efield.txt  | 90 ++++++++++++++++++++++++++++++++----------
 2 files changed, 146 insertions(+), 39 deletions(-)

diff --git a/doc/fix_efield.html b/doc/fix_efield.html
index 7e79e0e7ff..80c642d06f 100644
--- a/doc/fix_efield.html
+++ b/doc/fix_efield.html
@@ -13,12 +13,24 @@
 </H3>
 <P><B>Syntax:</B>
 </P>
-<PRE>fix ID group-ID efield ex ey ez 
+<PRE>fix ID group-ID efield ex ey ez keyword value ... 
 </PRE>
-<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command
-<LI>efield = style name of this fix command
-<LI>ex,ey,ez = E-field component values (electric field units)
+<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command 
+
+<LI>efield = style name of this fix command 
+
+<LI>ex,ey,ez = E-field component values (electric field units) 
+
 <LI>any of ex,ey,ez can be a variable (see below) 
+
+<LI>zero or more keyword/value pairs may be appended to args 
+
+<LI>keyword = <I><I>energy</I> 
+
+<PRE>  <I>energy</I> value = v_name
+    v_name = variable with name that calculates the potential energy of each atom in the added E-field 
+</PRE>
+
 </UL>
 <P><B>Examples:</B>
 </P>
@@ -37,11 +49,13 @@ can be specified as an equal-style or atom-style
 <A HREF = "variable.html">variable</A>, namely <I>ex</I>, <I>ey</I>, <I>ez</I>.  If the value is a
 variable, it should be specified as v_name, where name is the variable
 name.  In this case, the variable will be evaluated each timestep, and
-its value used to determine the E-field component.  For point-dipoles,
-equal-style variables can be used, but atom-style variables are not
-currently supported, since they imply a spatial gradient in the
-electric field which means additional terms with gradients of the
-field are required for the force and torque on dipoles.
+its value used to determine the E-field component.
+</P>
+<P>For point-dipoles, equal-style variables can be used, but atom-style
+variables are not currently supported, since they imply a spatial
+gradient in the electric field which means additional terms with
+gradients of the field are required for the force and torque on
+dipoles.
 </P>
 <P>Equal-style variables can specify formulas with various mathematical
 functions, and include <A HREF = "thermo_style.html">thermo_style</A> command
@@ -53,28 +67,71 @@ variables but can also include per-atom values, such as atom
 coordinates.  Thus it is easy to specify a spatially-dependent E-field
 with optional time-dependence as well.
 </P>
+<HR>
+
+<P>Adding a force or torque to atoms implies a change in their potential
+energy as they move or rotate due to the applied E-field.
+</P>
+<P>For dynamics via the "run" command, this energy can be optionally
+added to the system's potential energy for thermodynamic output (see
+below).  For energy minimization via the "minimize" command, this
+energy must be added to the system's potential energy to formulate a
+self-consistent minimization problem (see below).
+</P>
+<P>The <I>energy</I> keyword is not allowed if the added field is a constant
+vector (ex,ey,ez), with all components defined as numeric constants
+and not as variables.  This is because LAMMPS can compute the energy
+for each charged particle directly as E = -x dot qE = -q (x*ex + y*ey
++ z*ez), so that -Grad(E) = F.  Similarly for point-dipole particles
+the energy can be computed as E = -mu dot E = -(mux*ex + muy*ey +
+muz*ez),
+</P>
+<P>The <I>energy</I> keyword is optional if the added force is defined with
+one or more variables, and if you are performing dynamics via the
+<A HREF = "run.html">run</A> command.  If the keyword is not used, LAMMPS will set
+the energy to 0.0, which is typically fine for dynamics.
+</P>
+<P>The <I>energy</I> keyword is required if the added force is defined with
+one or more variables, and you are performing energy minimization via
+the "minimize" command for charged particles.  It is not required for
+point-dipoles, but a warning is issued since the minimizer in LAMMPS
+does not rotate dipoles, so you should not expect to be able to
+minimize the orientation of dipoles in an applied electric field.
+</P>
+<P>The <I>energy</I> keyword specifies the name of an atom-style
+<A HREF = "variable.html">variable</A> which is used to compute the energy of each
+atom as function of its position.  Like variables used for <I>ex</I>, <I>ey</I>,
+<I>ez</I>, the energy variable is specified as v_name, where name is the
+variable name.
+</P>
+<P>Note that when the <I>energy</I> keyword is used during an energy
+minimization, you must insure that the formula defined for the
+atom-style <A HREF = "variable.html">variable</A> is consistent with the force
+variable formulas, i.e. that -Grad(E) = F.  For example, if the force
+due to the electric field were a spring-like F = kx, then the energy
+formula should be E = -0.5kx^2.  If you don't do this correctly, the
+minimization will not converge properly.
+</P>
 <P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
 </P>
 <P>No information about this fix is written to <A HREF = "restart.html">binary restart
 files</A>.  
 </P>
 <P>The <A HREF = "fix_modify.html">fix_modify</A> <I>energy</I> option is supported by this
-fix to add the potential "energy" inferred by the added force to the
-system's potential energy as part of <A HREF = "thermo_style.html">thermodynamic
-output</A>.  This is a fictitious quantity but is
-needed so that the <A HREF = "minimize.html">minimize</A> command can include the
-forces added by this fix in a consistent manner.  I.e. there is a
-decrease in potential energy when atoms move in the direction of the
-added force.  The potential energy contribution of dipoles in the
-electric field is also included.
+fix to add the potential "energy" inferred by the added force due to
+the electric field to the system's potential energy as part of
+<A HREF = "thermo_style.html">thermodynamic output</A>.  This is a fictitious
+quantity but is needed so that the <A HREF = "minimize.html">minimize</A> command
+can include the forces added by this fix in a consistent manner.
+I.e. there is a decrease in potential energy when atoms move in the
+direction of the added force due to the electric field.
 </P>
 <P>This fix computes a global scalar and a global 3-vector of forces,
 which can be accessed by various <A HREF = "Section_howto.html#howto_15">output
 commands</A>.  The scalar is the potential
 energy discussed above.  The vector is the total force added to the
 group of atoms.  The scalar and vector values calculated by this fix
-are "extensive".  The added torques for point-dipoles cannot currently
-be output in this manner.
+are "extensive".
 </P>
 <P>No parameter of this fix can be used with the <I>start/stop</I> keywords of
 the <A HREF = "run.html">run</A> command.
diff --git a/doc/fix_efield.txt b/doc/fix_efield.txt
index 04d88a87b2..dccb04c737 100644
--- a/doc/fix_efield.txt
+++ b/doc/fix_efield.txt
@@ -10,12 +10,17 @@ fix efield command :h3
 
 [Syntax:]
 
-fix ID group-ID efield ex ey ez :pre
+fix ID group-ID efield ex ey ez keyword value ... :pre
 
-ID, group-ID are documented in "fix"_fix.html command
-efield = style name of this fix command
-ex,ey,ez = E-field component values (electric field units)
-any of ex,ey,ez can be a variable (see below) :ul
+ID, group-ID are documented in "fix"_fix.html command :ulb,l
+efield = style name of this fix command :l
+ex,ey,ez = E-field component values (electric field units) :l
+any of ex,ey,ez can be a variable (see below) :l
+zero or more keyword/value pairs may be appended to args :l
+keyword = {{energy} :l
+  {energy} value = v_name
+    v_name = variable with name that calculates the potential energy of each atom in the added E-field :pre
+:ule
 
 [Examples:]
 
@@ -34,11 +39,13 @@ can be specified as an equal-style or atom-style
 "variable"_variable.html, namely {ex}, {ey}, {ez}.  If the value is a
 variable, it should be specified as v_name, where name is the variable
 name.  In this case, the variable will be evaluated each timestep, and
-its value used to determine the E-field component.  For point-dipoles,
-equal-style variables can be used, but atom-style variables are not
-currently supported, since they imply a spatial gradient in the
-electric field which means additional terms with gradients of the
-field are required for the force and torque on dipoles.
+its value used to determine the E-field component.
+
+For point-dipoles, equal-style variables can be used, but atom-style
+variables are not currently supported, since they imply a spatial
+gradient in the electric field which means additional terms with
+gradients of the field are required for the force and torque on
+dipoles.
 
 Equal-style variables can specify formulas with various mathematical
 functions, and include "thermo_style"_thermo_style.html command
@@ -50,28 +57,71 @@ variables but can also include per-atom values, such as atom
 coordinates.  Thus it is easy to specify a spatially-dependent E-field
 with optional time-dependence as well.
 
+:line 
+
+Adding a force or torque to atoms implies a change in their potential
+energy as they move or rotate due to the applied E-field.
+
+For dynamics via the "run" command, this energy can be optionally
+added to the system's potential energy for thermodynamic output (see
+below).  For energy minimization via the "minimize" command, this
+energy must be added to the system's potential energy to formulate a
+self-consistent minimization problem (see below).
+
+The {energy} keyword is not allowed if the added field is a constant
+vector (ex,ey,ez), with all components defined as numeric constants
+and not as variables.  This is because LAMMPS can compute the energy
+for each charged particle directly as E = -x dot qE = -q (x*ex + y*ey
++ z*ez), so that -Grad(E) = F.  Similarly for point-dipole particles
+the energy can be computed as E = -mu dot E = -(mux*ex + muy*ey +
+muz*ez),
+
+The {energy} keyword is optional if the added force is defined with
+one or more variables, and if you are performing dynamics via the
+"run"_run.html command.  If the keyword is not used, LAMMPS will set
+the energy to 0.0, which is typically fine for dynamics.
+
+The {energy} keyword is required if the added force is defined with
+one or more variables, and you are performing energy minimization via
+the "minimize" command for charged particles.  It is not required for
+point-dipoles, but a warning is issued since the minimizer in LAMMPS
+does not rotate dipoles, so you should not expect to be able to
+minimize the orientation of dipoles in an applied electric field.
+
+The {energy} keyword specifies the name of an atom-style
+"variable"_variable.html which is used to compute the energy of each
+atom as function of its position.  Like variables used for {ex}, {ey},
+{ez}, the energy variable is specified as v_name, where name is the
+variable name.
+
+Note that when the {energy} keyword is used during an energy
+minimization, you must insure that the formula defined for the
+atom-style "variable"_variable.html is consistent with the force
+variable formulas, i.e. that -Grad(E) = F.  For example, if the force
+due to the electric field were a spring-like F = kx, then the energy
+formula should be E = -0.5kx^2.  If you don't do this correctly, the
+minimization will not converge properly.
+
 [Restart, fix_modify, output, run start/stop, minimize info:]
 
 No information about this fix is written to "binary restart
 files"_restart.html.  
 
 The "fix_modify"_fix_modify.html {energy} option is supported by this
-fix to add the potential "energy" inferred by the added force to the
-system's potential energy as part of "thermodynamic
-output"_thermo_style.html.  This is a fictitious quantity but is
-needed so that the "minimize"_minimize.html command can include the
-forces added by this fix in a consistent manner.  I.e. there is a
-decrease in potential energy when atoms move in the direction of the
-added force.  The potential energy contribution of dipoles in the
-electric field is also included.
+fix to add the potential "energy" inferred by the added force due to
+the electric field to the system's potential energy as part of
+"thermodynamic output"_thermo_style.html.  This is a fictitious
+quantity but is needed so that the "minimize"_minimize.html command
+can include the forces added by this fix in a consistent manner.
+I.e. there is a decrease in potential energy when atoms move in the
+direction of the added force due to the electric field.
 
 This fix computes a global scalar and a global 3-vector of forces,
 which can be accessed by various "output
 commands"_Section_howto.html#howto_15.  The scalar is the potential
 energy discussed above.  The vector is the total force added to the
 group of atoms.  The scalar and vector values calculated by this fix
-are "extensive".  The added torques for point-dipoles cannot currently
-be output in this manner.
+are "extensive".
 
 No parameter of this fix can be used with the {start/stop} keywords of
 the "run"_run.html command.