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