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

Merge branch 'master' into doc-continued-refactoring

Browse Source 
# Conflicts:
#	doc/src/compute_fep.rst
This commit is contained in:
Axel Kohlmeyer
2020-02-17 17:37:10 +01:00
parent b30670d405 c8561ecef0
commit f69c6196a0
21 changed files with 589 additions and 255 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/src/Build_extras.rst
View File

@ -880,6 +880,9 @@ USER-PLUMED package
Before building LAMMPS with this package, you must first build PLUMED.
PLUMED can be built as part of the LAMMPS build or installed separately
from LAMMPS using the generic `plumed installation instructions <plumedinstall_>`_.
The USER-PLUMED package has been tested to work with Plumed versions
2.4.x, 2.5.x, and 2.6.x and will error out, when trying to run calculations
with a different version of the Plumed kernel.
PLUMED can be linked into MD codes in three different modes: static,

BIN
doc/src/Eqs/pair_coul_soft.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 11 KiB

10
doc/src/Eqs/pair_coul_soft.tex
View File

@ -1,10 +0,0 @@
\documentstyle[12pt]{article}
\begin{document}
\[
E = \lambda^n \frac{ C q_i q_j}{\epsilon
\left[ \alpha_{\mathrm{C}} (1-\lambda)^2 + r^2 \right]^{1/2}} \qquad r < r_c
\]
\end{document}

BIN
doc/src/Eqs/pair_lj_soft.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 18 KiB

15
doc/src/Eqs/pair_lj_soft.tex
View File

@ -1,15 +0,0 @@
\documentstyle[12pt]{article}
\begin{document}
\[
E = \lambda^n 4 \epsilon
\left\{
\frac{1}{ \left[ \alpha_{\mathrm{LJ}} (1-\lambda)^2 +
\left( \displaystyle\frac{r}{\sigma} \right)^6 \right]^2 } -
\frac{1}{ \alpha_{\mathrm{LJ}} (1-\lambda)^2 +
\left( \displaystyle\frac{r}{\sigma} \right)^6 }
\right\} \qquad r < r_c
\]
\end{document}

BIN
doc/src/Eqs/pair_morse_soft.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

13
doc/src/Eqs/pair_morse_soft.tex
View File

@ -1,13 +0,0 @@
\documentclass[12pt]{article}
\usepackage{amsmath}
\begin{document}
\begin{align*}
s(\lambda) =& (1 - \lambda) / (1 - \lambda_f), \qquad B = -2D e^{-2 \alpha r_0} (e^{\alpha r_0} - 1) / 3 \\
E =& D_0 \left[ e^{- 2 \alpha (r - r_0)} - 2 e^{- \alpha (r - r_0)} \right] + s(\lambda) B e^{-3\alpha(r-r_0)}, \qquad \hspace{2.85em}\lambda \geq \lambda_f,\quad r < r_c \\
E =& \left( D_0 \left[ e^{- 2 \alpha (r - r_0)} - 2 e^{- \alpha (r - r_0)} \right] + B e^{-3\alpha(r-r_0)} \right)(\lambda/\lambda_f)^n, \qquad \lambda < \lambda_f,\quad r < r_c
\end{align*}
\end{document}

BIN
doc/src/Eqs/pair_nm.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.2 KiB

10
doc/src/Eqs/pair_nm.tex
View File

@ -1,10 +0,0 @@
\documentstyle[12pt]{article}
\begin{document}
$$
E = \frac{E_0}{(n-m)} \left[ m \left(\frac{r_0}{r}\right)^n -
n \left(\frac{r_0}{r}\right)^m \right] \qquad r < r_c
$$
\end{document}

25
doc/src/Install_linux.rst
View File

