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

doc/Manual.html

@@ -200,6 +200,10 @@ it gives quick access to documentation for all LAMMPS commands.
   6.21 <A HREF = "Section_howto.html#howto_21">Calculating viscosity</A> 
 <BR>
   6.22 <A HREF = "howto_22">Calculating a diffusion coefficient</A> 
+<BR>
+  6.23 <A HREF = "howto_23">Using chunks to calculate system properties</A> 
+<BR>
+  6.24 <A HREF = "howto_24">Setting parameters for pppm/disp</A> 
 <BR></UL>
 <LI><A HREF = "Section_example.html">Example problems</A> 
 

doc/Manual.txt

@@ -136,7 +136,9 @@ it gives quick access to documentation for all LAMMPS commands.
   6.19 "Library interface to LAMMPS"_howto_19 :b
   6.20 "Calculating thermal conductivity"_howto_20 :b
   6.21 "Calculating viscosity"_howto_21 :b
-  6.22 "Calculating a diffusion coefficient"_howto_22 :ule,b
+  6.22 "Calculating a diffusion coefficient"_howto_22 :b
+  6.23 "Using chunks to calculate system properties"_howto_23 :b
+  6.24 "Setting parameters for pppm/disp"_howto_24 :ule,b
 "Example problems"_Section_example.html :l
 "Performance & scalability"_Section_perf.html :l
 "Additional tools"_Section_tools.html :l

doc/Section_errors.html

@@ -6759,6 +6759,10 @@ requested accuracy.
 
 <DD>This is a limitation of the PPPM implementation in LAMMPS. 
 
+<DT><I>PPPMDisp used but no parameters set, for further information please see the pppm/disp documentation</I> 
+
+<DD>An efficient and accurate usage of the pppm/disp requires settings via the kspace_modify command. Please see the pppm/disp documentation for further instructions. 
+
 <DT><I>PRD command before simulation box is defined</I> 
 
 <DD>The prd command cannot be used before a read_data,

doc/Section_errors.txt

@@ -6755,6 +6755,10 @@ requested accuracy. :dd
 
 This is a limitation of the PPPM implementation in LAMMPS. :dd
 
+{PPPMDisp used but no parameters set, for further information please see the pppm/disp documentation} :dt
+
+An efficient and accurate usage of the pppm/disp requires settings via the kspace_modify command. Please see the pppm/disp documentation for further instructions. :dd
+
 {PRD command before simulation box is defined} :dt
 
 The prd command cannot be used before a read_data,

doc/Section_howto.html

@@ -36,6 +36,7 @@
 6.21 <A HREF = "#howto_21">Calculating viscosity</A><BR>
 6.22 <A HREF = "#howto_22">Calculating a diffusion coefficient</A><BR>
 6.23 <A HREF = "#howto_23">Using chunks to calculate system properties</A><BR>
+6.24 <A HREF = "#howto_24">Setting parameters for the pppm/disp</A> <BR>
 
 <P>The example input scripts included in the LAMMPS distribution and
 highlighted in <A HREF = "Section_example.html">Section_example</A> also show how to
@@ -2315,6 +2316,106 @@ fix 1 all ave/histo 100 1 100 0 20 20 c_size mode vector ave running beyond igno
 </PRE>
 <HR>
 
