Adding MSM documentation.

git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@8778 f3b2605a-c512-4ea7-a41b-209d697bcdaa
This commit is contained in:
pscrozi 2012-09-13 19:50:50 +00:00
parent 01f20e806b
commit ef70a452da
4 changed files with 130 additions and 45 deletions

View File

@ -46,25 +46,28 @@ kspace_modify slab 3.0
<A HREF = "kspace_style.html">kspace_style</A> command. Not all parameters are
relevant to all kspace styles.
</P>
<P>The <I>mesh</I> 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.
<P>The <I>mesh</I> keyword sets the grid size for kspace style <I>pppm</I> or <I>msm</I>.
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.
</P>
<P>The <I>order</I> 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 <I>pppm</I> or <I>msm</I>.
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.
</P>
<P>The order parameter may be reset by LAMMPS when it sets up the PPPM
<P>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 <I>ewald</I> or the FFT grid size for style
<I>pppm</I>.
K-space vectors for style <I>ewald</I>, the FFT grid size for style
<I>pppm</I>, or the real space grid size for style <I>msm</I>.
</P>
<P>The <I>gewald</I> keyword sets the value of the Ewald or PPPM G-ewald
parameter as <I>rinv</I> 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 <I>gewald</I> parameter.
</P>
<P>The <I>slab</I> 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 <I>slab</I>
option is explained in the paper by <A HREF = "#Yeh">(Yeh)</A>. An alternative
slab option can be invoked with the <I>nozforce</I> 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
<I>slab</I> and <I>nozforce</I> options are not allowed for MSM.
</P>
<P>The <I>compute</I> keyword allows Kspace computations to be turned off,
even though a <A HREF = "kspace_style.html">kspace_style</A> is defined. This is

View File

@ -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

View File

@ -40,6 +40,8 @@
<I>pppm/proxy</I> value = accuracy
accuracy = desired relative error in forces
<I>pppm/tip4p/proxy</I> value = accuracy
accuracy = desired relative error in forces
<I>msm</I> value = accuracy
accuracy = desired relative error in forces
</PRE>
@ -48,6 +50,7 @@
</P>
<PRE>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>
<P><B>Description:</B>
@ -119,6 +122,26 @@ section</A> of the manual.
</P>
<HR>
<P>The <I>msm</I> style invokes a multi-level summation method MSM solver
<A HREF = "#Hardy">(Hardy)</A> 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.
</P>
<P>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.
</P>
<HR>
<P>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.
</P>
<P>The accuracy setting is used in conjunction with the pairwise cutoff
to determine the number of K-space vectors for style <I>ewald</I> or the
FFT grid size for style <I>pppm</I>.
FFT grid size for style <I>pppm</I> or <I>msm</I>.
</P>
<P>RMS force errors in real space for <I>ewald</I> and <I>pppm</I> are estimated
using equation 18 of <A HREF = "#Kolafa">(Kolafa)</A>, which is also referenced as
@ -146,7 +169,9 @@ equation 9 of <A HREF = "#Petersen">(Petersen)</A>. RMS force errors in K-space
<I>ewald</I> are estimated using equation 11 of <A HREF = "#Petersen">(Petersen)</A>,
which is similar to equation 32 of <A HREF = "#Kolafa">(Kolafa)</A>. RMS force
errors in K-space for <I>pppm</I> are estimated using equation 38 of
<A HREF = "#Deserno">(Deserno)</A>.
<A HREF = "#Deserno">(Deserno)</A>. RMS force errors for <I>msm</I> are estimated
following the procedure outlined in chapter 3 of <A HREF = "#Hardy">(Hardy)</A>,
with equation 3.197 of particular note.
</P>
<P>See the <A HREF = "kspace_modify.html">kspace_modify</A> command for additional
options of the K-space solvers that can be set, including a <I>force</I>
@ -198,6 +223,14 @@ LAMMPS</A> section for more info.
<P>When using a long-range pairwise TIP4P potential, you must use kspace
style <I>pppm/tip4p</I> and vice versa.
</P>
<P>The <I>msm</I> style is fairly new, and still lacks some important features
and optimizations. In particular, the <I>msm</I> 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.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "kspace_modify.html">kspace_modify</A>, <A HREF = "pair_lj.html">pair_style
@ -240,4 +273,10 @@ Adam Hilger, NY (1989).
<P><B>(Veld)</B> In 't Veld, Ismail, Grest, J Chem Phys, in press (2007).
</P>
<A NAME = "Hardy"></A>
<P><B>(Hardy)</B> David, Multilevel Summation for the Fast Evaluation of
Forces for the Simulation of Biomolecules, University of Illinois
at Urbana-Champaign, (2006).
</P>
</HTML>

View File

@ -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).