pair_modify command — LAMMPS documentation

\(\renewcommand{\AA}{\text{Å}}\)

# pair_modify command

## Syntax

    pair_modify keyword values ...

- 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 special or compute/tally or neigh/trim

      pair value = sub-style N
        sub-style = sub-style of pair hybrid
        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
        2^N = # of values in table
      table/disp value = N
        2^N = # of values in table
      tabinner value = cutoff
        cutoff = inner cutoff at which to begin table (distance units)
      tabinner/disp value = cutoff
        cutoff = inner cutoff at which to begin table (distance units)
      tail value = yes or no
      compute value = yes or no
      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
      neigh/trim value = yes or no

## Examples

    pair_modify shift yes mix geometric
    pair_modify tail yes
    pair_modify table 12
    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. If the pair style is hybrid or hybrid/overlay, then the specified parameters are by default modified for all the hybrid sub-styles.

Note

The behavior for hybrid pair styles can be changed by using the pair keyword, which allows selection of a specific sub-style to apply all remaining keywords 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” or “PairIJ Coeffs” sections of the 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 and some mix options are not available for certain pair styles. Also, there are additional restrictions when using pair style hybrid or hybrid/overlay. See the page for individual pair styles for those restrictions. Note also that the pair_coeff command also can be used to directly set coefficients for a specific I != J pairing, in which case no mixing is performed. If possible, LAMMPS will print an informational message about how many of the mixed pair coefficients were generated and which mixing rule was applied.

- mix geometric

  \[\begin{split}\epsilon_{ij} = & \sqrt{\epsilon_i \epsilon_j} \\ \sigma_{ij} = & \sqrt{\sigma_i \sigma_j}\end{split}\]

- mix arithmetic

  \[\begin{split}\epsilon_{ij} = & \sqrt{\epsilon_i \epsilon_j} \\ \sigma_{ij} = & \frac{1}{2} (\sigma_i + \sigma_j)\end{split}\]

- mix sixthpower

  \[\begin{split}\epsilon_{ij} = & \frac{2 \sqrt{\epsilon_i \epsilon_j} \sigma_i^3 \sigma_j^3}{\sigma_i^6 + \sigma_j^6} \\ \sigma_{ij} = & \left(\frac{1}{2} (\sigma_i^6 + \sigma_j^6) \right)^{\frac{1}{6}}\end{split}\]

The shift keyword determines whether a Lennard-Jones potential is shifted at its cutoff to 0.0. If so, this adds an energy term to each pairwise interaction which will be included in the thermodynamic output, but does not affect pair forces or atom trajectories. See the doc page for individual pair styles to see which ones support this option.

The table and table/disp keywords apply to pair styles with a long-range Coulombic term or long-range dispersion term respectively; see the 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 (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 memory which can slow down the computation due to cache misses. A reasonable value of N is between 8 and 16. The default value of 12 (table of length 4096) gives approximately the same accuracy as the no-table (N = 0) option. For N = 0, forces and energies are computed directly, using a polynomial fit for the needed erfc() function evaluation, which is what earlier versions of LAMMPS did. Values greater than 16 typically slow down the simulation and will not improve accuracy; values from 1 to 8 give unreliable results.

The tabinner and tabinner/disp keywords set an inner cutoff above which the pairwise computation is done by table lookup (if tables are invoked), for the corresponding Coulombic and dispersion tables discussed with the table and table/disp keywords. The smaller the cutoff is set, the less accurate the table becomes (for a given number of table values), which can require use of larger tables. The default cutoff value is sqrt(2.0) distance units which means nearly all 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 page for individual styles to see which support this option. These corrections are included in the calculation and printing of thermodynamic quantities (see the 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 fix npt and fix nph commands). The formulas used for the long-range corrections come from equation 5 of (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 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:

- The simulated system is a 3d bulk homogeneous liquid. This option 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.

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

The compute keyword allows pairwise computations to be turned off, even though a pair_style is defined. This is not useful for running a real simulation, but can be useful for debugging purposes or for performing a rerun simulation, when you only wish to compute partial forces that do not include the pairwise contribution.

Two examples are as follows. First, this option allows you to perform a simulation with 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 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 pair keyword can only be used with the hybrid and hybrid/overlay pair styles. If used, it must appear first in the list of keywords.

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 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 special_bonds 1-2, 1-3, 1-4 exclusion settings (weights) for the sub-style selected by the pair keyword.

Similar to the 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 special keyword is not compatible with pair styles from the GPU or the INTEL package and attempting to use it will cause an error.

Note

Weights of exactly 0.0 or 1.0 in the 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 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 between 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 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.

Added in version 3Aug2022.

The neigh/trim keyword controls whether an explicit cutoff is set for each neighbor list request issued by individual pair sub-styles when using pair hybrid/overlay. When this keyword is set to no, then the cutoff of each pair sub-style neighbor list will be set equal to the largest cutoff, even if a shorter cutoff is specified for a particular sub-style. If possible the neighbor list will be copied directly from another list. When this keyword is set to yes then the cutoff of the neighbor list will be explicitly set to the value requested by the pair sub-style, and if possible the list will be created by trimming neighbors from another list with a longer cutoff, otherwise a new neighbor list will be created with the specified cutoff. The yes option can be faster when there are multiple pair styles with different cutoffs since the number of pair-wise distance checks between neighbors is reduced (but the time required to build the neighbor lists is increased). The no option could be faster when two or more neighbor lists have similar (but not exactly the same) cutoffs.

Note

The “pair_modify neigh/trim” command only applies when there are multiple pair sub-styles for the same atoms with different cutoffs, i.e. when using pair style hybrid/overlay. If you have different cutoffs for different pairs for atoms type, the neighbor style multi should be used to create optimized neighbor lists.

## Restrictions

You cannot use shift yes with tail yes, since those are conflicting options. You cannot use tail yes with 2d simulations. You cannot use special with pair styles from the GPU or INTEL package.

## Related commands

pair_style, pair_style hybrid, pair_coeff, thermo_style, compute */tally, neighbor multi

## Default

The option defaults are mix = geometric, shift = no, table = 12, tabinner = sqrt(2.0), tail = no, compute = yes, and neigh/trim yes.

Note that some pair styles perform mixing, but only a certain style of mixing. See the doc pages for individual pair styles for details.

(Wolff) Wolff and Rudd, Comp Phys Comm, 120, 200-32 (1999).

(Sun) Sun, J Phys Chem B, 102, 7338-7364 (1998).