+<A NAME = "howto_24"></A><H4>6.24 Setting parameters for pppm/disp 
+</H4>
+<P>The PPPM method computes interactions by splitting the pair potential
+into two parts, one of which is computed in a normal pairwise fashion,
+the so-called real-space part, and one of which is computed using the
+Fourier transform, the so called reciprocal-space or kspace part.
+For both parts, the potential is not computed exactly but is approximated.
+Thus, there is an error in both parts of the computation, the real-space
+and the kspace error. The just mentioned facts are true both for the
+PPPM for Coulomb as well as dispersion interactions. The deciding
+difference - and also the reason why the parameters for pppm/disp
+have to be selected with more care - is the impact of the errors on
+the results: The kspace error of the PPPM for Coulomb and dispersion
+interaction and the real-space error of the PPPM for Coulomb interaction
+have the character of noise. In contrast, the real-space error of the
+PPPM for dispersion has a clear physical interpretation: the underprediction
+of cohesion. As a consequence, the real-space error has a much stronger
+effect than the kspace error on simulation results for pppm/disp.
+Parameters must thus be chosen in a way that this error is much smaller
+than the kspace error.
+</P>
+<P>When using pppm/disp and not making any specifications on the
+PPPM parameters via the kspace modify command, parameters will be
+tuned such that the real-space error and the kspace error are equal.
+This will result in simulations that are either inaccurate or slow,
+both of which is not desirable. For selecting parameters for the
+pppm/disp that provide fast and accurate simulations, there are two
+approaches, which both have their up- and downsides.
+</P>
+<P>The first approach is to set desired real-space an kspace accuracies
+via the <I>kspace_modify force/disp/real</I> and
+<I>kspace_modify force/disp/kspace</I> commands. Note that the accuracies
+have to be specified in force units and are thus dependend on the chosen
+unit settings. For real units, 0.0001 and 0.002 seem to provide reasonable
+accurate and efficient computations for the real-space and kspace accuracies.
+0.002 and 0.05 work well for most systems using lj units. PPPM parameters will
+be generated based on the desired accuracies. The upside of
+this approach is that it usually provides
+a good set of parameters and will work for both the <I>kspace_modify diff ad</I>
+and <I>kspace_modify diff ik</I> options.
+The downside of the method is that setting
+the PPPM parameters will take some time during the initialization of
+the simulation.
+</P>
+<P>The second approach is to set the parameters for the pppm/disp explicitly
+using the <I>kspace_modify mesh/disp</I>, <I>kspace_modify order/disp</I>,
+and <I>kspace_modify gewald/disp</I> commands. This approach requires a
+more experienced user who understands well the impact of the choice of parameters
+on the simulation accuracy and performance. This approach provides a
+fast initialization of the simulation. However, it is sensitive to errors:
+A combination of parameters that will perform well for one system might result
+in far-from-optimal conditions for other simulations. For example, parametes
+that provide accurate and fast computations for all-atomistic force fields
+can provide insufficient accuracy or united-atomistic force fields (which is
+related to that the latter typically have larger dispersion coefficients).
+</P>
+<P>To avoid inaccurate or inefficient simulations, the pppm/disp stops
+simulations with an error message if no action is taken to control the
+PPPM parameters. If the automatic parameter generation is desired and
+real-space and kspace accuracies are desired to be equal, this error
+message can be suppressed using the <I>kspace_modify disp/auto yes</I>
+command.
+</P>
+<P>A reasonable approach that combines the upsides of both methods
+is to make the first run using the <I>kspace_modify force/disp/real</I>
+and <I>kspace_modify force/disp/kspace</I> commands, write down the PPPM parameters
+from the outut, and specify these parameters using the second approach
+in subsequent runs (which have the same composition, force field, and
+approximately the same volume).
+</P>
+<P>Concerning the performance of the pppm/disp there are two more
+things to consider. The first is that when using the pppm/disp, the
+cutoff parameter does no longer affect the accuracy of the simulation
+(subject to that gewald/disp is adjusted when changing the cutoff).
+The performance can thus be increased by examining different values
+for the cutoff parameter. A lower bound for the cutoff is only set
+by the truncation error of the repulsive term of pair potentials.
+</P>
+<P>The second is that the mixing rule of the pair style has an impact on
+the computation time when using the pppm/disp. Fastest computations are
+achieved when using the geometric mixing rule. Using the arithmetic
+mixing rule substantially increases the computational cost.
+The computational overhead can be reduced using the
+<I>kspace_modify mix/disp geom</I> and <I>kspace_modify splittol</I>
+commands. The first command simply enforces geometric mixing of the
+dispersion coeffiecients in kspace computations.
+This introduces some error in the computations but will also significantly
+speed-up the simulations. The second keyword sets the accuracy with
+which the dispersion coefficients are approximated using a matrix factorization approach.
+This may result in better accuracy then using the first command, but will
+usually also not provide an equally good increase of efficiency.
+</P>
+<P>Finally, pppm/disp can also be used when no mixing rules apply.
+This can be achieved using the <I>kspace_modify mix/disp none</I> command.
+Note that the code does not check automatically whether any mixing
+rule is fulfilled. If mixing rules do not apply, the user will have
+to specify this command explicitly.
+</P>
+<HR>
+
 <HR>
 
 <A NAME = "Berendsen"></A>

