From 20032cd0a7f72eafbcc05123f95d4ad9d0fe8fa1 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Fri, 13 Feb 2015 22:15:20 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@13113 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/Manual.html | 4 ++ doc/Manual.txt | 4 +- doc/Section_errors.html | 4 ++ doc/Section_errors.txt | 4 ++ doc/Section_howto.html | 103 +++++++++++++++++++++++++++++++++++++++- doc/Section_howto.txt | 103 +++++++++++++++++++++++++++++++++++++++- doc/kspace_modify.html | 22 ++++++--- doc/kspace_modify.txt | 19 ++++++-- doc/kspace_style.html | 10 ++-- doc/kspace_style.txt | 10 ++-- 10 files changed, 262 insertions(+), 21 deletions(-) diff --git a/doc/Manual.html b/doc/Manual.html index 35b57256a2..70cd7af176 100644 --- a/doc/Manual.html +++ b/doc/Manual.html @@ -200,6 +200,10 @@ it gives quick access to documentation for all LAMMPS commands. 6.21 Calculating viscosity
6.22 Calculating a diffusion coefficient +
+ 6.23 Using chunks to calculate system properties +
+ 6.24 Setting parameters for pppm/disp
  • Example problems diff --git a/doc/Manual.txt b/doc/Manual.txt index d9de5057bc..2292a80148 100644 --- a/doc/Manual.txt +++ b/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 diff --git a/doc/Section_errors.html b/doc/Section_errors.html index d30dfd35d2..f5976fba97 100644 --- a/doc/Section_errors.html +++ b/doc/Section_errors.html @@ -6759,6 +6759,10 @@ requested accuracy.
    This is a limitation of the PPPM implementation in LAMMPS. +
    PPPMDisp used but no parameters set, for further information please see the pppm/disp documentation + +
    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. +
    PRD command before simulation box is defined
    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