@ -8,8 +8,8 @@ Binaries are available for different versions of Linux:
| :ref:`Pre-built EPEL Linux executables (RHEL, CentOS) <epel>`
| :ref:`Pre-built OpenSuse Linux executables <opensuse>`
| :ref:`Gentoo Linux executable <gentoo>`
| :ref:`Arch Linux build-script <arch>`
|
| :ref:`Arch Linux build-script <arch>`
|
----------
@ -132,11 +132,21 @@ mirrors. The "module load" command is needed once per (shell) session
or shell terminal instance, unless it is automatically loaded from the
shell profile.
The LAMMPS binary is built with the :ref:`KIM package <kim>` which
results in the above command also installing the `kim-api` binaries when LAMMPS
is installed. In order to use potentials from `openkim.org <openkim_>`_, you
can install the `openkim-models` package
.. parsed-literal::
dnf install openkim-models
Please use "lmp -help" to see which compilation options, packages,
and styles are included in the binary.
Thanks to Christoph Junghans (LANL) for making LAMMPS available in Fedora.
.. _openkim: https://openkim.org
----------
@ -146,7 +156,7 @@ Thanks to Christoph Junghans (LANL) for making LAMMPS available in Fedora.
Pre-built EPEL Linux executable
------------------------------------------
Pre-built LAMMPS packages for stable releases are available
Pre-built LAMMPS (and KIM) packages for stable releases are available
in the `Extra Packages for Enterprise Linux (EPEL) repository <https://fedoraproject.org/wiki/EPEL>`_
for use with Red Hat Enterprise Linux (RHEL) or CentOS version 7.x
and compatible Linux distributions. Names of packages, executable,
@ -187,6 +197,15 @@ is *lmp*\ . Thus to run an input in parallel on 2 CPUs you would do:
Please use "lmp -help" to see which compilation options, packages,
and styles are included in the binary.
The LAMMPS binary is built with the :ref:`KIM package <kim>` which
results in the above command also installing the `kim-api` binaries when LAMMPS
is installed. In order to use potentials from `openkim.org <openkim_>`_, you
can install the `openkim-models` package
.. parsed-literal::
zypper install openkim-models
Thanks to Christoph Junghans (LANL) for making LAMMPS available in OpenSuse.

38
doc/src/compute_fep.rst
View File

