From ef70a452da2d906e719b503b0625305c47a08d87 Mon Sep 17 00:00:00 2001 From: pscrozi Date: Thu, 13 Sep 2012 19:50:50 +0000 Subject: [PATCH] Adding MSM documentation. git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@8778 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/kspace_modify.html | 45 +++++++++++++++++++++++------------------- doc/kspace_modify.txt | 45 +++++++++++++++++++++++------------------- doc/kspace_style.html | 43 ++++++++++++++++++++++++++++++++++++++-- doc/kspace_style.txt | 42 ++++++++++++++++++++++++++++++++++++--- 4 files changed, 130 insertions(+), 45 deletions(-) diff --git a/doc/kspace_modify.html b/doc/kspace_modify.html index b3e8d09a96..231f5f0c15 100644 --- a/doc/kspace_modify.html +++ b/doc/kspace_modify.html @@ -46,25 +46,28 @@ kspace_modify slab 3.0 kspace_style command. Not all parameters are relevant to all kspace styles.

-

The mesh keyword sets the 3d FFT grid size for kspace style pppm. -Each dimension must be factorizable into powers of 2, 3, and 5. When -this option is not set, the PPPM solver chooses its own grid size, -consistent with the user-specified accuracy and pairwise cutoff. -Values for x,y,z of 0,0,0 unset the option. +

The mesh keyword sets the grid size for kspace style pppm or msm. +In the case of PPPM, each dimension must be factorizable into powers +of 2, 3, and 5. In the case of MSM, each dimension must be +factorizable into powers of 2. When this option is not set, the PPPM +or MSM solver chooses its own grid size, consistent with the +user-specified accuracy and pairwise cutoff. Values for x,y,z of +0,0,0 unset the option.

The order keyword determines how many grid spacings an atom's charge -extends when it is mapped to the FFT grid in kspace style pppm. The -default for this parameter is 5, which means each charge spans 5 grid -cells in each dimension. The minimum allowed setting is 2 and the -maximum allowed setting is 7. The larger the value of this parameter, -the smaller the FFT grid will need to be to achieve the requested -precision. Conversely, the smaller the order value, the larger the -grid will be. Note that there is an inherent trade-off involved: a -small grid will lower the cost of FFTs, but a large order parameter -will increase the cost of intepolating charge/fields to/from the grid. -And vice versa. +extends when it is mapped to the grid in kspace style pppm or msm. +The default for this parameter is 5 for PPPM and 4 for MSM, which means +each charge spans 5 or 4 grid cells in each dimension, respectively. +For the LAMMPS implementation of MSM, 4 is the only allowable value. +For PPPM, the minimum allowed setting is 2 and the maximum allowed +setting is 7. The larger the value of this parameter, the smaller the +grid will need to be to achieve the requested precision. Conversely, +the smaller the order value, the larger the grid will be. Note that +there is an inherent trade-off involved: a small grid will lower the +cost of FFTs, but a large order parameter will increase the cost of +interpolating charge/fields to/from the grid. And vice versa.

-

The order parameter may be reset by LAMMPS when it sets up the PPPM +

The PPPM order parameter may be reset by LAMMPS when it sets up the FFT grid if the implied grid stencil extends beyond the grid cells owned by neighboring processors. Typically this will only occur when small problems are run on large numbers of processors. A warning will @@ -78,8 +81,8 @@ calculated by the long-range solver and is thus specified in force units. A negative value for the accuracy setting means to use the relative accuracy parameter. The accuracy setting is used in conjunction with the pairwise cutoff to determine the number of -K-space vectors for style ewald or the FFT grid size for style -pppm. +K-space vectors for style ewald, the FFT grid size for style +pppm, or the real space grid size for style msm.

The gewald keyword sets the value of the Ewald or PPPM G-ewald parameter as rinv in reciprocal distance units. Without this @@ -89,7 +92,8 @@ simulation to the next which may not be desirable for matching a KSpace solver to a pre-tabulated pairwise potential. This setting can also be useful if Ewald or PPPM fails to choose a good grid spacing and G-ewald parameter automatically. If the value is set to 0.0, -LAMMPS will choose the G-ewald parameter automatically. +LAMMPS will choose the G-ewald parameter automatically. MSM does not +use the gewald parameter.

