ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improve grammar and use terms consistent with the rest of LAMMPS

Browse Source
This commit is contained in:
Axel Kohlmeyer
2021-02-28 23:20:02 -05:00
parent cac03a85f3
commit a7e5f1acf2
1 changed files with 114 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
doc/src/pair_lj_relres.rst
View File

@ -13,10 +13,10 @@ Syntax
pair_style lj/relres Rsi Rso Rci Rco
* Rsi = inner switching distance between the fine-grained and coarse-grained potentials (distance units)
* Rso = outer switching distance between the fine-grained and coarse-grained potentials (distance units)
* Rci = inner cutting distance beyond which the force smoothing for all interactions is applied (distance units)
* Rco = outer cutting distance for all interactions (distance units)
* Rsi = inner cutoff for switching between the fine-grained and coarse-grained potentials (distance units)
* Rso = outer cutoff for switching between the fine-grained and coarse-grained potentials (distance units)
* Rci = inner cutoff beyond which the force smoothing for all interactions is applied (distance units)
* Rco = outer cutoff distance for all interactions (distance units)
Examples
""""""""
@ -30,13 +30,13 @@ Examples
Description
"""""""""""
Style *lj/relres* computes a LJ interaction using the Relative Resolution
(RelRes) framework which applies a fine-grained (FG) potential between near
neighbors and a coarse-grained (CG) potential between far neighbors
:ref:`(Chaimovich1) <Chaimovich1>`. The approach improves the computational
efficiency by almost an order of magnitude, while maintaining the correct
static and dynamic behavior of a reference system
:ref:`(Chaimovich2) <Chaimovich2>`.
Pair style *lj/relres* computes a LJ interaction using the Relative
Resolution (RelRes) framework which applies a fine-grained (FG)
potential between near neighbors and a coarse-grained (CG) potential
between far neighbors :ref:`(Chaimovich1) <Chaimovich1>`. This approach
can improve the computational efficiency by almost an order of
magnitude, while maintaining the correct static and dynamic behavior of
a reference system :ref:`(Chaimovich2) <Chaimovich2>`.
.. math::
@ -47,31 +47,31 @@ static and dynamic behavior of a reference system
\sum_{m=0}^{4} \gamma_{cm}\left(r-r_{ci}\right)^m -\Gamma_c, & \quad\mathrm{if}\quad r_{ci}\leq r< r_{co}, \\
0, & \quad\mathrm{if}\quad r\geq r_{co}.\end{array}\right.
The FG parameters of the LJ potential (:math:`\epsilon^{FG}` and
:math:`\sigma^{FG}`) are applied up to the inner switching distance,
:math:`r_{si}`, while the CG parameters of the LJ potential
(:math:`\epsilon^{CG}` and :math:`\sigma^{CG}`) are applied beyond the
outer switching distance, :math:`r_{so}`. Between :math:`r_{si}` and
:math:`r_{so}` a polynomial smoothing is applied in a way that the force,
together with its derivative, is continuous between the FG and CG potentials.
An analogous smoothing is applied between the inner and outer cutting
distances (:math:`r_{ci}` and :math:`r_{co}`). The shifting constants
:math:`\Gamma_{si}`, :math:`\Gamma_{so}` and :math:`\Gamma_{c}` ensure
the continuity of the energy over the entire domain.
The corresponding polynomial coefficients :math:`\gamma_{sm}` and
:math:`\gamma_{cm}`, as well as the shifting constants, are automatically
computed by LAMMPS.
The FG parameters of the LJ potential (:math:`\epsilon^{FG}` and
:math:`\sigma^{FG}`) are applied up to the inner switching distance,
:math:`r_{si}`, while the CG parameters of the LJ potential
(:math:`\epsilon^{CG}` and :math:`\sigma^{CG}`) are applied beyond the
outer switching distance, :math:`r_{so}`. Between :math:`r_{si}` and
:math:`r_{so}` a polynomial smoothing function is applied so that the
force and its derivative are continuous between the FG and CG
potentials. An analogous smoothing function is applied between the
inner and outer cutoff distances (:math:`r_{ci}` and :math:`r_{co}`).
The offsets :math:`\Gamma_{si}`, :math:`\Gamma_{so}` and
:math:`\Gamma_{c}` ensure the continuity of the energy over the entire
domain. The corresponding polynomial coefficients :math:`\gamma_{sm}`
and :math:`\gamma_{cm}`, as well as the offsets are automatically
computed by LAMMPS.
.. note::
Energy and force resulting from this methodology can be plotted via the
:doc:`pair_write <pair_write>` command.
The following coefficients must be defined for each pair of atom
types via the :doc:`pair_coeff <pair_coeff>` command as in the examples
above, or in the data file or restart files read by the
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
commands, or by mixing as will be described below:
The following coefficients must be defined for each pair of atom types
via the :doc:`pair_coeff <pair_coeff>` command as in the examples above,
or in the data file or restart files read by the :doc:`read_data
<read_data>` or :doc:`read_restart <read_restart>` commands, or by
mixing as will be described below:
* :math:`\epsilon^{FG}` (energy units)
* :math:`\sigma^{FG}` (distance units)
@ -79,7 +79,7 @@ commands, or by mixing as will be described below:
* :math:`\sigma^{CG}` (distance units)
Additional parameters can be defined to specify different
:math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`, :math:`r_{co}` for
:math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`, :math:`r_{co}` for
a particular set of atom types:
* :math:`r_{si}` (distance units)
@ -88,86 +88,88 @@ a particular set of atom types:
* :math:`r_{co}` (distance units)
These parameters are optional, and they are used to override the global
switching/cutting distances as defined in the pair_style command. If not
specified, the global values for :math:`r_{si}`, :math:`r_{so}`,
:math:`r_{ci}`, and :math:`r_{co}` are used. If this override option is
employed, all four arguments must be specified.
cutoffs as defined in the pair_style command. If not specified, the
global values for :math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`, and
:math:`r_{co}` are used. If this override option is employed, all four
arguments must be specified.
----------
Here are some guidelines for using the pair_style *lj/relres* command.
At the most basic level in the RelRes framework, groups of atoms must be
defined (even before utilizing the *lj/relres* pair style):
The atoms within each group must be bonded between each other, and
At the most basic level in the RelRes framework, groups of atoms must be
defined (even before utilizing the *lj/relres* pair style):
The atoms within each group must be bonded to each other, and
preferably, no two of these atoms are separated by more than two bonds.
One of the atoms in a group (typically the central one) is the "hybrid" site:
It embodies both FG and CG models. Conversely, all other atoms in a group
(typically the peripheral ones) are the "ordinary" sites: They embody just FG
characteristics with no CG features.
One of the atoms in a group (typically the central one) is the "hybrid" site:
It embodies both FG and CG models. Conversely, all other atoms in a group
(typically the peripheral ones) are the "ordinary" sites: They embody just FG
characteristics with no CG features.
Importantly, the computational efficiency of RelRes substantially depends on
the mapping ratio (the number of sites grouped together). For a mapping
ratio of 3, the efficiency factor is around 4, and for a mapping ratio of 5,
the efficiency factor is around 5 :ref:`(Chaimovich2) <Chaimovich2>`.
The computational efficiency of RelRes substantially depends on the
mapping ratio (the number of sites grouped together). For a mapping
ratio of 3, the efficiency factor is around 4, and for a mapping ratio
of 5, the efficiency factor is around 5 :ref:`(Chaimovich2)
<Chaimovich2>`.
The flexibility of LAMMPS allows placing any values for the LJ parameters
in the input script. However, here are the optimal recommendations for the
RelRes parameters, which yield the correct structural and thermal behavior
in a system of interest :ref:`(Chaimovich1) <Chaimovich1>`. Foremost, one
must presume a set of parameters for the FG interactions that applies for
all atom types. Regarding the parameters for the CG interactions, the rules
rely on the site category (if it is a hybrid or an ordinary site). For atom
types of ordinary sites, :math:`\epsilon^{CG}` must be set to 0 (zero) while
the specific value of :math:`\sigma^{CG}` is irrelevant. For atom types of
hybrid sites, the CG parameters should be generally calculated using the
The flexibility of LAMMPS allows placing any values for the LJ
parameters in the input script. However, here are the optimal
recommendations for the RelRes parameters, which yield the correct
structural and thermal behavior in a system of interest
:ref:`(Chaimovich1) <Chaimovich1>`. One must first assign a complete set of
parameters for the FG interactions that are applicable to all atom types.
Regarding the parameters for the CG interactions, the rules rely on the
site category (if it is a hybrid or an ordinary site). For atom types of
ordinary sites, :math:`\epsilon^{CG}` must be set to 0 (zero) while the
specific value of :math:`\sigma^{CG}` is irrelevant. For atom types of
hybrid sites, the CG parameters should be generally calculated using the
following equations:
.. math::
\sigma_I^{CG}=\frac{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^{12}}\right)^{1/2}}{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^6}\right)^{1/3}}
\sigma_I^{CG}=\frac{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^{12}}\right)^{1/2}}{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^6}\right)^{1/3}}
\quad\mathrm{and}\quad
\epsilon_I^{CG}=\frac{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^6}\right)^4}{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^{12}}\right)^2}
\epsilon_I^{CG}=\frac{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^6}\right)^4}{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^{12}}\right)^2}
where :math:`I` is an atom type of a hybrid site of a particular group
:math:`A`, and corresponding with this group, the summation proceeds over
where :math:`I` is an atom type of a hybrid site of a particular group
:math:`A`, and corresponding with this group, the summation proceeds over
all of its atoms :math:`\alpha`. This equation is the monopole term in the
underlying Taylor series, and it is indeed relevant only if
geometric mixing is applicable for the FG model; if this is not the case,
Ref. :ref:`(Chaimovich2) <Chaimovich2>` discusses the alternative option,
and in such situations, the pair_coeff command should be explicitly defined
for all combinations of atom types :math:`I\;!=J`.
underlying Taylor series, and it is indeed relevant only if
geometric mixing is applicable for the FG model; if this is not the case,
Ref. :ref:`(Chaimovich2) <Chaimovich2>` discusses alternative options,
and in such situations the pair_coeff command should be explicitly used
for all combinations of atom types :math:`I\;!=J`.
The switching distance is another crucial parameter in RelRes. Decreasing it
improves the computational efficiency, yet if it is too small, the molecular
simulations may be deficient in capturing the system behavior. As a rule of
thumb, the switching distance should be approximately
:math:`\,\sim\! 1.5\sigma` :ref:`(Chaimovich1) <Chaimovich1>`; thorough
recommendations can be found in Ref. :ref:`(Chaimovich2) <Chaimovich2>`.
Regarding the smoothing zone itself, :math:`\,\sim\! 0.1\sigma`
is recommended; if desired, it can be eliminated by setting the inner
switching distance, :math:`r_{si}`, equal to the outer switching distance,
:math:`r_{so}` (the same is true for the cutting distances :math:`r_{ci}` and
:math:`r_{co}`).
The switching distance is another crucial parameter in RelRes:
decreasing it improves the computational efficiency, yet if it is too
small, the molecular simulations may not capture the system behavior
correctly. As a rule of thumb, the switching distance should be
approximately :math:`\,\sim\! 1.5\sigma` :ref:`(Chaimovich1)
<Chaimovich1>`; recommendations can be found in Ref. :ref:`(Chaimovich2)
<Chaimovich2>`. Regarding the smoothing zone itself, :math:`\,\sim\!
0.1\sigma` is recommended; if desired, switching can be eliminated by setting
the inner switching cutoff, :math:`r_{si}`, equal to the outer
switching cutoff, :math:`r_{so}` (the same is true for the other cutoffs
:math:`r_{ci}` and :math:`r_{co}`).
----------
As an example, imagine that in your system, a molecule is comprised just
of one group such that one atom type (#1) is associated with
its hybrid site, and another atom type (#2) is associated with its ordinary
sites (in total, there are 2 atom types). If geometric mixing is applicable,
its hybrid site, and another atom type (#2) is associated with its ordinary
sites (in total, there are 2 atom types). If geometric mixing is applicable,
the following commands should be used:
.. code-block:: LAMMPS
pair_style lj/relres Rsi Rso Rci Rco
pair_coeff 1 1 epsilon_FG1 sigma_FG1 epsilon_CG1 sigma_CG1
pair_coeff 2 2 epsilon_FG2 sigma_FG2 0.0 0.0
pair_modify shift yes
pair_coeff 1 1 epsilon_FG1 sigma_FG1 epsilon_CG1 sigma_CG1
pair_coeff 2 2 epsilon_FG2 sigma_FG2 0.0 0.0
pair_modify shift yes
In a more complex situation, there may be two distinct groups in a system
(these two groups may be on same molecule or on different molecules),
each with its own switching distance. If there are still two atom types
In a more complex situation, there may be two distinct groups in a system
(these two groups may be on same molecule or on different molecules),
each with its own switching distance. If there are still two atom types
in each group as in the earlier example, the commands should be:
.. code-block:: LAMMPS
@ -175,18 +177,18 @@ in each group as in the earlier example, the commands should be:
pair_style lj/relres Rsi Rso Rci Rco
pair_coeff 1 1 epsilon_FG1 sigma_FG1 epsilon_CG1 sigma_CG1 Rsi1 Rso1 Rci Rco
pair_coeff 2 2 epsilon_FG2 sigma_FG2 0.0 0.0 Rsi1 Rso1 Rci Rco
pair_coeff 3 3 epsilon_FG3 sigma_FG3 epsilon_CG3 sigma_CG3
pair_coeff 4 4 epsilon_FG4 sigma_FG4 0.0 0.0
pair_modify shift yes
pair_coeff 3 3 epsilon_FG3 sigma_FG3 epsilon_CG3 sigma_CG3
pair_coeff 4 4 epsilon_FG4 sigma_FG4 0.0 0.0
pair_modify shift yes
In this example, the switching distance for the first group (atom types 1
and 2) is defined explicitly in the pair_coeff command which overrides the
global values, while the second group (atom types 3 and 4) uses the global
definition from the pair_style command. The emphasis here is that the atom
types that belong to a specific group should have the same switching/cutting
distances.
In this example, the switching distance for the first group (atom types 1
and 2) is defined explicitly in the pair_coeff command which overrides the
global values, while the second group (atom types 3 and 4) uses the global
definition from the pair_style command. The emphasis here is that the atom
types that belong to a specific group should have the same switching/cutting
distances.
In the case that geometric mixing is not applicable, for simulating the
In the case that geometric mixing is not applicable, for simulating the
system from the previous example, we recommend using the following commands:
.. code-block:: LAMMPS
@ -199,16 +201,16 @@ system from the previous example, we recommend using the following commands:
pair_coeff 2 2 epsilon_FG2 sigma_FG2 0.0 0.0 Rsi1 Rso1 Rci Rco
pair_coeff 2 3 epsilon_FG23 sigma_FG23 0.0 0.0 Rsi13 Rso13 Rci Rco
pair_coeff 2 4 epsilon_FG24 sigma_FG24 0.0 0.0 Rsi13 Rso13 Rci Rco
pair_coeff 3 3 epsilon_FG3 sigma_FG3 epsilon_CG3 sigma_CG3
pair_coeff 3 4 epsilon_FG34 sigma_FG34 0.0 0.0
pair_coeff 4 4 epsilon_FG4 sigma_FG4 0.0 0.0
pair_modify shift yes
pair_coeff 3 3 epsilon_FG3 sigma_FG3 epsilon_CG3 sigma_CG3
pair_coeff 3 4 epsilon_FG34 sigma_FG34 0.0 0.0
pair_coeff 4 4 epsilon_FG4 sigma_FG4 0.0 0.0
pair_modify shift yes
Notice that the CG parameters are mixed only for interactions between atom
types associated with hybrid sites, and that the switching distances are
mixed on the group basis.
Notice that the CG parameters are mixed only for interactions between atom
types associated with hybrid sites, and that the switching distances are
mixed on the group basis.
More examples can be found in the *examples/relres* folder.
More examples can be found in the *examples/relres* folder.
----------
@ -219,19 +221,19 @@ More examples can be found in the *examples/relres* folder.
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
For atom type pairs :math:`I,\:J` with :math:`I\;!=J`, the
:math:`\epsilon^{FG}`, :math:`\sigma^{FG}`, :math:`\epsilon^{CG}`,
:math:`\sigma^{CG}`, :math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`,
and :math:`r_{co}` parameters for this pair style can be mixed, if
not defined explicitly. All parameters are mixed according to the
pair_modify mix option. The default mix value is *geometric*\ ,
and it is recommended to use with this *lj/relres* style. See the
For atom type pairs :math:`I,\:J` with :math:`I\;!=J`, the
:math:`\epsilon^{FG}`, :math:`\sigma^{FG}`, :math:`\epsilon^{CG}`,
:math:`\sigma^{CG}`, :math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`,
and :math:`r_{co}` parameters for this pair style can be mixed, if
not defined explicitly. All parameters are mixed according to the
pair_modify mix option. The default mix value is *geometric*\ ,
and it is recommended to use with this *lj/relres* style. See the
"pair_modify" command for details.
This pair style supports the :doc:`pair_modify <pair_modify>` shift
option for the energy of the pair interaction. It is recommended to set
this option to *yes*\ . Otherwise, the shifting constant :math:`\Gamma_{c}`
is set to zero. Constants :math:`\Gamma_{si}` and :math:`\Gamma_{so}` are
is set to zero. Constants :math:`\Gamma_{si}` and :math:`\Gamma_{so}` are
not impacted by this option.
The :doc:`pair_modify <pair_modify>` table option is not relevant
@ -270,11 +272,11 @@ none
.. _Chaimovich1:
**(Chaimovich1)** A.Chaimovich, C. Peter and K. Kremer, J. Chem. Phys. 143,
**(Chaimovich1)** A.Chaimovich, C. Peter and K. Kremer, J. Chem. Phys. 143,
243107 (2015).
.. _Chaimovich2:
**(Chaimovich2)** M.Chaimovich and A. Chaimovich, J. Chem. Theory Comput. 17,
**(Chaimovich2)** M.Chaimovich and A. Chaimovich, J. Chem. Theory Comput. 17,
1045-1059 (2021).