diff --git a/doc/src/pair_modify.rst b/doc/src/pair_modify.rst index dee1390234..7694279e20 100644 --- a/doc/src/pair_modify.rst +++ b/doc/src/pair_modify.rst @@ -13,18 +13,14 @@ Syntax * one or more keyword/value pairs may be listed * keyword = *pair* or *shift* or *mix* or *table* or *table/disp* or *tabinner* - or *tabinner/disp* or *tail* or *compute* or *nofdotr* + or *tabinner/disp* or *tail* or *compute* or *nofdotr* or *special* or + *compute/tally* .. parsed-literal:: - *pair* values = sub-style N *special* which wt1 wt2 wt3 - or sub-style N *compute/tally* flag + *pair* value = sub-style N sub-style = sub-style of :doc:`pair hybrid ` - N = which instance of sub-style (only if sub-style is used multiple times) - *special* which wt1 wt2 wt3 = override *special_bonds* settings (optional) - which = *lj/coul* or *lj* or *coul* - w1,w2,w3 = 1-2, 1-3, and 1-4 weights from 0.0 to 1.0 inclusive - *compute/tally* flag = *yes* or *no* + N = which instance of sub-style (1 to M), only specify if sub-style is used multiple times *mix* value = *geometric* or *arithmetic* or *sixthpower* *shift* value = *yes* or *no* *table* value = N @@ -37,8 +33,11 @@ Syntax cutoff = inner cutoff at which to begin table (distance units) *tail* value = *yes* or *no* *compute* value = *yes* or *no* - *nofdotr* - + *nofdotr* value = none + *special* values = which wt1 wt2 wt3 + which = *lj/coul* or *lj* or *coul* + w1,w2,w3 = 1-2, 1-3, 1-4 weights from 0.0 to 1.0 inclusive + *compute/tally* value = *yes* or *no* Examples @@ -53,47 +52,40 @@ Examples pair_modify pair lj/cut compute no pair_modify pair tersoff compute/tally no pair_modify pair lj/cut/coul/long 1 special lj/coul 0.0 0.0 0.0 + pair_modify pair lj/cut/coul/long special lj 0.0 0.0 0.5 special coul 0.0 0.0 0.8333333 Description """"""""""" -Modify the parameters of the currently defined pair style. Not all -parameters are relevant to all pair styles. +Modify the parameters of the currently defined pair style. If the +pair style is :doc:`hybrid or hybrid/overlay `, then the +specified parameters are by default modified for all the hybrid sub-styles. -If used, the *pair* keyword must appear first in the list of keywords. -It can only be used with the :doc:`hybrid and hybrid/overlay ` pair styles. It means that all the -following parameters will only be modified for the specified -sub-style. If the sub-style is defined multiple times, then an -additional numeric argument *N* must also be specified, which is a -number from 1 to M where M is the number of times the sub-style was -listed in the :doc:`pair_style hybrid ` command. The extra -number indicates which instance of the sub-style the remaining -keywords will be applied to. Note that if the *pair* keyword is not -used, and the pair style is *hybrid* or *hybrid/overlay*\ , then all the -specified keywords will be applied to all sub-styles. +.. note:: -The *special* and *compute/tally* keywords can **only** be used in -conjunction with the *pair* keyword and must directly follow it. -*special* allows to override the -:doc:`special_bonds ` settings for the specified sub-style. -*compute/tally* allows to disable or enable registering -:doc:`compute \*/tally ` computes for a given sub-style. -More details are given below. + The behavior for hybrid pair styles can be changed by using the *pair* + keyword, which allows to select a specific sub-style to apply a setting to. + The *special* and *compute/tally* keywords can **only** be + used in conjunction with the *pair* keyword. See further details about + these 3 keywords below. The *mix* keyword affects pair coefficients for interactions between atoms of type I and J, when I != J and the coefficients are not explicitly set in the input script. Note that coefficients for I = J must be set explicitly, either in the input script via the -"pair\_coeff" command or in the "Pair Coeffs" section of the :doc:`data file `. For some pair styles it is not necessary to -specify coefficients when I != J, since a "mixing" rule will create -them from the I,I and J,J settings. The pair\_modify *mix* value -determines what formulas are used to compute the mixed coefficients. -In each case, the cutoff distance is mixed the same way as sigma. +:doc:`pair_coeff ` command or in the "Pair Coeffs" section of the +:doc:`data file `. For some pair styles it is not +necessary to specify coefficients when I != J, since a "mixing" rule +will create them from the I,I and J,J settings. The pair\_modify +*mix* value determines what formulas are used to compute the mixed +coefficients. In each case, the cutoff distance is mixed the same way +as sigma. -Note that not all pair styles support mixing. Also, some mix options -are not available for certain pair styles. See the doc page for -individual pair styles for those restrictions. Note also that the -:doc:`pair_coeff ` command also can be to directly set +Note that not all pair styles support mixing and some mix options +are not available for certain pair styles. Also, there are additional +restrictions when using :doc:`pair style hybrid or hybrid/overlay `. +See the doc page for individual pair styles for those restrictions. Note also that the +:doc:`pair_coeff ` command also can be used to directly set coefficients for a specific I != J pairing, in which case no mixing is performed. @@ -135,10 +127,11 @@ see the doc page for individual styles to see which potentials support these options. If N is non-zero, a table of length 2\^N is pre-computed for forces and energies, which can shrink their computational cost by up to a factor of 2. The table is indexed via a -bit-mapping technique :ref:`(Wolff) ` and a linear interpolation is -performed between adjacent table values. In our experiments with -different table styles (lookup, linear, spline), this method typically -gave the best performance in terms of speed and accuracy. +bit-mapping technique :ref:`(Wolff) ` and a linear +interpolation is performed between adjacent table values. In our +experiments with different table styles (lookup, linear, spline), this +method typically gave the best performance in terms of speed and +accuracy. The choice of table length is a tradeoff in accuracy versus speed. A larger N yields more accurate force computations, but requires more @@ -162,27 +155,28 @@ pairwise interactions are computed via table lookup for simulations with "real" units, but some close pairs may be computed directly (non-table) for simulations with "lj" units. -When the *tail* keyword is set to *yes*\ , certain pair styles will add -a long-range VanderWaals tail "correction" to the energy and pressure. -These corrections are bookkeeping terms which do not affect dynamics, -unless a constant-pressure simulation is being performed. See the doc -page for individual styles to see which support this option. These -corrections are included in the calculation and printing of -thermodynamic quantities (see the :doc:`thermo_style ` -command). Their effect will also be included in constant NPT or NPH -simulations where the pressure influences the simulation box -dimensions (e.g. the :doc:`fix npt ` and :doc:`fix nph ` -commands). The formulas used for the long-range corrections come from -equation 5 of :ref:`(Sun) `. +When the *tail* keyword is set to *yes*\ , certain pair styles will +add a long-range VanderWaals tail "correction" to the energy and +pressure. These corrections are bookkeeping terms which do not affect +dynamics, unless a constant-pressure simulation is being performed. +See the doc page for individual styles to see which support this +option. These corrections are included in the calculation and +printing of thermodynamic quantities (see the :doc:`thermo_style +` command). Their effect will also be included in +constant NPT or NPH simulations where the pressure influences the +simulation box dimensions (e.g. the :doc:`fix npt ` and +:doc:`fix nph ` commands). The formulas used for the +long-range corrections come from equation 5 of :ref:`(Sun) `. .. note:: The tail correction terms are computed at the beginning of each run, using the current atom counts of each atom type. If atoms are - deleted (or lost) or created during a simulation, e.g. via the :doc:`fix gcmc ` command, the correction factors are not - re-computed. If you expect the counts to change dramatically, you can - break a run into a series of shorter runs so that the correction - factors are re-computed more frequently. + deleted (or lost) or created during a simulation, e.g. via the + :doc:`fix gcmc ` command, the correction factors are not + re-computed. If you expect the counts to change dramatically, you + can break a run into a series of shorter runs so that the + correction factors are re-computed more frequently. Several additional assumptions are inherent in using tail corrections, including the following: @@ -191,26 +185,27 @@ including the following: should not be used for systems that are non-liquid, 2d, have a slab geometry (only 2d periodic), or inhomogeneous. * G(r), the radial distribution function (rdf), is unity beyond the - cutoff, so a fairly large cutoff should be used (i.e. 2.5 sigma for an - LJ fluid), and it is probably a good idea to verify this assumption by - checking the rdf. The rdf is not exactly unity beyond the cutoff for - each pair of interaction types, so the tail correction is necessarily - an approximation. + cutoff, so a fairly large cutoff should be used (i.e. 2.5 sigma for + an LJ fluid), and it is probably a good idea to verify this + assumption by checking the rdf. The rdf is not exactly unity beyond + the cutoff for each pair of interaction types, so the tail + correction is necessarily an approximation. - The tail corrections are computed at the beginning of each simulation - run. If the number of atoms changes during the run, e.g. due to atoms - leaving the simulation domain, or use of the :doc:`fix gcmc ` - command, then the corrections are not updated to reflect the changed - atom count. If this is a large effect in your simulation, you should - break the long run into several short runs, so that the correction - factors are re-computed multiple times. + The tail corrections are computed at the beginning of each + simulation run. If the number of atoms changes during the run, + e.g. due to atoms leaving the simulation domain, or use of the + :doc:`fix gcmc ` command, then the corrections are not + updated to reflect the changed atom count. If this is a large + effect in your simulation, you should break the long run into + several short runs, so that the correction factors are re-computed + multiple times. -* Thermophysical properties obtained from calculations with this option - enabled will not be thermodynamically consistent with the truncated - force-field that was used. In other words, atoms do not feel any LJ - pair interactions beyond the cutoff, but the energy and pressure - reported by the simulation include an estimated contribution from - those interactions. +* Thermophysical properties obtained from calculations with this + option enabled will not be thermodynamically consistent with the + truncated force-field that was used. In other words, atoms do not + feel any LJ pair interactions beyond the cutoff, but the energy and + pressure reported by the simulation include an estimated + contribution from those interactions. The *compute* keyword allows pairwise computations to be turned off, @@ -225,53 +220,73 @@ a simulation with :doc:`pair_style hybrid ` with only a subset of the hybrid sub-styles enabled. Second, this option allows you to perform a simulation with only long-range interactions but no short-range pairwise interactions. Doing this by simply not defining -a pair style will not work, because the -:doc:`kspace_style ` command requires a Kspace-compatible -pair style be defined. +a pair style will not work, because the :doc:`kspace_style +` command requires a Kspace-compatible pair style be +defined. The *nofdotr* keyword allows to disable an optimization that computes -the global stress tensor from the total forces and atom positions rather -than from summing forces between individual pairs of atoms. +the global stress tensor from the total forces and atom positions +rather than from summing forces between individual pairs of atoms. ---------- +The *pair* keyword can only be used with the :doc:`hybrid and +hybrid/overlay ` pair styles. If used, it must appear +first in the list of keywords. -The *special* keyword allows to override the 1-2, 1-3, and 1-4 -exclusion settings for individual sub-styles of a -:doc:`hybrid pair style `. It requires 4 arguments similar -to the :doc:`special_bonds ` command, *which* and -wt1,wt2,wt3. The *which* argument can be *lj* to change the -Lennard-Jones settings, *coul* to change the Coulombic settings, -or *lj/coul* to change both to the same set of 3 values. The wt1,wt2,wt3 -values are numeric weights from 0.0 to 1.0 inclusive, for the 1-2, -1-3, and 1-4 bond topology neighbors, respectively. The *special* -keyword can only be used in conjunction with the *pair* keyword -and has to directly follow it. This option is not compatible with -pair styles from the GPU or the USER-INTEL package and attempting -it will cause an error. +Its meaning is that all the following parameters will only be modified +for the specified sub-style. If the sub-style is defined multiple +times, then an additional numeric argument *N* must also be specified, +which is a number from 1 to M where M is the number of times the +sub-style was listed in the :doc:`pair_style hybrid ` +command. The extra number indicates which instance of the sub-style +the remaining keywords will be applied to. + +The *special* and *compute/tally* keywords can **only** be used in +conjunction with the *pair* keyword and they must directly follow it. +I.e. any other keyword, must appear after *pair*, *special*, and +*compute/tally*. + +The *special* keyword overrides the global :doc:`special_bonds ` +1-2, 1-3, 1-4 exclusion settings (weights) for the sub-style selected +by the *pair* keyword. + +Similar to the :doc:`special_bonds ` command, it takes +4 arguments. The *which* argument can be *lj* to change only the +non-Coulomb weights (e.g. Lennard-Jones or Buckingham), *coul* to change +only the Coulombic settings, or *lj/coul* to change both to the same +values. The *wt1,wt2,wt3* values are numeric weights from 0.0 to 1.0 +inclusive, for the 1-2, 1-3, and 1-4 bond topology neighbors, respectively. +The *special* keyword can be used multiple times, e.g. to set the *lj* +and *coul* settings to different values. .. note:: - The global settings specified by the - :doc:`special_bonds ` command affect the construction of - neighbor lists. Weights of 0.0 (for 1-2, 1-3, or 1-4 neighbors) - exclude those pairs from the neighbor list entirely. Weights of 1.0 - store the neighbor with no weighting applied. Thus only global values - different from exactly 0.0 or 1.0 can be overridden and an error is - generated if the requested setting is not compatible with the global - setting. Substituting 1.0e-10 for 0.0 and 0.9999999999 for 1.0 is - usually a sufficient workaround in this case without causing a - significant error. - -The *compute/tally* keyword takes exactly 1 argument (\ *no* or *yes*\ ), -and allows to selectively disable or enable processing of the various -:doc:`compute \*/tally ` styles for a given -:doc:`pair hybrid or hybrid/overlay ` sub-style. + The *special* keyword is not compatible with pair styles from the + GPU or the USER-INTEL package and attempting to use it will cause + an error. .. note:: - Any "pair\_modify pair compute/tally" command must be issued + Weights of exactly 0.0 or 1.0 in the :doc:`special_bonds ` + command have implications on the neighbor list construction, which + means that they cannot be overridden by using the *special* keyword. + One workaround for this restriction is to use the :doc:`special_bonds ` + command with weights like 1.0e-10 or 0.999999999 instead of 0.0 or 1.0, + respectively, which enables to reset each them to any value between 0.0 + and 1.0 inclusively. Otherwise you can set **all** global weights to + an arbitrary number outside of 0.0 or 1.0, like 0.5, and then you have + to override **all** *special* settings for **all** sub-styles which use + the 1-2, 1-3, and 1-4 exclusion weights in their force/energy computation. + +The *compute/tally* keyword disables or enables registering :doc:`compute +\*/tally ` computes for the sub-style specified by +the *pair* keyword. Use *no* to disable, or *yes* to enable. + +.. note:: + + The "pair_modify pair compute/tally" command must be issued **before** the corresponding compute style is defined. @@ -290,7 +305,7 @@ Related commands """""""""""""""" :doc:`pair_style `, :doc:`pair_style hybrid `, -pair\_coeff"_pair\_coeff.html, :doc:`thermo_style `, +:doc:`pair_coeff `, :doc:`thermo_style `, :doc:`compute \*/tally ` Default