doc/Section_howto.txt

@@ -32,7 +32,8 @@ This section describes how to perform common tasks using LAMMPS.
 6.20 "Calculating thermal conductivity"_#howto_20
 6.21 "Calculating viscosity"_#howto_21
 6.22 "Calculating a diffusion coefficient"_#howto_22
-6.23 "Using chunks to calculate system properties"_#howto_23 :all(b)
+6.23 "Using chunks to calculate system properties"_#howto_23
+6.24 "Setting parameters for the pppm/disp"_#howto_24 :all(b)
 
 The example input scripts included in the LAMMPS distribution and
 highlighted in "Section_example"_Section_example.html also show how to
@@ -2298,6 +2299,106 @@ compute cc1 all chunk/atom c_cluster compress yes
 compute size all property/chunk cc1 count
 fix 1 all ave/histo 100 1 100 0 20 20 c_size mode vector ave running beyond ignore file tmp.histo :pre
 
+:line
+
+6.24 Setting parameters for pppm/disp :link(howto_24),h4
+
+The PPPM method computes interactions by splitting the pair potential
+into two parts, one of which is computed in a normal pairwise fashion,
+the so-called real-space part, and one of which is computed using the
+Fourier transform, the so called reciprocal-space or kspace part.
+For both parts, the potential is not computed exactly but is approximated.
+Thus, there is an error in both parts of the computation, the real-space
+and the kspace error. The just mentioned facts are true both for the
+PPPM for Coulomb as well as dispersion interactions. The deciding
+difference - and also the reason why the parameters for pppm/disp
+have to be selected with more care - is the impact of the errors on
+the results: The kspace error of the PPPM for Coulomb and dispersion
+interaction and the real-space error of the PPPM for Coulomb interaction
+have the character of noise. In contrast, the real-space error of the
+PPPM for dispersion has a clear physical interpretation: the underprediction
+of cohesion. As a consequence, the real-space error has a much stronger
+effect than the kspace error on simulation results for pppm/disp.
+Parameters must thus be chosen in a way that this error is much smaller
+than the kspace error.
+
+When using pppm/disp and not making any specifications on the
+PPPM parameters via the kspace modify command, parameters will be
+tuned such that the real-space error and the kspace error are equal.
+This will result in simulations that are either inaccurate or slow,
+both of which is not desirable. For selecting parameters for the
+pppm/disp that provide fast and accurate simulations, there are two
+approaches, which both have their up- and downsides.
+
+The first approach is to set desired real-space an kspace accuracies
+via the {kspace_modify force/disp/real} and
+{kspace_modify force/disp/kspace} commands. Note that the accuracies
+have to be specified in force units and are thus dependend on the chosen
+unit settings. For real units, 0.0001 and 0.002 seem to provide reasonable
+accurate and efficient computations for the real-space and kspace accuracies.
+0.002 and 0.05 work well for most systems using lj units. PPPM parameters will
+be generated based on the desired accuracies. The upside of
+this approach is that it usually provides
+a good set of parameters and will work for both the {kspace_modify diff ad}
+and {kspace_modify diff ik} options.
+The downside of the method is that setting
+the PPPM parameters will take some time during the initialization of
+the simulation.
+
+The second approach is to set the parameters for the pppm/disp explicitly
+using the {kspace_modify mesh/disp}, {kspace_modify order/disp},
+and {kspace_modify gewald/disp} commands. This approach requires a
+more experienced user who understands well the impact of the choice of parameters
+on the simulation accuracy and performance. This approach provides a
+fast initialization of the simulation. However, it is sensitive to errors:
+A combination of parameters that will perform well for one system might result
+in far-from-optimal conditions for other simulations. For example, parametes
+that provide accurate and fast computations for all-atomistic force fields
+can provide insufficient accuracy or united-atomistic force fields (which is
+related to that the latter typically have larger dispersion coefficients).
+
+To avoid inaccurate or inefficient simulations, the pppm/disp stops
+simulations with an error message if no action is taken to control the
+PPPM parameters. If the automatic parameter generation is desired and
+real-space and kspace accuracies are desired to be equal, this error
+message can be suppressed using the {kspace_modify disp/auto yes}
+command.
+
+A reasonable approach that combines the upsides of both methods
+is to make the first run using the {kspace_modify force/disp/real}
+and {kspace_modify force/disp/kspace} commands, write down the PPPM parameters
+from the outut, and specify these parameters using the second approach
+in subsequent runs (which have the same composition, force field, and
+approximately the same volume).
+
+Concerning the performance of the pppm/disp there are two more
+things to consider. The first is that when using the pppm/disp, the
+cutoff parameter does no longer affect the accuracy of the simulation
+(subject to that gewald/disp is adjusted when changing the cutoff).
+The performance can thus be increased by examining different values
+for the cutoff parameter. A lower bound for the cutoff is only set
+by the truncation error of the repulsive term of pair potentials.
+
+The second is that the mixing rule of the pair style has an impact on
+the computation time when using the pppm/disp. Fastest computations are
+achieved when using the geometric mixing rule. Using the arithmetic
+mixing rule substantially increases the computational cost.
+The computational overhead can be reduced using the
+{kspace_modify mix/disp geom} and {kspace_modify splittol}
+commands. The first command simply enforces geometric mixing of the
+dispersion coeffiecients in kspace computations.
+This introduces some error in the computations but will also significantly
+speed-up the simulations. The second keyword sets the accuracy with
+which the dispersion coefficients are approximated using a matrix factorization approach.
+This may result in better accuracy then using the first command, but will
+usually also not provide an equally good increase of efficiency.
+
+Finally, pppm/disp can also be used when no mixing rules apply.
+This can be achieved using the {kspace_modify mix/disp none} command.
+Note that the code does not check automatically whether any mixing
+rule is fulfilled. If mixing rules do not apply, the user will have
+to specify this command explicitly.
+
 :line
 :line
 