The slab keyword allows an Ewald or PPPM solver to be used for a systems that are periodic in x,y but non-periodic in z - a @@ -105,7 +109,8 @@ must prevent particle migration beyond the initial z-bounds, typically by providing a wall-style fix. The methodology behind the slab option is explained in the paper by (Yeh). An alternative slab option can be invoked with the nozforce keyword in lieu of the -volfactor. This turns off all kspace forces in the z direction. +volfactor. This turns off all kspace forces in the z direction. The +slab and nozforce options are not allowed for MSM.

The compute keyword allows Kspace computations to be turned off, even though a kspace_style is defined. This is diff --git a/doc/kspace_modify.txt b/doc/kspace_modify.txt index 01b4e8f89d..95100bf5cf 100644 --- a/doc/kspace_modify.txt +++ b/doc/kspace_modify.txt @@ -40,25 +40,28 @@ Set parameters used by the kspace solvers defined by the "kspace_style"_kspace_style.html command. Not all parameters are relevant to all kspace styles. -The {mesh} keyword sets the 3d FFT grid size for kspace style pppm. -Each dimension must be factorizable into powers of 2, 3, and 5. When -this option is not set, the PPPM solver chooses its own grid size, -consistent with the user-specified accuracy and pairwise cutoff. -Values for x,y,z of 0,0,0 unset the option. +The {mesh} keyword sets the grid size for kspace style {pppm} or {msm}. +In the case of PPPM, each dimension must be factorizable into powers +of 2, 3, and 5. In the case of MSM, each dimension must be +factorizable into powers of 2. When this option is not set, the PPPM +or MSM solver chooses its own grid size, consistent with the +user-specified accuracy and pairwise cutoff. Values for x,y,z of +0,0,0 unset the option. The {order} keyword determines how many grid spacings an atom's charge -extends when it is mapped to the FFT grid in kspace style pppm. The -default for this parameter is 5, which means each charge spans 5 grid -cells in each dimension. The minimum allowed setting is 2 and the -maximum allowed setting is 7. The larger the value of this parameter, -the smaller the FFT grid will need to be to achieve the requested -precision. Conversely, the smaller the order value, the larger the -grid will be. Note that there is an inherent trade-off involved: a -small grid will lower the cost of FFTs, but a large order parameter -will increase the cost of intepolating charge/fields to/from the grid. -And vice versa. +extends when it is mapped to the grid in kspace style {pppm} or {msm}. +The default for this parameter is 5 for PPPM and 4 for MSM, which means +each charge spans 5 or 4 grid cells in each dimension, respectively. +For the LAMMPS implementation of MSM, 4 is the only allowable value. +For PPPM, the minimum allowed setting is 2 and the maximum allowed +setting is 7. The larger the value of this parameter, the smaller the +grid will need to be to achieve the requested precision. Conversely, +the smaller the order value, the larger the grid will be. Note that +there is an inherent trade-off involved: a small grid will lower the +cost of FFTs, but a large order parameter will increase the cost of +interpolating charge/fields to/from the grid. And vice versa. -The order parameter may be reset by LAMMPS when it sets up the PPPM +The PPPM order parameter may be reset by LAMMPS when it sets up the FFT grid if the implied grid stencil extends beyond the grid cells owned by neighboring processors. Typically this will only occur when small problems are run on large numbers of processors. A warning will @@ -72,8 +75,8 @@ calculated by the long-range solver and is thus specified in force units. A negative value for the accuracy setting means to use the relative accuracy parameter. The accuracy setting is used in conjunction with the pairwise cutoff to determine the number of -K-space vectors for style {ewald} or the FFT grid size for style -{pppm}. +K-space vectors for style {ewald}, the FFT grid size for style +{pppm}, or the real space grid size for style {msm}. The {gewald} keyword sets the value of the Ewald or PPPM G-ewald parameter as {rinv} in reciprocal distance units. Without this @@ -83,7 +86,8 @@ simulation to the next which may not be desirable for matching a KSpace solver to a pre-tabulated pairwise potential. This setting can also be useful if Ewald or PPPM fails to choose a good grid spacing and G-ewald parameter automatically. If the value is set to 0.0, -LAMMPS will choose the G-ewald parameter automatically. +LAMMPS will choose the G-ewald parameter automatically. MSM does not +use the {gewald} parameter. The {slab} keyword allows an Ewald or PPPM solver to be used for a systems that are periodic in x,y but non-periodic in z - a @@ -99,7 +103,8 @@ must prevent particle migration beyond the initial z-bounds, typically by providing a wall-style fix. The methodology behind the {slab} option is explained in the paper by "(Yeh)"_#Yeh. An alternative slab option can be invoked with the {nozforce} keyword in lieu of the -volfactor. This turns off all kspace forces in the z direction. +volfactor. This turns off all kspace forces in the z direction. The +{slab} and {nozforce} options are not allowed for MSM. The {compute} keyword allows Kspace computations to be turned off, even though a "kspace_style"_kspace_style.html is defined. This is diff --git a/doc/kspace_style.html b/doc/kspace_style.html index 5ccc5bd3c1..8930038d95 100644 --- a/doc/kspace_style.html +++ b/doc/kspace_style.html @@ -40,6 +40,8 @@ pppm/proxy value = accuracy accuracy = desired relative error in forces pppm/tip4p/proxy value = accuracy + accuracy = desired relative error in forces + msm value = accuracy accuracy = desired relative error in forces @@ -48,6 +50,7 @@ 

