From 8431b8f71174dc802f88b7687576976f4dfb79f2 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Wed, 29 Jan 2014 00:37:26 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@11366 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/kspace_modify.html | 318 +++++++++++++++++++++ doc/kspace_modify.txt | 608 ++++++++++++++++++++--------------------- 2 files changed, 622 insertions(+), 304 deletions(-) diff --git a/doc/kspace_modify.html b/doc/kspace_modify.html index 0e7dd90187..dde788c36b 100644 --- a/doc/kspace_modify.html +++ b/doc/kspace_modify.html @@ -1 +1,319 @@ +
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands +
+ + + + + + +
+ +

kspace_modify command +

+

Syntax: +

+
kspace_modify keyword value ... 
+
+ +

Examples: +

+
kspace_modify mesh 24 24 30 order 6
+kspace_modify slab 3.0 
+
+

Description: +

+

Set parameters used by the kspace solvers defined by the +kspace_style command. Not all parameters are +relevant to all kspace styles. +

+

The mesh keyword sets the grid size for kspace style pppm or +msm. In the case of PPPM, this is the FFT mesh, and each dimension +must be factorizable into powers of 2, 3, and 5. In the case of MSM, +this is the finest scale real-space mesh, and 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 mesh/disp keyword sets the grid size for kspace style +pppm/disp. This is the FFT mesh for long-range dispersion and ach +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 order keyword determines how many grid spacings an atom's charge +extends when it is mapped to the grid in kspace style pppm or msm. +The default for this parameter is 5 for PPPM and 8 for MSM, which +means each charge spans 5 or 8 grid cells in each dimension, +respectively. For the LAMMPS implementation of MSM, the order can +range from 4 to 10 and must be even. For PPPM, the minimum allowed +setting is 2 and the maximum allowed setting is 7. The larger the +value of this parameter, the smaller that LAMMPS will set the grid +size, to achieve the requested accuracy. Conversely, the smaller the +order value, the larger the grid size will be. Note that there is an +inherent trade-off involved: a small grid will lower the cost of FFTs +or MSM direct sum, but a larger order parameter will increase the cost +of interpolating charge/fields to/from the grid. +

+

The order/disp keyword determines how many grid spacings an atom's +dispersion term extends when it is mapped to the grid in kspace style +pppm/disp. It has the same meaning as the order setting for +Coulombics. +

+

The overlap keyword can be used in conjunction with the minorder +keyword with the PPPM styles to adjust the amount of communication +that occurs when values on the FFT grid are exchangeed between +processors. This communication is distinct from the communication +inherent in the parallel FFTs themselves, and is required because +processors interpolate charge and field values using grid point values +owned by neighboring processors (i.e. ghost point communication). If +the overlap keyword is set to yes then this communication is +allowed to extend beyond nearest-neighbor processors, e.g. when using +lots of processors on a small problem. If it is set to no then the +communication will be limited to nearest-neighbor processors and the +order setting will be reduced if necessary, as explained by the +minorder keyword discussion. The overlap keyword is always set to +yes in MSM. +

+

The minorder keyword allows LAMMPS to reduce the order setting if +necessary to keep the communication of ghost grid point limited to +exchanges between nearest-neighbor processors. See the discussion of +the overlap keyword for details. If the overlap keyword is set to +yes, which is the default, this is never needed. If it set to no +and overlap occurs, then LAMMPS will reduce the order setting, one +step at a time, until the ghost grid overlap only extends to nearest +neighbor processors. The minorder keyword limits how small the +order setting can become. The minimum allowed value for PPPM is 2, +which is the default. If minorder is set to the same value as +order then no reduction is allowed, and LAMMPS will generate an +error if the grid communcation is non-nearest-neighbor and overlap +is set to no. The minorder keyword is not currently supported in +MSM. +

+

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 +be generated indicating the order parameter is being reduced to allow +LAMMPS to run the problem. Automatic adjustment of the order parameter +is not supported in MSM. +

+

The force keyword overrides the relative accuracy parameter set by +the kspace_style command with an absolute +accuracy. The accuracy determines the RMS error in per-atom forces +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, 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 for charge as rinv in reciprocal distance units. Without +this setting, LAMMPS chooses the parameter automatically as a function +of cutoff, precision, grid spacing, etc. This means it can vary from +one 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. MSM does not +use the gewald parameter. +

