NEB routine to target equal energy difference between knots

[tomswinburne]

Summary

NEB 'ideal' aims to give equidistant knots; this PR implements a NEB style 'equal' which aims to give knots equidistant in energy. From the proposed fix_neb.rst:

With a value of ideal, the spring force is computed as suggested in ref(WeinanE) <WeinanE>

Fnudge_parallel = -Kspring * (RD-RDideal) / (2 * 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.

Note that the ideal form of nudging can often be more effective at keeping the replicas equally spaced.

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:

Fnudge_parallel = -Kspring * (ED-EDideal) / (2 * meanEDist)

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.

Related Issue(s)

Author(s)
Tom D Swinburne, CNRS / Aix-Marseille University, thomas.swinburne at cnrs.fr

Licensing

By submitting this pull request, I agree, that my contribution will be included in LAMMPS and redistributed under either the GNU General Public License version 2 (GPL v2) or the GNU Lesser General Public License version 2.1 (LGPL v2.1).

Backward Compatibility
no

Implementation Notes
Fully checked in lammps, minimal changes to code

Post Submission Checklist

• The feature or features in this pull request is complete
• Licensing information is [complete]
• Corresponding author information is complete
• The source code follows the LAMMPS formatting guidelines
• Suitable new documentation files and/or updates to the existing docs are included
• The added/updated documentation is integrated and tested with the documentation build system
• The feature has been verified to work with the conventional build system
• The feature has been verified to work with the CMake based build system
• Suitable tests have been added to the unittest tree.
• A package specific README file has been included or updated
• One or more example input decks are included

Further Information, Files, and Links

Test image:

[akohlmey]

As indicated in individual comments, this needs changes to the code and documentation and some explanation. It would also be an opportunity to do some refactoring beyond your changes, especially for the documentation to make it better aligned with the latest style and conventions that we are trying to establish for better readability and visual appeal.

[tomswinburne]

I have implemented the changes @akohlmey , I added a similar enum for the verbose keyword also.

[tomswinburne]

To confirm @akohlmey , I will not edit anymore until future notice

[akohlmey]

To confirm @akohlmey , I will not edit anymore until future notice

I am done with my changes

[tomswinburne]

Many thanks for the quick changes @akohlmey

[athomps]

1. I suggest replacing terse and verbose keywords with a single optional keyword verbosity that is followed by values normal or terse or verbose. This will fully reflect the values of print_mode in the implementation. The doc page should be updated accordingly, including in Default section at the bottom "{verbosity} = {normal}"
2. The plot included in the PR shows that EDideal is different on the left and right sides of the climbing image. This should be reflected in the doc page definition of Fparallel, at least in the form of a comment, but ideally in the form of a mathematical expression.

[akohlmey]

1. I suggest replacing terse and verbose keywords with a single optional keyword verbosity that is followed by values normal or terse or verbose. This will fully reflect the values of print_mode in the implementation. The doc page should be updated accordingly, including in Default section at the bottom "{verbosity} = {normal}"

This is done now.

[tomswinburne]

2. The plot included in the PR shows that `EDideal` is different on the left and right sides of the climbing image.  This should be reflected in the doc page definition of Fparallel, at least in the form of a comment, but ideally in the form of a mathematical expression.

Updated doc page to reflect the operation of equal and ideal. During climbing, the ideal style no longer targets equal spacing, but equal spacing each side of the climbing image. The equal style is identical to ideal before climbing, then during climbing the target is equal absolute energy differences each side of the climbing image.

[athomps]

I approve.

[athomps]

Updated doc page to reflect the operation of equal and ideal. During climbing, the ideal style no longer targets equal spacing, but equal spacing each side of the climbing image. The equal style is identical to ideal before climbing, then during climbing the target is equal absolute energy differences each side of the climbing image.
@tomswinburne Thanks for also clarifying the effect of ideal style in climbing mode.

[tomswinburne]

Many thanks @akohlmey and @athomps !