kspace_style pppm 1.0e-4
 kspace_style pppm/cg 1.0e-5 1.0e-6
+kspace style msm 1.0e-4
 kspace_style none

Description: @@ -119,6 +122,26 @@ section of the manual.

+

The msm style invokes a multi-level summation method MSM solver +(Hardy) which maps atom charge to a 3d mesh, and uses a +multi-level hierarchy of coarser and coarser meshes on which direct +coulomb solves are done. This method does not use FFTs and scales +as N. It may therefore be faster than the other K-space solvers for +relatively large problems when running on large core counts. +

+

MSM is most competitive versus Ewald and PPPM when only relatively +low accuracy forces, about 1% relative error or higher, are needed. +Note that MSM speed will be poor for large MSM meshes +(i.e. 64 x 64 x 64 or larger). Also note that use of a larger +coulomb cutoff (i.e. 15 angstroms instead of 10 angstroms) provides +better MSM accuracy for both the real space and grid computed forces. +Beware that the error estimation method for MSM is not very accurate, +so you should probably set your own mesh size and ensure that you are +getting adequate force accuracy by doing an energy conservation test +or comparison versus the Ewald method. +

+
+

When a kspace style is used, a pair style that includes the short-range correction to the pairwise Coulombic or other 1/r^N forces must also be selected. For Coulombic interactions, these styles are @@ -138,7 +161,7 @@ smaller than the reference force.

The accuracy setting is used in conjunction with the pairwise cutoff to determine the number of K-space vectors for style ewald or the -FFT grid size for style pppm. +FFT grid size for style pppm or msm.

RMS force errors in real space for ewald and pppm are estimated using equation 18 of (Kolafa), which is also referenced as @@ -146,7 +169,9 @@ equation 9 of (Petersen). RMS force errors in K-space ewald are estimated using equation 11 of (Petersen), which is similar to equation 32 of (Kolafa). RMS force errors in K-space for pppm are estimated using equation 38 of -(Deserno). +(Deserno). RMS force errors for msm are estimated +following the procedure outlined in chapter 3 of (Hardy), +with equation 3.197 of particular note.

See the kspace_modify command for additional options of the K-space solvers that can be set, including a force @@ -198,6 +223,14 @@ LAMMPS section for more info.

When using a long-range pairwise TIP4P potential, you must use kspace style pppm/tip4p and vice versa.

+

The msm style is fairly new, and still lacks some important features +and optimizations. In particular, the msm style does not include +long-range virial contributions to the pressure. It should not be used +for NPT simulations, and the reported total pressures should not be +trusted. Also the upper MSM levels (above the first level) are not +parallelized, so this MSM implementation may not yet scale very well +on large core counts. +

Related commands:

kspace_modify, pair_style @@ -240,4 +273,10 @@ Adam Hilger, NY (1989).

(Veld) In 't Veld, Ismail, Grest, J Chem Phys, in press (2007).

+ + +

(Hardy) David, Multilevel Summation for the Fast Evaluation of +Forces for the Simulation of Biomolecules, University of Illinois +at Urbana-Champaign, (2006). +