@ -79,9 +79,8 @@ reference and perturbed systems:
.. math::
\lambda = 0 \quad\Rightarrow\quad U = U_{\mathrm{bg}} + U_0 \\
\lambda = 1 \quad\Rightarrow\quad U = U_{\mathrm{bg}} + U_1
\lambda &= 0 \quad\Rightarrow\quad U = U_{\mathrm{bg}} + U_0 \\
\lambda &= 1 \quad\Rightarrow\quad U = U_{\mathrm{bg}} + U_1
It is possible but not necessary that the coupling parameter (or a
function thereof) appears as a multiplication factor of the potential
@ -95,9 +94,9 @@ stepwise alchemical transformations during a simulation run:
.. math::
\Delta_0^1 A = \sum_{i=0}^{n-1} \Delta_{\lambda_i}^{\lambda_{i+1}} A =
- kT \sum_{i=0}^{n-1} \ln \left< \exp \left( - \frac{U(\lambda_{i+1}) -
U(\lambda_i)}{kT} \right) \right>_{\lambda_i}
\Delta_0^1 A = \sum_{i=0}^{n-1} \Delta_{\lambda_i}^{\lambda_{i+1}} A = - kT
\sum_{i=0}^{n-1} \ln \left< \exp \left( - \frac{U(\lambda_{i+1}) -
U(\lambda_i)}{kT} \right) \right>_{\lambda_i}
This compute is suitable for the finite-difference thermodynamic
integration (FDTI) method :ref:`(Mezei) <Mezei>`, which is based on an
@ -107,9 +106,8 @@ perturbation method using a very small :math:`\delta`:
.. math::
\Delta_0^1 A = \int_{\lambda=0}^{\lambda=1} \left( \frac{\partial
A(\lambda)}{\partial\lambda} \right)_\lambda \mathrm{d}\lambda
\approx \sum_{i=0}^{n-1} w_i \frac{A(\lambda_{i} + \delta) -
A(\lambda_i)}{\delta}
A(\lambda)}{\partial\lambda} \right)_\lambda \mathrm{d}\lambda \approx
\sum_{i=0}^{n-1} w_i \frac{A(\lambda_{i} + \delta) - A(\lambda_i)}{\delta}
where :math:`w_i` are weights of a numerical quadrature. The :doc:`fix adapt <fix_adapt>` command can be used to define the stages of
:math:`\lambda` at which the derivative is calculated and averaged.
@ -123,12 +121,10 @@ the derivative of the potential energy with respect to :math:`\lambda`:
.. math::
\Delta_0^1 A = \int_{\lambda=0}^{\lambda=1} \left< \frac{\partial
U(\lambda)}{\partial\lambda} \right>_\lambda \mathrm{d}\lambda
\approx \sum_{i=0}^{n-1} w_i \left< \frac{U(\lambda_{i} + \delta) -
U(\lambda)}{\partial\lambda} \right>_\lambda \mathrm{d}\lambda \approx
\sum_{i=0}^{n-1} w_i \left< \frac{U(\lambda_{i} + \delta) -
U(\lambda_i)}{\delta} \right>_{\lambda_i}
Another technique to calculate free energy differences is the
acceptance ratio method :ref:`(Bennet) <Bennet>`, which can be implemented
by calculating the potential energy differences with :math:`\delta` = 1.0 on
@ -136,7 +132,9 @@ both the forward and reverse routes:
.. math::
\left< \frac{1}{1 + \exp\left[\left(U_1 - U_0 - \Delta_0^1A \right) /kT \right]} \right>_0 = \left< \frac{1}{1 + \exp\left[\left(U_0 - U_1 + \Delta_0^1A \right) /kT \right]} \right>_1
\left< \frac{1}{1 + \exp\left[\left(U_1 - U_0 - \Delta_0^1A \right) /kT
\right]} \right>_0 = \left< \frac{1}{1 + \exp\left[\left(U_0 - U_1 +
\Delta_0^1A \right) /kT \right]} \right>_1
The value of the free energy difference is determined by numerical
root finding to establish the equality.
@ -287,7 +285,7 @@ trajectories during which the volume fluctuates or changes :ref:`(Allen and Tild
\Delta_0^1 A = - kT \sum_{i=0}^{n-1} \ln \frac{\left< V \exp \left( -
\frac{U(\lambda_{i+1}) - U(\lambda_i)}{kT} \right)
\right>_{\lambda_i}}{\left< V \right>_{\lambda_i}}
\right>_{\lambda_i}}{\left< V \right>_{\lambda_i}}
----------
@ -334,31 +332,21 @@ The option defaults are *tail* = *no*\ , *volume* = *no*\ .
.. _Pearlman:
**(Pearlman)** Pearlman, J Chem Phys, 98, 1487 (1994)
.. _Mezei:
**(Mezei)** Mezei, J Chem Phys, 86, 7084 (1987)
.. _Bennet:
**(Bennet)** Bennet, J Comput Phys, 22, 245 (1976)
.. _BoreschKarplus:
**(BoreschKarplus)** Boresch and Karplus, J Phys Chem A, 103, 103 (1999)
.. _AllenTildesley:
**(AllenTildesley)** Allen and Tildesley, Computer Simulation of
Liquids, Oxford University Press (1987)

222
doc/src/pair_fep_soft.rst
View File

@ -187,8 +187,14 @@ are suited for "alchemical" free energy calculations using the :doc:`fix adapt/f
The *lj/cut/soft* style and related sub-styles compute the 12-6 Lennard-Jones
and Coulomb potentials modified by a soft core, with the functional form
.. image:: Eqs/pair_lj_soft.jpg
:align: center
.. math::
E = \lambda^n 4 \epsilon \left\{
\frac{1}{ \left[ \alpha_{\mathrm{LJ}} (1-\lambda)^2 +
\left( \displaystyle\frac{r}{\sigma} \right)^6 \right]^2 } -
\frac{1}{ \alpha_{\mathrm{LJ}} (1-\lambda)^2 +
\left( \displaystyle\frac{r}{\sigma} \right)^6 }
\right\} \qquad r < r_c
The *lj/class2/soft* style is a 9-6 potential with the exponent of the
denominator of the first term in brackets taking the value 1.5 instead of 2
@ -197,25 +203,30 @@ denominator of the first term in brackets taking the value 1.5 instead of 2
Coulomb interactions can also be damped with a soft core at short distance,
.. image:: Eqs/pair_coul_soft.jpg
:align: center
.. math::
In the Coulomb part C is an energy-conversion constant, q\_i and q\_j
are the charges on the 2 atoms, and epsilon is the dielectric constant
which can be set by the :doc:`dielectric <dielectric>` command.
E = \lambda^n \frac{ C q_i q_j}{\epsilon \left[ \alpha_{\mathrm{C}}
(1-\lambda)^2 + r^2 \right]^{1/2}} \qquad r < r_c
The coefficient lambda is an activation parameter. When lambda = 1 the pair
potential is identical to a Lennard-Jones term or a Coulomb term or a
combination of both. When lambda = 0 the interactions are deactivated. The
transition between these two extrema is smoothed by a soft repulsive core in
order to avoid singularities in potential energy and forces when sites are
created or annihilated and can overlap :ref:`(Beutler) <Beutler>`.
In the Coulomb part :math:`C` is an energy-conversion constant, :math:`q_i` and
:math:`q_j` are the charges on the 2 atoms, and epsilon is the dielectric
constant which can be set by the :doc:`dielectric <dielectric>` command.
The parameters n, alpha\_LJ and alpha\_C are set in the
:doc:`pair_style <pair_style>` command, before the cutoffs. Usual choices for the
exponent are n = 2 or n = 1. For the remaining coefficients alpha\_LJ = 0.5 and
alpha\_C = 10 Angstrom\^2 are appropriate choices. Plots of the 12/6 LJ and
Coulomb terms are shown below, for lambda ranging from 1 to 0 every 0.1.
The coefficient lambda is an activation parameter. When :math:`\lambda = 1` the
pair potential is identical to a Lennard-Jones term or a Coulomb term or a
combination of both. When :math:`\lambda = 0` the interactions are
deactivated. The transition between these two extrema is smoothed by a soft
repulsive core in order to avoid singularities in potential energy and forces
when sites are created or annihilated and can overlap :ref:`(Beutler)
<Beutler>`.
The parameters :math:`n`, :math:`\alpha_\mathrm{LJ}` and
:math:`\alpha_\mathrm{C}` are set in the :doc:`pair_style <pair_style>` command,
before the cutoffs. Usual choices for the exponent are :math:`n = 2` or
:math:`n = 1`. For the remaining coefficients :math:`\alpha_\mathrm{LJ} = 0.5`
and :math:`\alpha_\mathrm{C} = 10~\text{A}^2` are appropriate choices. Plots of
the 12-6 LJ and Coulomb terms are shown below, for lambda ranging from 1 to 0
every 0.1.
.. image:: JPG/lj_soft.jpg
.. image:: JPG/coul_soft.jpg
@ -225,12 +236,12 @@ For the *lj/cut/coul/cut/soft* or *lj/cut/coul/long/soft* pair styles, as well
as for the equivalent *class2* versions, the following coefficients must be
defined for each pair of atoms 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 described below:
the :doc:`read_data <read_data>` or :doc:`read_restart <read_restart>` commands,
or by mixing as described below:
* epsilon (energy units)
* sigma (distance units)
* lambda (activation parameter, between 0 and 1)
* :math:`\epsilon` (energy units)
* :math:`\sigma` (distance units)
* :math:`\lambda` (activation parameter, between 0 and 1)
* cutoff1 (distance units)
* cutoff2 (distance units)
@ -245,61 +256,62 @@ since it has no Coulombic terms. For the *coul/cut/soft* and
specified.
Style *lj/cut/tip4p/long/soft* implements a soft-core version of the TIP4P water
model. The usage of the TIP4P pair style is documented in the
:doc:`pair_lj <pair_lj>` styles. In the soft version the parameters n, alpha\_LJ
and alpha\_C are set in the :doc:`pair_style <pair_style>` command, after the
specific parameters of the TIP4P water model and before the cutoffs. The
activation parameter lambda is supplied as an argument of the
:doc:`pair_coeff <pair_coeff>` command, after epsilon and sigma and before the
optional cutoffs.
model. The usage of the TIP4P pair style is documented in the :doc:`pair_lj
<pair_lj>` styles. In the soft version the parameters :math:`n`,
:math:`\alpha_\mathrm{LJ}` and :math:`\alpha_\mathrm {C}` are set in the
:doc:`pair_style <pair_style>` command, after the specific parameters of the
TIP4P water model and before the cutoffs. The activation parameter lambda is
supplied as an argument of the :doc:`pair_coeff <pair_coeff>` command, after
epsilon and sigma and before the optional cutoffs.
Style *lj/charmm/coul/long/soft* implements a soft-core version of the modified
12-6 LJ potential used in CHARMM and documented in the
:doc:`pair_style lj/charmm/coul/long <pair_charmm>` style. In the soft version the parameters n,
alpha\_LJ and alpha\_C are set in the :doc:`pair_style <pair_style>` command, before
the global cutoffs. The activation parameter lambda is introduced as an argument
of the :doc:`pair_coeff <pair_coeff>` command, after epsilon and sigma and
before the optional eps14 and sigma14.
12-6 LJ potential used in CHARMM and documented in the :doc:`pair_style
lj/charmm/coul/long <pair_charmm>` style. In the soft version the parameters
:math:`n`, :math:`\alpha_\mathrm{LJ}` and :math:`\alpha_\mathrm{C}` are set in
the :doc:`pair_style <pair_style>` command, before the global cutoffs. The
activation parameter lambda is introduced as an argument of the :doc:`pair_coeff
<pair_coeff>` command, after :math:`\epsilon` and :math:`\sigma` and before the
optional eps14 and sigma14.
Style *lj/class2/soft* implements a soft-core version of the 9-6 potential in
:doc:`pair_style lj/class2 <pair_class2>`. In the soft version the parameters n, alpha\_LJ
and alpha\_C are set in the :doc:`pair_style <pair_style>` command, before the
global cutoffs. The activation parameter lambda is introduced as an argument of
the the :doc:`pair_coeff <pair_coeff>` command, after epsilon and sigma and before
the optional cutoffs.
:doc:`pair_style lj/class2 <pair_class2>`. In the soft version the parameters
:math:`n`, :math:`\alpha_\mathrm{LJ}` and :math:`\alpha_\mathrm{C}` are set in the
:doc:`pair_style <pair_style>` command, before the global cutoffs. The
activation parameter lambda is introduced as an argument of the the
:doc:`pair_coeff <pair_coeff>` command, after :math:`\epsilon` and
:math:`\sigma` and before the optional cutoffs.
The *coul/cut/soft*\ , *coul/long/soft* and *tip4p/long/soft* sub-styles
are designed to be combined with other pair potentials via the
:doc:`pair_style hybrid/overlay <pair_hybrid>` command. This is because
they have no repulsive core. Hence, if used by themselves, there will
be no repulsion to keep two oppositely charged particles from
overlapping each other. In this case, if lambda = 1, a singularity may
occur. These sub-styles are suitable to represent charges embedded in
the Lennard-Jones radius of another site (for example hydrogen atoms
in several water models).
The *coul/cut/soft*\ , *coul/long/soft* and *tip4p/long/soft* sub-styles are
designed to be combined with other pair potentials via the :doc:`pair_style
hybrid/overlay <pair_hybrid>` command. This is because they have no repulsive
core. Hence, if used by themselves, there will be no repulsion to keep two
oppositely charged particles from overlapping each other. In this case, if
:math:`\lambda = 1`, a singularity may occur. These sub-styles are suitable to
represent charges embedded in the Lennard-Jones radius of another site (for
example hydrogen atoms in several water models).
.. note::
When using the soft-core Coulomb potentials with long-range
solvers (\ *coul/long/soft*\ , *lj/cut/coul/long/soft*\ , etc.) in a free
energy calculation in which sites holding electrostatic charges are
being created or annihilated (using :doc:`fix adapt/fep <fix_adapt_fep>`
and :doc:`compute fep <compute_fep>`) it is important to adapt both the
lambda activation parameter (from 0 to 1, or the reverse) and the
value of the charge (from 0 to its final value, or the reverse). This
ensures that long-range electrostatic terms (kspace) are correct. It
is not necessary to use soft-core Coulomb potentials if the van der
Waals site is present during the free-energy route, thus avoiding
overlap of the charges. Examples are provided in the LAMMPS source
directory tree, under examples/USER/fep.
When using the soft-core Coulomb potentials with long-range solvers (\
*coul/long/soft*\ , *lj/cut/coul/long/soft*\ , etc.) in a free energy
calculation in which sites holding electrostatic charges are being created or
annihilated (using :doc:`fix adapt/fep <fix_adapt_fep>` and :doc:`compute fep
<compute_fep>`) it is important to adapt both the :math:`\lambda` activation
parameter (from 0 to 1, or the reverse) and the value of the charge (from 0
to its final value, or the reverse). This ensures that long-range
electrostatic terms (kspace) are correct. It is not necessary to use
soft-core Coulomb potentials if the van der Waals site is present during the
free-energy route, thus avoiding overlap of the charges. Examples are
provided in the LAMMPS source directory tree, under examples/USER/fep.
.. note::
To avoid division by zero do not set sigma = 0 in the *lj/cut/soft* and
related styles; use the lambda parameter instead to activate/deactivate
interactions, or use epsilon = 0 and sigma = 1. Alternatively, when sites do not
interact though the Lennard-Jones term the *coul/long/soft* or similar sub-style
can be used via the :doc:`pair_style hybrid/overlay <pair_hybrid>` command.
To avoid division by zero do not set :math:`\sigma = 0` in the *lj/cut/soft*
and related styles; use the lambda parameter instead to activate/deactivate
interactions, or use :math:`\epsilon = 0` and :math:`\sigma = 1`.
Alternatively, when sites do not interact though the Lennard-Jones term
the *coul/long/soft* or similar sub-style can be used via the
:doc:`pair_style hybrid/overlay <pair_hybrid>` command.
----------
@ -309,15 +321,25 @@ The *morse/soft* variant modifies the :doc:`pair_morse <pair_morse>` style at
short range to have a soft core. The functional form differs from that of the
*lj/soft* styles, and is instead given by:
.. image:: Eqs/pair_morse_soft.jpg
:align: center
.. math::
\begin{split}
s(\lambda) =& (1 - \lambda) / (1 - \lambda_f), \qquad B = -2D e^{-2 \alpha
r_0} (e^{\alpha r_0} - 1) / 3 \\
E =& D_0 \left[ e^{- 2 \alpha (r - r_0)} - 2 e^{- \alpha (r - r_0)} \right] +
s(\lambda) B e^{-3\alpha(r-r_0)}, \qquad \hspace{2.85em}\lambda \geq
\lambda_f,\quad r < r_c \\
E =& \left( D_0 \left[ e^{- 2 \alpha (r - r_0)} - 2 e^{- \alpha (r - r_0)}
\right] + B e^{-3\alpha(r-r_0)} \right)(\lambda/\lambda_f)^n, \qquad \lambda
< \lambda_f,\quad r < r_c
\end{split}
The *morse/soft* style requires the following pair coefficients:
* D0 (energy units)
* alpha (1/distance units)
* r0 (distance units)
* lambda (unitless, between 0.0 and 1.0)
* :math:`D_0` (energy units)
* :math:`\alpha` (1/distance units)
* :math:`r_0` (distance units)
* :math:`\lambda` (unitless, between 0.0 and 1.0)
* cutoff (distance units)
The last coefficient is optional. If not specified, the global morse cutoff is
@ -338,9 +360,10 @@ These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
You can specify the accelerated styles explicitly in your input script by
including their suffix, or you can use the :doc:`-suffix command-line switch
<Run_options>` when you invoke LAMMPS, or you can use the :doc:`suffix <suffix>`
command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
@ -351,16 +374,16 @@ instructions on how to use the accelerated styles effectively.
**Mixing, shift, tail correction, restart info**\ :
The different versions of the *lj/cut/soft* pair styles support mixing. For atom
type pairs I,J and I != J, the epsilon and sigma coefficients and cutoff
distance for these pair style can be mixed. The default mix value is
*geometric* for 12-6 styles.
The different versions of the *lj/cut/soft* pair styles support mixing. For
atom type pairs I,J and I != J, the :math:`\epsilon` and :math:`\sigma`
coefficients and cutoff distance for these pair style can be mixed. The default
mix value is *geometric* for 12-6 styles.
The mixing rule for epsilon and sigma for *lj/class2/soft* 9-6 potentials is to use the
*sixthpower* formulas. The :doc:`pair_modify mix <pair_modify>` setting is thus
ignored for class2 potentials for epsilon and sigma. However it is still
followed for mixing the cutoff distance. See the :doc:`pair_modify <pair_modify>`
command for details.
The mixing rule for epsilon and sigma for *lj/class2/soft* 9-6 potentials is to
use the *sixthpower* formulas. The :doc:`pair_modify mix <pair_modify>` setting
is thus ignored for class2 potentials for :math:`\epsilon` and
:math:`\sigma`. However it is still followed for mixing the cutoff distance. See
the :doc:`pair_modify <pair_modify>` command for details.
The *morse/soft* pair style does not support mixing. Thus, coefficients for all
LJ pairs must be specified explicitly.
@ -376,22 +399,25 @@ interaction.
.. note::
The analytical form of the tail corrections for energy and pressure used
in the *lj/cut/soft* potentials are approximate, being identical to that of the
corresponding non-soft potentials scaled by a factor lambda\^n. The errors due to
this approximation should be negligible. For example, for a cutoff of 2.5 sigma
this approximation leads to maximum relative errors in tail corrections of the
order of 1e-4 for energy and virial (alpha\_LJ = 0.5, n = 2). The error vanishes
when lambda approaches 0 or 1. Note that these are the errors affecting the
long-range tail (itself a correction to the interaction energy) which includes
other approximations, namely that the system is homogeneous (local density equal
The analytical form of the tail corrections for energy and pressure used in
the *lj/cut/soft* potentials are approximate, being identical to that of the
corresponding non-soft potentials scaled by a factor :math:`\lambda^n`. The
errors due to this approximation should be negligible. For example, for a
cutoff of :math:`2.5\sigma` this approximation leads to maximum relative
errors in tail corrections of the order of 1e-4 for energy and virial
(:math:`\alpha_\mathrm{LJ} = 0.5, n = 2`). The error vanishes when lambda
approaches 0 or 1. Note that these are the errors affecting the long-range
tail (itself a correction to the interaction energy) which includes other
approximations, namely that the system is homogeneous (local density equal
the average density) beyond the cutoff.
The *morse/soft* pair style does not support the :doc:`pair_modify <pair_modify>`
tail option for adding long-range tail corrections to energy and pressure.
The *morse/soft* pair style does not support the :doc:`pair_modify
<pair_modify>` tail option for adding long-range tail corrections to energy and
pressure.
All of these pair styles write information to :doc:`binary restart files <restart>`, so pair\_style and pair\_coeff commands do not need to be
specified in an input script that reads a restart file.
All of these pair styles write information to :doc:`binary restart files
<restart>`, so pair\_style and pair\_coeff commands do not need to be specified
in an input script that reads a restart file.
----------

43
doc/src/pair_nm.rst
View File

@ -68,22 +68,25 @@ by :ref:`Clarke <Clarke>`, mainly used for ionic liquids. A site can
represent a single atom or a united-atom site. The energy of an
interaction has the following form:
.. image:: Eqs/pair_nm.jpg
:align: center
.. math::
Rc is the cutoff.
E = \frac{E_0}{(n-m)} \left[ m \left(\frac{r_0}{r}\right)^n - n
\left(\frac{r_0}{r}\right)^m \right] \qquad r < r_c
where :math:`r_c` is the cutoff.
Style *nm/cut/coul/cut* adds a Coulombic pairwise interaction given by
.. image:: Eqs/pair_coulomb.jpg
:align: center
.. math::
where C is an energy-conversion constant, Qi and Qj are the charges on
the 2 atoms, and epsilon is the dielectric constant which can be set
by the :doc:`dielectric <dielectric>` command. If one cutoff is
specified in the pair\_style command, it is used for both the NM and
Coulombic terms. If two cutoffs are specified, they are used as
cutoffs for the NM and Coulombic terms respectively.
E = \frac{C q_i q_j}{\epsilon r} \qquad r < r_c
where :math:`C` is an energy-conversion constant, :math:`q_i` and :math:`q_j`
are the charges on the 2 atoms, and epsilon is the dielectric constant which can
be set by the :doc:`dielectric <dielectric>` command. If one cutoff is
specified in the pair\_style command, it is used for both the N-M and Coulombic
terms. If two cutoffs are specified, they are used as cutoffs for the N-M and
Coulombic terms respectively.
Styles *nm/cut/coul/long* compute the same
Coulombic interactions as style *nm/cut/coul/cut* except that an
@ -101,22 +104,22 @@ 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.
* E0 (energy units)
* r0 (distance units)
* n (unitless)
* m (unitless)
* :math:`E_0` (energy units)
* :math:`r_0` (distance units)
* :math:`n` (unitless)
* :math:`m` (unitless)
* cutoff1 (distance units)
* cutoff2 (distance units)
The latter 2 coefficients are optional. If not specified, the global
NM and Coulombic cutoffs specified in the pair\_style command are used.
If only one cutoff is specified, it is used as the cutoff for both NM
N-M and Coulombic cutoffs specified in the pair\_style command are used.
If only one cutoff is specified, it is used as the cutoff for both N-M
and Coulombic interactions for this type pair. If both coefficients
are specified, they are used as the NM and Coulombic cutoffs for this
are specified, they are used as the N-M and Coulombic cutoffs for this
type pair. You cannot specify 2 cutoffs for style *nm*\ , since it
has no Coulombic terms.
For *nm/cut/coul/long* only the NM cutoff can be specified since a
For *nm/cut/coul/long* only the N-M cutoff can be specified since a
Coulombic cutoff cannot be specified for an individual I,J type pair.
All type pairs use the same global Coulombic cutoff specified in the
pair\_style command.
@ -140,7 +143,7 @@ the short-range portion of the long-range Coulombic interaction.
All of the *nm* pair styles support the :doc:`pair_modify <pair_modify>`
tail option for adding a long-range tail correction to the energy and
pressure for the NM portion of the pair interaction.
pressure for the N-M portion of the pair interaction.
All of the *nm* pair styles write their information to :doc:`binary restart files <restart>`, so pair\_style and pair\_coeff commands do not need
to be specified in an input script that reads a restart file.