diff --git a/doc/src/fix_neb.rst b/doc/src/fix_neb.rst index 0c6d0323d7..8e9ba3939c 100644 --- a/doc/src/fix_neb.rst +++ b/doc/src/fix_neb.rst @@ -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) ` 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) ` 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) ` 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) ` -.. 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 ` 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 ` 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`, 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`, 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) `. +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) +`. 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. diff --git a/doc/src/neb.rst b/doc/src/neb.rst index 1ba1bd1cc2..33c9ac8c27 100644 --- a/doc/src/neb.rst +++ b/doc/src/neb.rst @@ -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) `, -:ref:`(HenkelmanB) `, :ref:`(Nakano) ` and :ref:`(Maras) `. +follows the discussion in these 4 papers: :ref:`(HenkelmanA) +`, :ref:`(HenkelmanB) `, :ref:`(Nakano) +` and :ref:`(Maras) `. 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 `. 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 `. 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 ` 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) ` 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) ` 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.