update documentation for pair_modify to reflect code changes and clarify the use of special
This commit is contained in:
Axel Kohlmeyer
@ -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 <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 <pair_hybrid>`, 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_hybrid>` 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 <pair_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 <special_bonds>` settings for the specified sub-style.
|
||||
*compute/tally* allows to disable or enable registering
|
||||
:doc:`compute \*/tally <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 <read_data>`. 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 <pair_coeff>` command or in the "Pair Coeffs" section of the
|
||||
:doc:`data file <read_data>`. 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 <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 <pair_hybrid>`.
|
||||
See the doc page for individual pair styles for those restrictions. Note also that the
|
||||
:doc:`pair_coeff <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) <Wolff1>` 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) <Wolff1>` 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 <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 <fix_nh>` and :doc:`fix nph <fix_nh>`
|
||||
commands). The formulas used for the long-range corrections come from
|
||||
equation 5 of :ref:`(Sun) <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
|
||||
<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 <fix_nh>` and
|
||||
:doc:`fix nph <fix_nh>` commands). The formulas used for the
|
||||
long-range corrections come from equation 5 of :ref:`(Sun) <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 <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 <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 <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 <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 <pair_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 <kspace_style>` command requires a Kspace-compatible
|
||||
pair style be defined.
|
||||
a pair style will not work, because the :doc:`kspace_style
|
||||
<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_hybrid>` 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 <pair_hybrid>`. It requires 4 arguments similar
|
||||
to the :doc:`special_bonds <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 <pair_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 <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 <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 <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 <compute_tally>` styles for a given
|
||||
:doc:`pair hybrid or hybrid/overlay <pair_hybrid>` 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 <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 <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 <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 <pair_style>`, :doc:`pair_style hybrid <pair_hybrid>`,
|
||||
pair\_coeff"_pair\_coeff.html, :doc:`thermo_style <thermo_style>`,
|
||||
:doc:`pair_coeff <pair_coeff>`, :doc:`thermo_style <thermo_style>`,
|
||||
:doc:`compute \*/tally <compute_tally>`
|
||||
|
||||
Default
|
||||
|
||||
Reference in New Issue
Block a user