diff --git a/doc/kspace_style.txt b/doc/kspace_style.txt index c71e5ba2de..b4bd108909 100644 --- a/doc/kspace_style.txt +++ b/doc/kspace_style.txt @@ -36,6 +36,8 @@ style = {none} or {ewald} or {ewald/omp} or {ewald/n} or {pppm} or {pppm/cg} or {pppm/proxy} value = accuracy accuracy = desired relative error in forces {pppm/tip4p/proxy} value = accuracy + accuracy = desired relative error in forces + {msm} value = accuracy accuracy = desired relative error in forces :pre :ule @@ -43,6 +45,7 @@ style = {none} or {ewald} or {ewald/omp} or {ewald/n} or {pppm} or {pppm/cg} or kspace_style pppm 1.0e-4 kspace_style pppm/cg 1.0e-5 1.0e-6 +kspace style msm 1.0e-4 kspace_style none :pre [Description:] @@ -114,6 +117,26 @@ section"_Section_start.html#start_2_4 of the manual. :line +The {msm} style invokes a multi-level summation method MSM solver +"(Hardy)"_#Hardy which maps atom charge to a 3d mesh, and uses a +multi-level hierarchy of coarser and coarser meshes on which direct +coulomb solves are done. This method does not use FFTs and scales +as N. It may therefore be faster than the other K-space solvers for +relatively large problems when running on large core counts. + +MSM is most competitive versus Ewald and PPPM when only relatively +low accuracy forces, about 1% relative error or higher, are needed. +Note that MSM speed will be poor for large MSM meshes +(i.e. 64 x 64 x 64 or larger). Also note that use of a larger +coulomb cutoff (i.e. 15 angstroms instead of 10 angstroms) provides +better MSM accuracy for both the real space and grid computed forces. +Beware that the error estimation method for MSM is not very accurate, +so you should probably set your own mesh size and ensure that you are +getting adequate force accuracy by doing an energy conservation test +or comparison versus the Ewald method. + +:line + When a kspace style is used, a pair style that includes the short-range correction to the pairwise Coulombic or other 1/r^N forces must also be selected. For Coulombic interactions, these styles are @@ -133,7 +156,7 @@ smaller than the reference force. The accuracy setting is used in conjunction with the pairwise cutoff to determine the number of K-space vectors for style {ewald} or the -FFT grid size for style {pppm}. +FFT grid size for style {pppm} or {msm}. RMS force errors in real space for {ewald} and {pppm} are estimated using equation 18 of "(Kolafa)"_#Kolafa, which is also referenced as @@ -141,7 +164,9 @@ equation 9 of "(Petersen)"_#Petersen. RMS force errors in K-space for {ewald} are estimated using equation 11 of "(Petersen)"_#Petersen, which is similar to equation 32 of "(Kolafa)"_#Kolafa. RMS force errors in K-space for {pppm} are estimated using equation 38 of -"(Deserno)"_#Deserno. +"(Deserno)"_#Deserno. RMS force errors for {msm} are estimated +following the procedure outlined in chapter 3 of "(Hardy)"_#Hardy, +with equation 3.197 of particular note. See the "kspace_modify"_kspace_modify.html command for additional options of the K-space solvers that can be set, including a {force} @@ -193,6 +218,14 @@ LAMMPS"_Section_start.html#start_3 section for more info. When using a long-range pairwise TIP4P potential, you must use kspace style {pppm/tip4p} and vice versa. +The {msm} style is fairly new, and still lacks some important features +and optimizations. In particular, the {msm} style does not include +long-range virial contributions to the pressure. It should not be used +for NPT simulations, and the reported total pressures should not be +trusted. Also the upper MSM levels (above the first level) are not +parallelized, so this MSM implementation may not yet scale very well +on large core counts. + [Related commands:] "kspace_modify"_kspace_modify.html, "pair_style @@ -228,4 +261,7 @@ Adam Hilger, NY (1989). :link(Veld) [(Veld)] In 't Veld, Ismail, Grest, J Chem Phys, in press (2007). - +:link(Hardy) +[(Hardy)] David, Multilevel Summation for the Fast Evaluation of +Forces for the Simulation of Biomolecules, University of Illinois +at Urbana-Champaign, (2006).