doc/kspace_modify.html

@@ -17,9 +17,8 @@
 </PRE>
 <UL><LI>one or more keyword/value pairs may be listed 
 
-<LI>keyword = <I>mesh</I> or <I>order</I> or <I>order/disp</I> or <I>mix/disp</I> or <I>overlap</I> or <I>minorder</I> or <I>force</I> or <I>gewald</I> or <I>gewald/disp</I> or <I>slab</I> or (nozforce</I> or <I>compute</I> or <I>cutoff/adjust</I> or <I>fftbench</I> or <I>collective</I> or <I>diff</I> or <I>kmax/ewald</I> or <I>force/disp/real</I> or <I>force/disp/kspace</I> or <I>splittol</I> 
+<PRE>keyword = <I>mesh</I> or <I>order</I> or <I>order/disp</I> or <I>mix/disp</I> or <I>overlap</I> or <I>minorder</I> or <I>force</I> or <I>gewald</I> or <I>gewald/disp</I> or <I>slab</I> or (nozforce</I> or <I>compute</I> or <I>cutoff/adjust</I> or <I>fftbench</I> or <I>collective</I> or <I>diff</I> or <I>kmax/ewald</I> or <I>force/disp/real</I> or <I>force/disp/kspace</I> or <I>splittol</I> or <I>disp/auto</I>:l
-
+  <I>mesh</I> value = x y z
-<PRE>  <I>mesh</I> value = x y z
     x,y,z = grid size in each dimension for long-range Coulombics
   <I>mesh/disp</I> value = x y z
     x,y,z = grid size in each dimension for 1/r^6 dispersion
@@ -52,6 +51,7 @@
   <I>force/disp/kspace</I> value = accuracy (force units)
   <I>splittol</I> value = tol
     tol = relative size of two eigenvalues (see discussion below)
+  <I>disp/auto</I> value = yes or no 
 </PRE>
 
 </UL>
@@ -278,10 +278,20 @@ computations of the dispersion part is decreased.
 </P>
 <P>The <I>force/disp/real</I> and <I>force/disp/kspace</I> keywords set the force
 accuracy for the real and space computations for the dispersion part
-of pppm/disp.  as shown in <A HREF = "#Isele-Holder">(Isele-Holder)</A>, optimal
+of pppm/disp. As shown in <A HREF = "#Isele-Holder">(Isele-Holder)</A>, optimal
 performance and accuracy in the results is obtained when these values
 are different.
 </P>
+<P>The <I>disp/auto</I> option controlls whether the pppm/disp is allowed to
+generate PPPM parameters automatically. If set to <I>no</I>, parameters have
+to be specified using the <I>gewald/disp</I>, <I>mesh/disp</I>,
+<I>force/disp/real</I> or <I>force/disp/kspace</I> keywords, or
+the code will stop with an error message. When this option is set to
+<I>yes</I>, the error message will not appear and the simulation will start.
+For a typical application, using the automatic parameter generation will provide
+simulations that are either inaccurate or slow. Using this option is thus not
+recommended. For guidelines on how to obtain good parameters, see the <A HREF = "Section_howto.html#howto_23">How-To</A> discussion.
+</P>
 <P><B>Restrictions:</B> none
 </P>
 <P><B>Related commands:</B>
@@ -295,7 +305,7 @@ are different.
 gewald = gewald/disp = 0.0, slab = 1.0, compute = yes, cutoff/adjust =
 yes (MSM), pressure/scalar = yes (MSM), fftbench = yes (PPPM), diff = ik
 (PPPM), mix/disp = pair, force/disp/real = -1.0, force/disp/kspace = -1.0,
-split = 0, and tol = 1.0e-6.
+split = 0, tol = 1.0e-6, and disp/auto = no.
 </P>
 <HR>
 

doc/kspace_modify.txt

@@ -13,7 +13,7 @@ kspace_modify command :h3
 kspace_modify keyword value ... :pre
 
 one or more keyword/value pairs may be listed :ulb,l
-keyword = {mesh} or {order} or {order/disp} or {mix/disp} or {overlap} or {minorder} or {force} or {gewald} or {gewald/disp} or {slab} or (nozforce} or {compute} or {cutoff/adjust} or {fftbench} or {collective} or {diff} or {kmax/ewald} or {force/disp/real} or {force/disp/kspace} or {splittol} :l
+keyword = {mesh} or {order} or {order/disp} or {mix/disp} or {overlap} or {minorder} or {force} or {gewald} or {gewald/disp} or {slab} or (nozforce} or {compute} or {cutoff/adjust} or {fftbench} or {collective} or {diff} or {kmax/ewald} or {force/disp/real} or {force/disp/kspace} or {splittol} or {disp/auto}:l
   {mesh} value = x y z
     x,y,z = grid size in each dimension for long-range Coulombics
   {mesh/disp} value = x y z
@@ -46,7 +46,8 @@ keyword = {mesh} or {order} or {order/disp} or {mix/disp} or {overlap} or {minor
   {force/disp/real} value = accuracy (force units)
   {force/disp/kspace} value = accuracy (force units)
   {splittol} value = tol
-    tol = relative size of two eigenvalues (see discussion below) :pre
+    tol = relative size of two eigenvalues (see discussion below)
+  {disp/auto} value = yes or no :pre
 :ule
 
 [Examples:]
@@ -272,10 +273,20 @@ computations of the dispersion part is decreased.
 
 The {force/disp/real} and {force/disp/kspace} keywords set the force
 accuracy for the real and space computations for the dispersion part
-of pppm/disp.  as shown in "(Isele-Holder)"_#Isele-Holder, optimal
+of pppm/disp. As shown in "(Isele-Holder)"_#Isele-Holder, optimal
 performance and accuracy in the results is obtained when these values
 are different.
 
+The {disp/auto} option controlls whether the pppm/disp is allowed to
+generate PPPM parameters automatically. If set to {no}, parameters have
+to be specified using the {gewald/disp}, {mesh/disp},
+{force/disp/real} or {force/disp/kspace} keywords, or
+the code will stop with an error message. When this option is set to
+{yes}, the error message will not appear and the simulation will start.
+For a typical application, using the automatic parameter generation will provide
+simulations that are either inaccurate or slow. Using this option is thus not
+recommended. For guidelines on how to obtain good parameters, see the "How-To"_Section_howto.html#howto_23 discussion.
+
 [Restrictions:] none
 
 [Related commands:]
@@ -289,7 +300,7 @@ The option defaults are mesh = mesh/disp = 0 0 0, order = order/disp =
 gewald = gewald/disp = 0.0, slab = 1.0, compute = yes, cutoff/adjust =
 yes (MSM), pressure/scalar = yes (MSM), fftbench = yes (PPPM), diff = ik
 (PPPM), mix/disp = pair, force/disp/real = -1.0, force/disp/kspace = -1.0,
-split = 0, and tol = 1.0e-6.
+split = 0, tol = 1.0e-6, and disp/auto = no.
 
 :line
 

doc/kspace_style.html

@@ -162,13 +162,15 @@ similar to the <I>ewald/disp</I> style. The 1/r^6 capability means
 that Lennard-Jones or Buckingham potentials can be used without a cutoff,
 i.e. they become full long-range potentials.
 </P>
-<P>For these styles, you may want to adjust the default choice of
+<P>For these styles, you will possibly want to adjust the default choice of
 parameters by using the <A HREF = "kspace_modify.html">kspace_modify</A> command.
 This can be done by either choosing the Ewald and grid parameters, or
 by specifying separate accuracies for the real and kspace
-calculations.  Further information on the influence of the parameters
+calculations. When not making any settings, the simulation will stop with
-and how to choose them is described in <A HREF = "#Isele-Holder">(Isele-Holder)</A>
+an error message. Further information on the influence of the parameters
-and <A HREF = "#Isele-Holder2">(Isele-Holder2)</A>.
+and how to choose them is described in <A HREF = "#Isele-Holder">(Isele-Holder)</A>,
+<A HREF = "#Isele-Holder2">(Isele-Holder2)</A> and the
+<A HREF = "Section_howto.html#howto_24">How-To</A> discussion.
 </P>
 <HR>
 

doc/kspace_style.txt

@@ -155,13 +155,15 @@ similar to the {ewald/disp} style. The 1/r^6 capability means
 that Lennard-Jones or Buckingham potentials can be used without a cutoff,
 i.e. they become full long-range potentials.
 
-For these styles, you may want to adjust the default choice of
+For these styles, you will possibly want to adjust the default choice of
 parameters by using the "kspace_modify"_kspace_modify.html command.
 This can be done by either choosing the Ewald and grid parameters, or
 by specifying separate accuracies for the real and kspace
-calculations.  Further information on the influence of the parameters
+calculations. When not making any settings, the simulation will stop with
-and how to choose them is described in "(Isele-Holder)"_#Isele-Holder
+an error message. Further information on the influence of the parameters
-and "(Isele-Holder2)"_#Isele-Holder2.
+and how to choose them is described in "(Isele-Holder)"_#Isele-Holder,
+"(Isele-Holder2)"_#Isele-Holder2 and the
+"How-To"_Section_howto.html#howto_24 discussion.
 
 :line