The prd command cannot be used before a read_data,
diff --git a/doc/Section_errors.txt b/doc/Section_errors.txt
index 91878bc777..c75538e530 100644
--- a/doc/Section_errors.txt
+++ b/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,
diff --git a/doc/Section_howto.html b/doc/Section_howto.html
index 4487f0113c..0ffb3e6fc7 100644
--- a/doc/Section_howto.html
+++ b/doc/Section_howto.html
@@ -35,7 +35,8 @@
6.20 Calculating thermal conductivity
6.21 Calculating viscosity
6.22 Calculating a diffusion coefficient
-6.23 Using chunks to calculate system properties
+6.23 Using chunks to calculate system properties
+6.24 Setting parameters for the pppm/disp
The example input scripts included in the LAMMPS distribution and
highlighted in Section_example 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
+6.24 Setting parameters for pppm/disp
+
+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.
+
+
+
diff --git a/doc/Section_howto.txt b/doc/Section_howto.txt
index 3fcec12fa5..54f7b436ee 100644
--- a/doc/Section_howto.txt
+++ b/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
diff --git a/doc/kspace_modify.html b/doc/kspace_modify.html
index 2660473532..25693a130d 100644
--- a/doc/kspace_modify.html
+++ b/doc/kspace_modify.html
@@ -17,9 +17,8 @@
- one or more keyword/value pairs may be listed
-
- 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
-
-
mesh value = x y z
+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
x,y,z = grid size in each dimension for 1/r^6 dispersion
@@ -51,7 +50,8 @@
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)
+ tol = relative size of two eigenvalues (see discussion below)
+ disp/auto value = yes or no
@@ -278,10 +278,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), optimal
+of pppm/disp. As shown in (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 discussion.
+
Restrictions: none
Related commands:
@@ -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.
diff --git a/doc/kspace_modify.txt b/doc/kspace_modify.txt
index 56c9bf4088..a6d336d94d 100644
--- a/doc/kspace_modify.txt
+++ b/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
diff --git a/doc/kspace_style.html b/doc/kspace_style.html
index 9e19bb697c..36b55dc1da 100644
--- a/doc/kspace_style.html
+++ b/doc/kspace_style.html
@@ -162,13 +162,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 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
-and how to choose them is described in (Isele-Holder)
-and (Isele-Holder2).
+calculations. When not making any settings, the simulation will stop with
+an error message. Further information on the influence of the parameters
+and how to choose them is described in (Isele-Holder),
+(Isele-Holder2) and the
+How-To discussion.
diff --git a/doc/kspace_style.txt b/doc/kspace_style.txt
index 9f7d482b88..821afcc5fc 100644
--- a/doc/kspace_style.txt
+++ b/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
-and how to choose them is described in "(Isele-Holder)"_#Isele-Holder
-and "(Isele-Holder2)"_#Isele-Holder2.
+calculations. When not making any settings, the simulation will stop with
+an error message. Further information on the influence of the parameters
+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