+

The gewald/disp keyword sets the value of the Ewald or PPPM G-ewald +parameter for dispersion as rinv in reciprocal distance units. It +has the same meaning as the gewald setting for Coulombics. +

+

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 +boundary setting of "boundary p p f". This is done by +treating the system as if it were periodic in z, but inserting empty +volume between atom slabs and removing dipole inter-slab interactions +so that slab-slab interactions are effectively turned off. The +volfactor value sets the ratio of the extended dimension in z divided +by the actual dimension in z. The recommended value is 3.0. A larger +value is inefficient; a smaller value introduces unwanted slab-slab +interactions. The use of fixed boundaries in z means that the user +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). The slab option +is also extended to non-neutral systems +(Ballenegger). 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. The nozforce option +is not supported by MSM. For MSM, any combination of periodic, +non-periodic, or shrink-wrapped boundaries can be set using +boundary (the slab approximation in not needed). The +slab keyword is not currently supported by Ewald or PPPM when using +a triclinic simulation cell. The slab correction has also been +extended to point dipole interactions (Klapp) in +kspace_style ewald/disp. +

+

The compute keyword allows Kspace computations to be turned off, +even though a kspace_style is defined. This is +not useful for running a real simulation, but can be useful for +debugging purposes or for computing only partial forces that do not +include the Kspace contribution. You can also do this by simply not +defining a kspace_style, but a Kspace-compatible +pair_style requires a kspace style to be defined. +This keyword gives you that option. +

+

The cutoff/adjust keyword applies only to MSM. If this option is +turned on, the Coulombic cutoff will be automatically adjusted at the +beginning of the run to give the desired estimated error. Other +cutoffs such as LJ will not be affected. If the grid is not set using +the mesh command, this command will also attempt to use the optimal +grid that minimizes cost using an estimate given by +(Hardy). Note that this cost estimate is not exact, somewhat +experimental, and still may not yield the optimal parameters. +

+

The fftbench keyword applies only to PPPM. It is on by default. If +this option is turned off, LAMMPS will not take the time at the end +of a run to give FFT benchmark timings, and will finish a few seconds +faster than it would if this option were on. +

+

The diff keyword specifies the differentiation scheme used by the +PPPM method to compute forces on particles given electrostatic +potentials on the PPPM mesh. The ik approach is the default for +PPPM and is the original formulation used in (Hockney). It +performs differentiation in Kspace, and uses 3 FFTs to transfer each +component of the computed fields back to real space for total of 4 +FFTs per timestep. +

+

The analytic differentiation ad approach uses only 1 FFT to transfer +information back to real space for a total of 2 FFTs per timestep. It +then performs analytic differentiation on the single quantity to +generate the 3 components of the electric field at each grid point. +This is sometimes referred to as "smoothed" PPPM. This approach +requires a somewhat larger PPPM mesh to achieve the same accuracy as +the ik method. Currently, only the ik method (default) can be +used for a triclinic simulation cell with PPPM. The ad method is +always used for MSM. +

+

IMPORTANT NOTE: Currently, not all PPPM styles support the ad +option. Support for those PPPM variants will be added later. +

+

The kmax/ewald keyword sets the number of kspace vectors in +each dimension for kspace style ewald. The three values must +be positive integers, or else (0,0,0), which unsets the option. +When this option is not +set, the Ewald sum scheme chooses its own kspace vectors, +consistent with the +user-specified accuracy and pairwise cutoff. In any case, +if kspace style ewald is invoked, the values used +are printed to the screen and +the log file at the start of the run. +

+

With the mix/disp keyword one can select the mixing rule for the +dispersion coefficients. With pair, the dispersion coefficients of +unlike types are computed as indicated with +pair_modify. With geom, geometric mixing is +enforced on the dispersion coefficients in the kspace +coefficients. When using the arithmetic mixing rule, this will +speed-up the simulations but introduces some error in the force +computations, as shown in (Wennberg). With none, it is +assumed that no mixing rule is applicable. Splitting of the dispersion +coefficients will be performed as described in +(Isele-Holder). This splitting can be influenced with +the splittol keywords. Only the eigenvalues that are larger than tol +compared to the largest eigenvalues are included. Using this keywords +the original matrix of dispersion coefficients is approximated. This +leads to faster computations, but the accuracy in the reciprocal space +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 +performance and accuracy in the results is obtained when these values +are different. +

