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

rework neb docs to use .. math:: and :math: in sphinx

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-01-12 22:58:16 -05:00
parent 7ac611b671
commit f27c7a9135
2 changed files with 91 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
doc/src/fix_neb.rst
View File

@ -60,37 +60,37 @@ replica having the highest energy relaxes toward the saddle point
relaxation is performed.
A key purpose of the nudging forces is to keep the replicas equally
spaced. During the NEB calculation, the 3N-length vector of
interatomic force Fi = -Grad(V) for each replica I is altered. For
all intermediate replicas (i.e. for 1 < I < N, except the climbing
replica) the force vector becomes:
spaced. During the NEB calculation, the :math:`3N`-length vector of
interatomic force :math:`F_i = -\nabla V` for each replica *i* is
altered. For all intermediate replicas (i.e. for :math:`1 < i < N`,
except the climbing replica) the force vector becomes:
.. parsed-literal::
.. math::
Fi = -Grad(V) + (Grad(V) dot T') T' + Fnudge_parallel + Fnudge_perp
F_i = -\nabla V + (\nabla V \cdot T') T' + F_\parallel + F_\perp
T' is the unit "tangent" vector for replica I and is a function of Ri,
Ri-1, Ri+1, and the potential energy of the 3 replicas; it points
roughly in the direction of (Ri+i - Ri-1); see the
:ref:`(Henkelman1) <Henkelman1>` paper for details. Ri are the atomic
coordinates of replica I; Ri-1 and Ri+1 are the coordinates of its
neighbor replicas. The term (Grad(V) dot T') is used to remove the
component of the gradient parallel to the path which would tend to
distribute the replica unevenly along the path. Fnudge_parallel is an
artificial nudging force which is applied only in the tangent
direction and which maintains the equal spacing between replicas (see
below for more information). Fnudge_perp is an optional artificial
spring which is applied in a direction perpendicular to the tangent
direction and which prevent the paths from forming acute kinks (see
below for more information).
T' is the unit "tangent" vector for replica *i* and is a function of
:math:`R_i, R_{i-1}, R_{i+1}`, and the potential energy of the 3
replicas; it points roughly in the direction of :math:`R_{i+i} -
R_{i-1}`; see the :ref:`(Henkelman1) <Henkelman1>` paper for details.
:math:`R_i` are the atomic coordinates of replica *i*; :math:`R_{i-1}`
and :math:`R_{i+1}` are the coordinates of its neighbor replicas. The
term :math:`\nabla V \cdot T'` is used to remove the component of the
gradient parallel to the path which would tend to distribute the replica
unevenly along the path. :math:`F_\parallel` is an artificial nudging
force which is applied only in the tangent direction and which maintains
the equal spacing between replicas (see below for more information).
:math:`F_\perp` is an optional artificial spring which is applied in a
direction perpendicular to the tangent direction and which prevent the
paths from forming acute kinks (see below for more information).
In the second stage of the NEB calculation, the interatomic force Fi
In the second stage of the NEB calculation, the interatomic force :math:`F_i`
for the climbing replica (the replica of highest energy after the
first stage) is changed to:
.. parsed-literal::
.. math::
Fi = -Grad(V) + 2 (Grad(V) dot T') T' + Fnudge_perp
F_i = -\nabla V + 2 (\nabla V \cdot T') T' + F_\perp
and the relaxation procedure is continued to a new converged MEP.
@ -101,26 +101,26 @@ computed. With a value of *neigh*, the parallel nudging force is
computed as in :ref:`(Henkelman1) <Henkelman1>` by connecting each
intermediate replica with the previous and the next image:
.. parsed-literal::
.. math::
Fnudge_parallel = *Kspring* \* (\|Ri+1 - Ri\| - \|Ri - Ri-1\|)
F_\parallel = Kspring \cdot \left(\left|R_{i+1} - R_i\right| - \left|R_i - R_{i-1}\right|\right)
Note that in this case the specified *Kspring* is in force/distance
units.
Note that in this case the specified *Kspring* is in
force/distance units.
With a value of *ideal*, the spring force is computed as suggested in
ref`(WeinanE) <WeinanE>`
.. parsed-literal::
.. math::
Fnudge_parallel = -\ *Kspring* \* (RD-RDideal) / (2 \* meanDist)
F_\parallel = -Kspring \cdot (RD - RD_{ideal}) / (2 \cdot meanDist)
where RD is the "reaction coordinate" see :doc:`neb <neb>` section, and
RDideal is the ideal RD for which all the images are equally spaced.
I.e. RDideal = (I-1)\*meanDist when the climbing replica is off, where
I is the replica number). The meanDist is the average distance
between replicas. Note that in this case the specified *Kspring* is
in force units.
where *RD* is the "reaction coordinate" see :doc:`neb <neb>` section,
and :math:`RD_{ideal}` is the ideal *RD* for which all the images are
equally spaced. I.e. :math:`RD_{ideal} = (i-1) \cdot meanDist` when the
climbing replica is off, where *i* is the replica number). The
*meanDist* is the average distance between replicas. Note that in this
case the specified *Kspring* is in force units.
Note that the *ideal* form of nudging can often be more effective at
keeping the replicas equally spaced.
@ -129,15 +129,20 @@ With a value of *equal* the spring force is computed as for *ideal*
before the climbing stage, then is computed to promote equidistant
spacing in energy rather than distance:
.. parsed-literal::
Fnudge_parallel = -\ *Kspring* \* (ED-EDideal) / (2 \* meanEDist)
.. math::
where ED is the cumulative sum of absolute energy differences
ED=sum(i<I)\|E(Ri+1)-E(Ri)\|, EDideal = (I-1)\*meanEdist
and meanEdist is the average absolute energy difference between replicas.
This form of nudging is to aid schemes which integrate forces along
NEB pathways such as :doc:`fix_pafi <fix_pafi>`, by providing optimal
quadrature points.
F_\parallel = -Kspring \cdot (ED - ED_{ideal}) / (2 \cdot meanEDist)
where *ED* is the cumulative sum of absolute energy differences:
.. math::
ED = \sum_{i<N} \left|E(R_{i+1}) - E(R_i)\right|, \qquad ED_{ideal} = (N-1) \cdot meanEdist
and *meanEdist* is the average absolute energy difference between
replicas. This form of nudging is to aid schemes which integrate forces
along NEB pathways such as :doc:`fix_pafi <fix_pafi>`, by providing
optimal quadrature points.
----------
@ -150,14 +155,16 @@ resolution is poor. I.e. when few replicas are used; see
The perpendicular spring force is given by
.. parsed-literal::
.. math::
Fnudge_perp = *Kspring2* \* F(Ri-1,Ri,Ri+1) (Ri+1 + Ri-1 - 2 Ri)
F_\perp = K_{spring2} \cdot F(R_{i-1},R_i,R_{i+1}) (R_{i+1} + R_{i-1} - 2 R_i)
where *Kspring2* is the specified value. F(Ri-1 Ri R+1) is a smooth
scalar function of the angle Ri-1 Ri Ri+1. It is equal to 0.0 when
the path is straight and is equal to 1 when the angle Ri-1 Ri Ri+1 is
acute. F(Ri-1 Ri R+1) is defined in :ref:`(Jonsson) <Jonsson>`.
where *Kspring2* is the specified value. :math:`F(R_{i-1}, R_i,
R_{i+1})` is a smooth scalar function of the angle :math:`R_{i-1} R_i
R_{i+1}`. It is equal to 0.0 when the path is straight and is equal to
1 when the angle :math:`R_{i-1} R_i R_{i+1}` is acute.
:math:`F(R_{i-1}, R_i, R_{i+1})` is defined in :ref:`(Jonsson)
<Jonsson>`.
If *Kspring2* is set to 0.0 (the default) then no perpendicular spring
force is added.
@ -171,12 +178,13 @@ forces can be applied to the first and/or last replicas, to enable
them to relax toward a MEP while constraining their energy E to the
target energy ETarget.
If ETarget>E, the interatomic force Fi for the specified replica becomes:
If :math:`E_{Target} > E`, the interatomic force :math:`F_i` for the
specified replica becomes:
.. parsed-literal::
.. math::
Fi = -Grad(V) + (Grad(V) dot T' + (E-ETarget)\*Kspring3) T', *when* Grad(V) dot T' < 0
Fi = -Grad(V) + (Grad(V) dot T' + (ETarget- E)\*Kspring3) T', *when* Grad(V) dot T' > 0
F_i & = -\nabla V + (\nabla V \cdot T' + (E - E_{Target}) \cdot K_{spring3}) T', \qquad \textrm{when} \quad \nabla V \cdot T' < 0 \\
F_i & = -\nabla V + (\nabla V \cdot T' + (E_{Target} - E) \cdot K_{spring3}) T', \qquad \textrm{when} \quad \nabla V \cdot T' > 0
The "spring" constant on the difference in energies is the specified
*Kspring3* value.

57
doc/src/neb.rst
View File

@ -29,7 +29,7 @@ Syntax
*none* arg = no argument all replicas assumed to already have
their initial coords
keyword = *verbose* or *terse*
* keyword = *verbose* or *terse*
Examples
""""""""
@ -47,19 +47,21 @@ Perform a nudged elastic band (NEB) calculation using multiple
replicas of a system. Two or more replicas must be used; the first
and last are the end points of the transition path.
NEB is a method for finding both the atomic configurations and height
of the energy barrier associated with a transition state, e.g. for an
atom to perform a diffusive hop from one energy basin to another in a
NEB is a method for finding both the atomic configurations and height of
the energy barrier associated with a transition state, e.g. for an atom
to perform a diffusive hop from one energy basin to another in a
coordinated fashion with its neighbors. The implementation in LAMMPS
follows the discussion in these 4 papers: :ref:`(HenkelmanA) <HenkelmanA>`,
:ref:`(HenkelmanB) <HenkelmanB>`, :ref:`(Nakano) <Nakano3>` and :ref:`(Maras) <Maras2>`.
follows the discussion in these 4 papers: :ref:`(HenkelmanA)
<HenkelmanA>`, :ref:`(HenkelmanB) <HenkelmanB>`, :ref:`(Nakano)
<Nakano3>` and :ref:`(Maras) <Maras2>`.
Each replica runs on a partition of one or more processors. Processor
partitions are defined at run-time using the :doc:`-partition command-line switch <Run_options>`. Note that if you have MPI installed, you
can run a multi-replica simulation with more replicas (partitions)
than you have physical processors, e.g you can run a 10-replica
simulation on just one or two processors. You will simply not get the
performance speed-up you would see with one or more physical
partitions are defined at run-time using the :doc:`-partition
command-line switch <Run_options>`. Note that if you have MPI
installed, you can run a multi-replica simulation with more replicas
(partitions) than you have physical processors, e.g you can run a
10-replica simulation on just one or two processors. You will simply
not get the performance speed-up you would see with one or more physical
processors per replica. See the :doc:`Howto replica <Howto_replica>`
doc page for further discussion.
@ -330,25 +332,26 @@ the fix neb command.
The forward (reverse) energy barrier is the potential energy of the
highest replica minus the energy of the first (last) replica.
Supplementary information for all replicas can be printed out to the
screen and master log.lammps file by adding the verbose keyword. This
information include the following. The "path angle" (pathangle) for
the replica i which is the angle between the 3N-length vectors (Ri-1 -
Ri) and (Ri+1 - Ri) (where Ri is the atomic coordinates of replica
i). A "path angle" of 180 indicates that replicas i-1, i and i+1 are
Supplementary information for all replicas can be printed out by adding
the *verbose* keyword. This information include the following. The
"path angle" (pathangle) for the replica i which is the angle between
the 3N-length vectors :math:`(R_{i-1} - R_i)` and :math:`(R_{i+1} -
R_i)` (where :math:`R_i` is the atomic coordinates of replica *i*). A
"path angle" of 180 indicates that replicas *i*-1, *i* and *i*+1 are
aligned. "angletangrad" is the angle between the 3N-length tangent
vector and the 3N-length force vector at image i. The tangent vector
is calculated as in :ref:`(HenkelmanA) <HenkelmanA>` for all intermediate
replicas and at R2 - R1 and RM - RM-1 for the first and last replica,
respectively. "anglegrad" is the angle between the 3N-length energy
gradient vector of replica i and that of replica i+1. It is not
defined for the final replica and reads nan. gradV is the norm of the
energy gradient of image i. ReplicaForce is the two-norm of the
3N-length force vector (including nudging forces) for replica i.
MaxAtomForce is the maximum force component of any atom in replica i.
vector and the 3N-length force vector at image *i*. The tangent vector
is calculated as in :ref:`(HenkelmanA) <HenkelmanA>` for all
intermediate replicas and at R2 - R1 and RM - RM-1 for the first and
last replica, respectively. "anglegrad" is the angle between the
3N-length energy gradient vector of replica *i* and that of replica
*i*+1. It is not defined for the final replica and reads nan. gradV is
the norm of the energy gradient of image *i* (:math:`\nabla V`).
ReplicaForce is the two-norm of the 3N-length force vector (including
nudging forces) for replica *i*. MaxAtomForce is the maximum force
component of any atom in replica *i*.
Alternatively, a restricted print out can be obtained by adding the
terse keyword, which omits per-replica information. This typically
*terse* keyword, which omits per-replica information. This typically
fits on one line of a command terminal, aiding visual inspection of
an ongoing NEB calculation.