Documentation and examples updated according to @sjplimp request

This commit is contained in:
Mark Chaimovich
2021-02-28 21:30:55 -05:00
parent 1e3b63c335
commit 175e6c964a
5 changed files with 37357 additions and 79 deletions

View File

@ -13,10 +13,10 @@ Syntax
pair_style lj/relres Rsi Rso Rci Rco
* Rsi = inner switching distance - boundary up to which LJ potential of fine-grained model is applied (distance units)
* Rso = outer switching distance - boundary beyond which LJ potential of coarse-grained model is applied (distance units)
* Rci = inner cutoff beyond which force smoothing is applied (distance units)
* Rco = outer cutoff for lj/relres interactions (distance units)
* 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)
Examples
""""""""
@ -24,55 +24,48 @@ Examples
.. code-block:: LAMMPS
pair_style lj/relres 4.0 5.0 8.0 10.0
pair_coeff * * 0.5 1.0 0.0 1.0
pair_coeff 1 1 1.5 1.2 3.0 1.2 3.0 3.5 6.0 7.0
pair_coeff 1 1 0.5 1.0 1.5 1.1
pair_coeff 2 2 0.5 1.0 0.0 0.0 3.0 3.5 6.0 7.0
Description
"""""""""""
Style *lj/relres* computes a LJ model using the RelRes methodology
developed by :ref:`Chaimovich at al.<Chaimovich1>`. This methodology
applies a fine-grained model between near neighbors (up to
:math:`r_{si}` boundary) and a simplified coarse-grained model for far
neighbors (beyond :math:`r_{so}` boundary) and thus resulting in a
significant improvement in computational efficiency while preserving
the correctness of the simulation results.
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>`.
.. math::
E = \left\{\begin{array}{lr}
4 \epsilon^{FG} \left[ \left(\frac{\sigma^{FG}}{r}\right)^{12} - \left(\frac{\sigma^{FG}}{r}\right)^6 \right]-G_{si}, & r< r_{si} \\
\sum_{m=0}^{4} C_{sm}\left(r-r_{si}\right)^m-G_{so} , & r_{si}\leq r< r_{so} \\
4 \epsilon^{CG} \left[ \left(\frac{\sigma^{CG}}{r}\right)^{12} - \left(\frac{\sigma^{CG}}{r}\right)^6 \right]-G_c, & r_{so}\leq r<r_{ci} \\
\sum_{m=0}^{4} C_{cm}\left(r-r_{ci}\right)^m -G_c, & r_{ci}\leq r< r_{co} \\
0, & r\geq r_{co}\end{array}\right.
4 \epsilon^{\scriptscriptstyle FG} \left[ \left(\frac{\sigma^{FG}}{r}\right)^{12} - \left(\frac{\sigma^{FG}}{r}\right)^6 \right]-\Gamma_{si}, & \quad\mathrm{if}\quad r< r_{si}, \\
\sum_{m=0}^{4} \gamma_{sm}\left(r-r_{si}\right)^m-\Gamma_{so} , & \quad\mathrm{if}\quad r_{si}\leq r< r_{so}, \\
4 \epsilon^{\scriptscriptstyle CG} \left[ \left(\frac{\sigma^{CG}}{r}\right)^{12} - \left(\frac{\sigma^{CG}}{r}\right)^6 \right]-\Gamma_c, & \quad\mathrm{if}\quad r_{so}\leq r<r_{ci}, \\
\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.
Between :math:`r_{si}` and :math:`r_{so}` the polynomial smoothing is
applied in a way that the force and its 1st derivative are continuous
when switching between fine- and coarse-grained potentials (between
:math:`r_{si}` and :math:`r_{so}`) and at the cutoff (between
:math:`r_{ci}` and :math:`r_{co}`). The corresponding polynomial
coefficients :math:`C_{sm}` and :math:`C_{cm}` and shifting constants
:math:`G_{si}`, :math:`G_{so}` and :math:`G_{c}` are computed by LAMMPS
accordingly. To avoid smoothing, the inner switching distance
:math:`r_{si}` parameter should be set equal to the outer switching
distance :math:`r_{so}` parameter (:math:`r_{si}=r_{so}`). Similarly, to
avoid smoothing at the cutoff, inner and outer cutoff parameters should
be equal (:math:`r_{ci}=r_{co}`). Details can be found in
:ref:`(Chaimovich) <Chaimovich2>`.
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.
.. note::
Energy and force resulting from this methodology can be plotted via the
:doc:`pair_write <pair_write>` command to see the effect.
In the implementation of the *lj/relres* pair style, atoms are grouped
in a way that one of the atoms in a group plays the role of a
coarse-grained site for the calculation of interactions beyond the
:math:`r_{so}` distance while continuing to be a fine-grained site for
shorter distances. This atom must be defined as a different atom
type. Other atoms in the group participate in the fine-grained
interactions only.
: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
@ -85,21 +78,137 @@ commands, or by mixing as will be described below:
* :math:`\epsilon^{CG}` (energy units)
* :math:`\sigma^{CG}` (distance units)
For atom types that are used as fine-grained sites only, :math:`\epsilon^{CG}` must be set to 0 (zero).
For atom types that are used as coarse-grained sites only (if any), :math:`\epsilon^{FG}` must be set to 0 (zero).
Additional parameters can be defined to specify different :math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`, :math:`r_{co}` for a particular set of atom types:
Additional parameters can be defined to specify different
:math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`, :math:`r_{co}` for
a particular set of atom types:
* :math:`r_{si}` (distance units)
* :math:`r_{so}` (distance units)
* :math:`r_{ci}` (distance units)
* :math:`r_{co}` (distance units)
These parameters are optional and they are used to override global
cutoff values as defined in the pair_style command. If this override
option is used, all four values must be specified. If not specified,
the global values for :math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`,
and :math:`r_{co}` are used.
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.
----------
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
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.
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 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
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}}
\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}
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`.
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}`).
----------
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,
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
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
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
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
system from the previous example, we recommend using the following commands:
.. code-block:: LAMMPS
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 2 epsilon_FG12 sigma_FG12 0.0 0.0 Rsi1 Rso1 Rci Rco
pair_coeff 1 3 epsilon_FG13 sigma_FG13 epsilon_CG13 sigma_CG13 Rsi13 Rso13 Rci Rco
pair_coeff 1 4 epsilon_FG14 sigma_FG14 0.0 0.0 Rsi13 Rso13 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 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
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.
----------
@ -110,19 +219,20 @@ and :math:`r_{co}` are used.
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
For atom type pairs I,J with 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.
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:`G_{c}`
is set to zero. Constants :math:`G_{si}` and :math:`G_{so}` are not
impacted by this option.
this option to *yes*\ . Otherwise, the shifting constant :math:`\Gamma_{c}`
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
for this pair style.
@ -160,11 +270,11 @@ none
.. _Chaimovich1:
**(Chaimovich at al.)** A.Chaimovich, C. Peter and K. Kremer, J. Chem. Phys. 143, 243107
(2015).
**(Chaimovich1)** A.Chaimovich, C. Peter and K. Kremer, J. Chem. Phys. 143,
243107 (2015).
.. _Chaimovich2:
**(Chaimovich)** M.Chaimovich and A. Chaimovich, J. Chem. Theory Comput. 17, 1045-1059
(2021).
**(Chaimovich2)** M.Chaimovich and A. Chaimovich, J. Chem. Theory Comput. 17,
1045-1059 (2021).

File diff suppressed because it is too large Load Diff

View File

@ -1,11 +1,16 @@
The input script in.22DMH.relres provide example of simulation using
Relative Resolution (RelRes) potential. In this example 2,2-Dimethylhexane
is selected as simulated substance to give complete view of the RelRes
utilization.
This script uses data file Data.22DMH.in.relres consisting of 8000 molecules.
It also generates RelRes potential for selected atom types.
The input script in.22DMH.respa demonstrates the use of the lj/relres pair
style with r-RESPA using multi-timestepping between FG and CG sites using
a hybrid pair style configuration.
The input script in.22DMH.relres provides an example of a molecular
simulation using the Relative Resolution (RelRes) algorithm. In this
example, 2,2-Dimethylhexane is the molecule in focus. This script
uses the data file Data.22DMH.in.relres, which consists of 8000
molecules. It also generates the RelRes potential for the selected atom types.
The input script in.22DMH.respa demonstrates the use of the lj/relres pair
style with r-RESPA applying multi-timestepping between the appropriate atom
types (using a hybrid pair style configuration).
The input script in.22DMH.real demonstrates the use of the lj/relres pair
style with real units (the data file Data.22DMH.in.real). It performs
a set of molecular simulations with different switching distances. Finally,
it performs a molecular simulation with the lj/smooth pair style, allowing
comparison of the thermal characteristics and the running time between the
RelRes and the conventional approach.

View File

@ -0,0 +1,109 @@
# Example: use of lj/relres for simulation of 2,2-dimethylhexane: C3H7-C5H11
# with various Rso setting as well as run of reference system for time comparison (real units)
# The first run writes restart file that is used by all subsequent runs.
# Run relres with Rso=6.25
units real
atom_style molecular
boundary p p p
dielectric 1
special_bonds lj/coul 0.0 0.0 0.5
bond_style harmonic
angle_style harmonic
dihedral_style fourier
pair_style lj/relres 5.75 6.25 12.0 14.0
read_data Data.22DMH.in.real
pair_coeff 6 6 0.175 3.905 0.0 0.0
pair_coeff 4 4 0.118 3.905 0.0 0.0
pair_coeff 2 2 0.118 3.905 1.2218 3.905
pair_coeff 5 5 0.145 3.960 0.0 0.0
pair_coeff 3 3 0.118 3.905 0.0 0.0
pair_coeff 1 1 0.05 3.8 2.9128 3.9309
pair_modify shift yes
neighbor 2.0 bin
neigh_modify every 2 delay 4 check yes
timestep 1.0
thermo 100
thermo_style custom step temp press pe ke etotal epair emol vol
fix 2 all nvt temp 290 290 2.0e+02
run 1000
write_restart restart.relres.real
# Run relres with Rso=7.25
clear
read_restart restart.relres.real
pair_style lj/relres 6.75 7.25 12.0 14.0
pair_coeff 6 6 0.175 3.905 0.0 0.0
pair_coeff 4 4 0.118 3.905 0.0 0.0
pair_coeff 2 2 0.118 3.905 1.2218 3.905
pair_coeff 5 5 0.145 3.960 0.0 0.0
pair_coeff 3 3 0.118 3.905 0.0 0.0
pair_coeff 1 1 0.05 3.8 2.9128 3.9309
pair_modify shift yes
neighbor 2.0 bin
neigh_modify every 2 delay 4 check yes
timestep 1.0
thermo 100
thermo_style custom step temp press pe ke etotal epair emol vol
fix 2 all nvt temp 290 290 2.0e+02
run 1000
# Run relres with mixed Rso: 6.25 for C3H7 group and 7.25 for C5H11 group
clear
read_restart restart.relres.real
pair_style lj/relres 6.75 7.25 12.0 14.0
pair_coeff 6 6 0.175 3.905 0.0 0.0 5.75 6.25 12.0 14.0
pair_coeff 4 4 0.118 3.905 0.0 0.0 5.75 6.25 12.0 14.0
pair_coeff 2 2 0.118 3.905 1.2218 3.905 5.75 6.25 12.0 14.0
pair_coeff 5 5 0.145 3.960 0.0 0.0
pair_coeff 3 3 0.118 3.905 0.0 0.0
pair_coeff 1 1 0.05 3.8 2.9128 3.9309
pair_modify shift yes
neighbor 2.0 bin
neigh_modify every 2 delay 4 check yes
timestep 1.0
thermo 100
thermo_style custom step temp press pe ke etotal epair emol vol
fix 2 all nvt temp 290 290 2.0e+02
run 1000
# Run reference system with lj/smooth
clear
read_restart restart.relres.real
pair_style lj/smooth 12.0 14.0
pair_coeff 6 6 0.175 3.905
pair_coeff 4 4 0.118 3.905
pair_coeff 2 2 0.118 3.905
pair_coeff 5 5 0.145 3.960
pair_coeff 3 3 0.118 3.905
pair_coeff 1 1 0.05 3.8
pair_modify shift yes
neighbor 2.0 bin
neigh_modify every 2 delay 4 check yes
timestep 1.0
thermo 100
thermo_style custom step temp press pe ke etotal epair emol vol
fix 2 all nvt temp 290 290 2.0e+02
run 1000

View File

@ -1,3 +1,6 @@
# Example: use of lj/relres for simulation of 2,2-dimethylhexane: C3H7-C5H11
# with with mixed Rso: 0.625e-9 for C3H7 group and 0.725e-9 for C5H11 group (si units)
units si
atom_style molecular
boundary p p p
@ -9,11 +12,11 @@ bond_style harmonic
angle_style harmonic
dihedral_style fourier
read_data Data.22DMH.in.relres
pair_coeff 6 6 1.21585e-21 0.3905e-9 0 0.3905e-9 0.575e-9 0.625e-9 1.2e-9 1.4e-9
pair_coeff 4 4 0.819828e-21 0.3905e-9 0 0.3905e-9 0.575e-9 0.625e-9 1.2e-9 1.4e-9
pair_coeff 2 2 0.819828e-21 0.3905e-9 8.48872E-21 0.3905E-9 0.575e-9 0.625e-9 1.2e-9 1.4e-9
pair_coeff 5 5 1.00742E-21 0.396E-9 0 0.396E-9
pair_coeff 3 3 0.819828e-21 0.3905e-9 0 0.3905e-9
pair_coeff 6 6 1.21585e-21 0.3905e-9 0.0 0.0 0.575e-9 0.625e-9 1.2e-9 1.4e-9
pair_coeff 4 4 0.819828e-21 0.3905e-9 0.0 0.0 0.575e-9 0.625e-9 1.2e-9 1.4e-9
pair_coeff 2 2 0.819828e-21 0.3905e-9 8.48872E-21 0.3905E-9 0.575e-9 0.625e-9 1.2e-9 1.4e-9
pair_coeff 5 5 1.00742E-21 0.396E-9 0.0 0.0
pair_coeff 3 3 0.819828e-21 0.3905e-9 0.0 0.0
pair_coeff 1 1 0.347385E-21 0.38E-9 20.2372E-21 0.39309E-9
pair_modify shift yes
neighbor 2.0e-10 bin