+

Restrictions: none +

+

Related commands: +

+

kspace_style, boundary +

+

Default: +

+

The option defaults are mesh = mesh/disp = 0 0 0, order = order/disp = +5 (PPPM), order = 10 (MSM), minorder = 2, overlap = yes, force = -1.0, +gewald = gewald/disp = 0.0, slab = 1.0, compute = yes, cutoff/adjust = +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. +

+
+ + + +

(Hockney) Hockney and Eastwood, Computer Simulation Using Particles, +Adam Hilger, NY (1989). +

+ + +

(Yeh) Yeh and Berkowitz, J Chem Phys, 111, 3155 (1999). +

+ + +

(Ballenegger) Ballenegger, Arnold, Cerda, J Chem Phys, 131, 094107 +(2009). +

+ + +

(Klapp) Klapp, Schoen, J Chem Phys, 117, 8050 (2002). +

+ + +

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

+ + +

(Isele-Holder) Isele-Holder, Mitchell, Hammond, Kohlmeyer, Ismail, J +Chem Theory Comput, 9, 5412 (2013). +

+ + +

(Wennberg) Wennberg, Murtola, Hess, Lindahl, J Chem Theory Comput, +9, 3527 (2013). +

+ diff --git a/doc/kspace_modify.txt b/doc/kspace_modify.txt index d6fdef3f2e..2fa013e70b 100644 --- a/doc/kspace_modify.txt +++ b/doc/kspace_modify.txt @@ -1,304 +1,304 @@ -"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c - -:link(lws,http://lammps.sandia.gov) -:link(ld,Manual.html) -:link(lc,Section_commands.html#comm) - -:line - -kspace_modify command :h3 - -[Syntax:] - -kspace_modify keyword value ... :pre - -one or more keyword/value pairs may be listed :ulb,l -keyword = {mesh} or {order} or {order/disp} or {overlap} or {minorder} or {force} or {gewald} or {gewald/disp} or {slab} or (nozforce} or {compute} or {cutoff/adjust} or {diff} or {kmax/ewald} or {force/disp/real} or {force/disp/kspace} or {splittol} :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 - {order} value = N - N = extent of Gaussian for PPPM or MSM mapping of charge to grid - {order/disp} value = N - N = extent of Gaussian for PPPM mapping of dispersion term to grid - {overlap} = {yes} or {no} = whether the grid stencil for PPPM is allowed to overlap into more than the nearest-neighbor processor - {minorder} value = M - M = min allowed extent of Gaussian when auto-adjusting to minimize grid communication - {force} value = accuracy (force units) - {gewald} value = rinv (1/distance units) - rinv = G-ewald parameter for Coulombics - {gewald/disp} value = rinv (1/distance units) - rinv = G-ewald parameter for dispersion - {slab} value = volfactor or {nozforce} - volfactor = ratio of the total extended volume used in the - 2d approximation compared with the volume of the simulation domain - {nozforce} turns off kspace forces in the z direction - {compute} value = {yes} or {no} - {cutoff/adjust} value = {yes} or {no} - {fftbench} value = {yes} or {no} - {diff} value = {ad} or {ik} = 2 or 4 FFTs for PPPM in smoothed or non-smoothed mode - {kmax/ewald} value = kx ky kz - kx,ky,kz = number of Ewald sum kspace vectors in each dimension - {mix/disp} value = {pair} or {geom} or {none} - {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 -:ule - -[Examples:] - -kspace_modify mesh 24 24 30 order 6 -kspace_modify slab 3.0 :pre - -[Description:] - -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 grid size for kspace style {pppm} or -{msm}. In the case of PPPM, this is the FFT mesh, and each dimension -must be factorizable into powers of 2, 3, and 5. In the case of MSM, -this is the finest scale real-space mesh, and 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 {mesh/disp} keyword sets the grid size for kspace style -{pppm/disp}. This is the FFT mesh for long-range dispersion and ach -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 {order} keyword determines how many grid spacings an atom's charge -extends when it is mapped to the grid in kspace style {pppm} or {msm}. -The default for this parameter is 5 for PPPM and 8 for MSM, which -means each charge spans 5 or 8 grid cells in each dimension, -respectively. For the LAMMPS implementation of MSM, the order can -range from 4 to 10 and must be even. For PPPM, the minimum allowed -setting is 2 and the maximum allowed setting is 7. The larger the -value of this parameter, the smaller that LAMMPS will set the grid -size, to achieve the requested accuracy. Conversely, the smaller the -order value, the larger the grid size will be. Note that there is an -inherent trade-off involved: a small grid will lower the cost of FFTs -or MSM direct sum, but a larger order parameter will increase the cost -of interpolating charge/fields to/from the grid. - -The {order/disp} keyword determines how many grid spacings an atom's -dispersion term extends when it is mapped to the grid in kspace style -{pppm/disp}. It has the same meaning as the {order} setting for -Coulombics. - -The {overlap} keyword can be used in conjunction with the {minorder} -keyword with the PPPM styles to adjust the amount of communication -that occurs when values on the FFT grid are exchangeed between -processors. This communication is distinct from the communication -inherent in the parallel FFTs themselves, and is required because -processors interpolate charge and field values using grid point values -owned by neighboring processors (i.e. ghost point communication). If -the {overlap} keyword is set to {yes} then this communication is -allowed to extend beyond nearest-neighbor processors, e.g. when using -lots of processors on a small problem. If it is set to {no} then the -communication will be limited to nearest-neighbor processors and the -{order} setting will be reduced if necessary, as explained by the -{minorder} keyword discussion. The {overlap} keyword is always set to -{yes} in MSM. - -The {minorder} keyword allows LAMMPS to reduce the {order} setting if -necessary to keep the communication of ghost grid point limited to -exchanges between nearest-neighbor processors. See the discussion of -the {overlap} keyword for details. If the {overlap} keyword is set to -{yes}, which is the default, this is never needed. If it set to {no} -and overlap occurs, then LAMMPS will reduce the order setting, one -step at a time, until the ghost grid overlap only extends to nearest -neighbor processors. The {minorder} keyword limits how small the -{order} setting can become. The minimum allowed value for PPPM is 2, -which is the default. If {minorder} is set to the same value as -{order} then no reduction is allowed, and LAMMPS will generate an -error if the grid communcation is non-nearest-neighbor and {overlap} -is set to {no}. The {minorder} keyword is not currently supported in -MSM. - -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 -be generated indicating the order parameter is being reduced to allow -LAMMPS to run the problem. Automatic adjustment of the order parameter -is not supported in MSM. - -The {force} keyword overrides the relative accuracy parameter set by -the "kspace_style"_kspace_style.html command with an absolute -accuracy. The accuracy determines the RMS error in per-atom forces -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}, 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 for charge as {rinv} in reciprocal distance units. Without -this setting, LAMMPS chooses the parameter automatically as a function -of cutoff, precision, grid spacing, etc. This means it can vary from -one 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. MSM does not -use the {gewald} parameter. - -The {gewald/disp} keyword sets the value of the Ewald or PPPM G-ewald -parameter for dispersion as {rinv} in reciprocal distance units. It -has the same meaning as the {gewald} setting for Coulombics. - -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 -"boundary"_boundary.html setting of "boundary p p f". This is done by -treating the system as if it were periodic in z, but inserting empty -volume between atom slabs and removing dipole inter-slab interactions -so that slab-slab interactions are effectively turned off. The -volfactor value sets the ratio of the extended dimension in z divided -by the actual dimension in z. The recommended value is 3.0. A larger -value is inefficient; a smaller value introduces unwanted slab-slab -interactions. The use of fixed boundaries in z means that the user -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. The {slab} option -is also extended to non-neutral systems -"(Ballenegger)"_#Ballenegger. 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. The {nozforce} option -is not supported by MSM. For MSM, any combination of periodic, -non-periodic, or shrink-wrapped boundaries can be set using -"boundary"_boundary.html (the slab approximation in not needed). The -{slab} keyword is not currently supported by Ewald or PPPM when using -a triclinic simulation cell. The slab correction has also been -extended to point dipole interactions "(Klapp)"_#Klapp in -"kspace_style"_kspace_style.html {ewald/disp}. - -The {compute} keyword allows Kspace computations to be turned off, -even though a "kspace_style"_kspace_style.html is defined. This is -not useful for running a real simulation, but can be useful for -debugging purposes or for computing only partial forces that do not -include the Kspace contribution. You can also do this by simply not -defining a "kspace_style"_kspace_style.html, but a Kspace-compatible -"pair_style"_pair_style.html requires a kspace style to be defined. -This keyword gives you that option. - -The {cutoff/adjust} keyword applies only to MSM. If this option is -turned on, the Coulombic cutoff will be automatically adjusted at the -beginning of the run to give the desired estimated error. Other -cutoffs such as LJ will not be affected. If the grid is not set using -the {mesh} command, this command will also attempt to use the optimal -grid that minimizes cost using an estimate given by -"(Hardy)"_#Hardy. Note that this cost estimate is not exact, somewhat -experimental, and still may not yield the optimal parameters. - -The {fftbench} keyword applies only to PPPM. It is on by default. If -this option is turned off, LAMMPS will not take the time at the end -of a run to give FFT benchmark timings, and will finish a few seconds -faster than it would if this option were on. - -The {diff} keyword specifies the differentiation scheme used by the -PPPM method to compute forces on particles given electrostatic -potentials on the PPPM mesh. The {ik} approach is the default for -PPPM and is the original formulation used in "(Hockney)"_#Hockney. It -performs differentiation in Kspace, and uses 3 FFTs to transfer each -component of the computed fields back to real space for total of 4 -FFTs per timestep. - -The analytic differentiation {ad} approach uses only 1 FFT to transfer -information back to real space for a total of 2 FFTs per timestep. It -then performs analytic differentiation on the single quantity to -generate the 3 components of the electric field at each grid point. -This is sometimes referred to as "smoothed" PPPM. This approach -requires a somewhat larger PPPM mesh to achieve the same accuracy as -the {ik} method. Currently, only the {ik} method (default) can be -used for a triclinic simulation cell with PPPM. The {ad} method is -always used for MSM. - -IMPORTANT NOTE: Currently, not all PPPM styles support the {ad} -option. Support for those PPPM variants will be added later. - -The {kmax/ewald} keyword sets the number of kspace vectors in -each dimension for kspace style {ewald}. The three values must -be positive integers, or else (0,0,0), which unsets the option. -When this option is not -set, the Ewald sum scheme chooses its own kspace vectors, -consistent with the -user-specified accuracy and pairwise cutoff. In any case, -if kspace style {ewald} is invoked, the values used -are printed to the screen and -the log file at the start of the run. - -With the {mix/disp} keyword one can select the mixing rule for the -dispersion coefficients. With {pair}, the dispersion coefficients of -unlike types are computed as indicated with -"pair_modify"_pair_modify.html. With {geom}, geometric mixing is -enforced on the dispersion coefficients in the kspace -coefficients. When using the arithmetic mixing rule, this will -speed-up the simulations but introduces some error in the force -computations, as shown in "(Wennberg)"_#Wennberg. With {none}, it is -assumed that no mixing rule is applicable. Splitting of the dispersion -coefficients will be performed as described in -"(Isele-Holder)"_#Isele-Holder. This splitting can be influenced with -the {splittol} keywords. Only the eigenvalues that are larger than tol -compared to the largest eigenvalues are included. Using this keywords -the original matrix of dispersion coefficients is approximated. This -leads to faster computations, but the accuracy in the reciprocal space -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 -performance and accuracy in the results is obtained when these values -are different. - -[Restrictions:] none - -[Related commands:] - -"kspace_style"_kspace_style.html, "boundary"_boundary.html - -[Default:] - -The option defaults are mesh = mesh/disp = 0 0 0, order = order/disp = -5 (PPPM), order = 10 (MSM), minorder = 2, overlap = yes, force = -1.0, -gewald = gewald/disp = 0.0, slab = 1.0, compute = yes, cutoff/adjust = -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. - -:line - -:link(Hockney) -[(Hockney)] Hockney and Eastwood, Computer Simulation Using Particles, -Adam Hilger, NY (1989). - -:link(Yeh) -[(Yeh)] Yeh and Berkowitz, J Chem Phys, 111, 3155 (1999). - -:link(Ballenegger) -[(Ballenegger)] Ballenegger, Arnold, Cerda, J Chem Phys, 131, 094107 -(2009). - -:link(Klapp) -[(Klapp)] Klapp, Schoen, J Chem Phys, 117, 8050 (2002). - -:link(Hardy) -[(Hardy)] David Hardy thesis: Multilevel Summation for the Fast -Evaluation of Forces for the Simulation of Biomolecules, University of -Illinois at Urbana-Champaign, (2006). - -:link(Isele-Holder) -[(Isele-Holder)] Isele-Holder, Mitchell, Hammond, Kohlmeyer, Ismail, J -Chem Theory Comput, 9, 5412 (2013). - -:link(Wennberg) -[(Wennberg)] Wennberg, Murtola, Hess, Lindahl, J Chem Theory Comput, -9, 3527 (2013). +"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Section_commands.html#comm) + +:line + +kspace_modify command :h3 + +[Syntax:] + +kspace_modify keyword value ... :pre + +one or more keyword/value pairs may be listed :ulb,l +keyword = {mesh} or {order} or {order/disp} or {overlap} or {minorder} or {force} or {gewald} or {gewald/disp} or {slab} or (nozforce} or {compute} or {cutoff/adjust} or {diff} or {kmax/ewald} or {force/disp/real} or {force/disp/kspace} or {splittol} :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 + {order} value = N + N = extent of Gaussian for PPPM or MSM mapping of charge to grid + {order/disp} value = N + N = extent of Gaussian for PPPM mapping of dispersion term to grid + {overlap} = {yes} or {no} = whether the grid stencil for PPPM is allowed to overlap into more than the nearest-neighbor processor + {minorder} value = M + M = min allowed extent of Gaussian when auto-adjusting to minimize grid communication + {force} value = accuracy (force units) + {gewald} value = rinv (1/distance units) + rinv = G-ewald parameter for Coulombics + {gewald/disp} value = rinv (1/distance units) + rinv = G-ewald parameter for dispersion + {slab} value = volfactor or {nozforce} + volfactor = ratio of the total extended volume used in the + 2d approximation compared with the volume of the simulation domain + {nozforce} turns off kspace forces in the z direction + {compute} value = {yes} or {no} + {cutoff/adjust} value = {yes} or {no} + {fftbench} value = {yes} or {no} + {diff} value = {ad} or {ik} = 2 or 4 FFTs for PPPM in smoothed or non-smoothed mode + {kmax/ewald} value = kx ky kz + kx,ky,kz = number of Ewald sum kspace vectors in each dimension + {mix/disp} value = {pair} or {geom} or {none} + {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 +:ule + +[Examples:] + +kspace_modify mesh 24 24 30 order 6 +kspace_modify slab 3.0 :pre + +[Description:] + +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 grid size for kspace style {pppm} or +{msm}. In the case of PPPM, this is the FFT mesh, and each dimension +must be factorizable into powers of 2, 3, and 5. In the case of MSM, +this is the finest scale real-space mesh, and 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 {mesh/disp} keyword sets the grid size for kspace style +{pppm/disp}. This is the FFT mesh for long-range dispersion and ach +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 {order} keyword determines how many grid spacings an atom's charge +extends when it is mapped to the grid in kspace style {pppm} or {msm}. +The default for this parameter is 5 for PPPM and 8 for MSM, which +means each charge spans 5 or 8 grid cells in each dimension, +respectively. For the LAMMPS implementation of MSM, the order can +range from 4 to 10 and must be even. For PPPM, the minimum allowed +setting is 2 and the maximum allowed setting is 7. The larger the +value of this parameter, the smaller that LAMMPS will set the grid +size, to achieve the requested accuracy. Conversely, the smaller the +order value, the larger the grid size will be. Note that there is an +inherent trade-off involved: a small grid will lower the cost of FFTs +or MSM direct sum, but a larger order parameter will increase the cost +of interpolating charge/fields to/from the grid. + +The {order/disp} keyword determines how many grid spacings an atom's +dispersion term extends when it is mapped to the grid in kspace style +{pppm/disp}. It has the same meaning as the {order} setting for +Coulombics. + +The {overlap} keyword can be used in conjunction with the {minorder} +keyword with the PPPM styles to adjust the amount of communication +that occurs when values on the FFT grid are exchangeed between +processors. This communication is distinct from the communication +inherent in the parallel FFTs themselves, and is required because +processors interpolate charge and field values using grid point values +owned by neighboring processors (i.e. ghost point communication). If +the {overlap} keyword is set to {yes} then this communication is +allowed to extend beyond nearest-neighbor processors, e.g. when using +lots of processors on a small problem. If it is set to {no} then the +communication will be limited to nearest-neighbor processors and the +{order} setting will be reduced if necessary, as explained by the +{minorder} keyword discussion. The {overlap} keyword is always set to +{yes} in MSM. + +The {minorder} keyword allows LAMMPS to reduce the {order} setting if +necessary to keep the communication of ghost grid point limited to +exchanges between nearest-neighbor processors. See the discussion of +the {overlap} keyword for details. If the {overlap} keyword is set to +{yes}, which is the default, this is never needed. If it set to {no} +and overlap occurs, then LAMMPS will reduce the order setting, one +step at a time, until the ghost grid overlap only extends to nearest +neighbor processors. The {minorder} keyword limits how small the +{order} setting can become. The minimum allowed value for PPPM is 2, +which is the default. If {minorder} is set to the same value as +{order} then no reduction is allowed, and LAMMPS will generate an +error if the grid communcation is non-nearest-neighbor and {overlap} +is set to {no}. The {minorder} keyword is not currently supported in +MSM. + +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 +be generated indicating the order parameter is being reduced to allow +LAMMPS to run the problem. Automatic adjustment of the order parameter +is not supported in MSM. + +The {force} keyword overrides the relative accuracy parameter set by +the "kspace_style"_kspace_style.html command with an absolute +accuracy. The accuracy determines the RMS error in per-atom forces +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}, 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 for charge as {rinv} in reciprocal distance units. Without +this setting, LAMMPS chooses the parameter automatically as a function +of cutoff, precision, grid spacing, etc. This means it can vary from +one 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. MSM does not +use the {gewald} parameter. + +The {gewald/disp} keyword sets the value of the Ewald or PPPM G-ewald +parameter for dispersion as {rinv} in reciprocal distance units. It +has the same meaning as the {gewald} setting for Coulombics. + +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 +"boundary"_boundary.html setting of "boundary p p f". This is done by +treating the system as if it were periodic in z, but inserting empty +volume between atom slabs and removing dipole inter-slab interactions +so that slab-slab interactions are effectively turned off. The +volfactor value sets the ratio of the extended dimension in z divided +by the actual dimension in z. The recommended value is 3.0. A larger +value is inefficient; a smaller value introduces unwanted slab-slab +interactions. The use of fixed boundaries in z means that the user +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. The {slab} option +is also extended to non-neutral systems +"(Ballenegger)"_#Ballenegger. 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. The {nozforce} option +is not supported by MSM. For MSM, any combination of periodic, +non-periodic, or shrink-wrapped boundaries can be set using +"boundary"_boundary.html (the slab approximation in not needed). The +{slab} keyword is not currently supported by Ewald or PPPM when using +a triclinic simulation cell. The slab correction has also been +extended to point dipole interactions "(Klapp)"_#Klapp in +"kspace_style"_kspace_style.html {ewald/disp}. + +The {compute} keyword allows Kspace computations to be turned off, +even though a "kspace_style"_kspace_style.html is defined. This is +not useful for running a real simulation, but can be useful for +debugging purposes or for computing only partial forces that do not +include the Kspace contribution. You can also do this by simply not +defining a "kspace_style"_kspace_style.html, but a Kspace-compatible +"pair_style"_pair_style.html requires a kspace style to be defined. +This keyword gives you that option. + +The {cutoff/adjust} keyword applies only to MSM. If this option is +turned on, the Coulombic cutoff will be automatically adjusted at the +beginning of the run to give the desired estimated error. Other +cutoffs such as LJ will not be affected. If the grid is not set using +the {mesh} command, this command will also attempt to use the optimal +grid that minimizes cost using an estimate given by +"(Hardy)"_#Hardy. Note that this cost estimate is not exact, somewhat +experimental, and still may not yield the optimal parameters. + +The {fftbench} keyword applies only to PPPM. It is on by default. If +this option is turned off, LAMMPS will not take the time at the end +of a run to give FFT benchmark timings, and will finish a few seconds +faster than it would if this option were on. + +The {diff} keyword specifies the differentiation scheme used by the +PPPM method to compute forces on particles given electrostatic +potentials on the PPPM mesh. The {ik} approach is the default for +PPPM and is the original formulation used in "(Hockney)"_#Hockney. It +performs differentiation in Kspace, and uses 3 FFTs to transfer each +component of the computed fields back to real space for total of 4 +FFTs per timestep. + +The analytic differentiation {ad} approach uses only 1 FFT to transfer +information back to real space for a total of 2 FFTs per timestep. It +then performs analytic differentiation on the single quantity to +generate the 3 components of the electric field at each grid point. +This is sometimes referred to as "smoothed" PPPM. This approach +requires a somewhat larger PPPM mesh to achieve the same accuracy as +the {ik} method. Currently, only the {ik} method (default) can be +used for a triclinic simulation cell with PPPM. The {ad} method is +always used for MSM. + +IMPORTANT NOTE: Currently, not all PPPM styles support the {ad} +option. Support for those PPPM variants will be added later. + +The {kmax/ewald} keyword sets the number of kspace vectors in +each dimension for kspace style {ewald}. The three values must +be positive integers, or else (0,0,0), which unsets the option. +When this option is not +set, the Ewald sum scheme chooses its own kspace vectors, +consistent with the +user-specified accuracy and pairwise cutoff. In any case, +if kspace style {ewald} is invoked, the values used +are printed to the screen and +the log file at the start of the run. + +With the {mix/disp} keyword one can select the mixing rule for the +dispersion coefficients. With {pair}, the dispersion coefficients of +unlike types are computed as indicated with +"pair_modify"_pair_modify.html. With {geom}, geometric mixing is +enforced on the dispersion coefficients in the kspace +coefficients. When using the arithmetic mixing rule, this will +speed-up the simulations but introduces some error in the force +computations, as shown in "(Wennberg)"_#Wennberg. With {none}, it is +assumed that no mixing rule is applicable. Splitting of the dispersion +coefficients will be performed as described in +"(Isele-Holder)"_#Isele-Holder. This splitting can be influenced with +the {splittol} keywords. Only the eigenvalues that are larger than tol +compared to the largest eigenvalues are included. Using this keywords +the original matrix of dispersion coefficients is approximated. This +leads to faster computations, but the accuracy in the reciprocal space +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 +performance and accuracy in the results is obtained when these values +are different. + +[Restrictions:] none + +[Related commands:] + +"kspace_style"_kspace_style.html, "boundary"_boundary.html + +[Default:] + +The option defaults are mesh = mesh/disp = 0 0 0, order = order/disp = +5 (PPPM), order = 10 (MSM), minorder = 2, overlap = yes, force = -1.0, +gewald = gewald/disp = 0.0, slab = 1.0, compute = yes, cutoff/adjust = +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. + +:line + +:link(Hockney) +[(Hockney)] Hockney and Eastwood, Computer Simulation Using Particles, +Adam Hilger, NY (1989). + +:link(Yeh) +[(Yeh)] Yeh and Berkowitz, J Chem Phys, 111, 3155 (1999). + +:link(Ballenegger) +[(Ballenegger)] Ballenegger, Arnold, Cerda, J Chem Phys, 131, 094107 +(2009). + +:link(Klapp) +[(Klapp)] Klapp, Schoen, J Chem Phys, 117, 8050 (2002). + +:link(Hardy) +[(Hardy)] David Hardy thesis: Multilevel Summation for the Fast +Evaluation of Forces for the Simulation of Biomolecules, University of +Illinois at Urbana-Champaign, (2006). + +:link(Isele-Holder) +[(Isele-Holder)] Isele-Holder, Mitchell, Hammond, Kohlmeyer, Ismail, J +Chem Theory Comput, 9, 5412 (2013). + +:link(Wennberg) +[(Wennberg)] Wennberg, Murtola, Hess, Lindahl, J Chem Theory Comput, +9, 3527 (2013).