quantum-espresso/NEB/Doc/user_guide.tex

\documentclass[12pt,a4paper]{article}
\def\version{7.3.1}
\def\qe{{\sc Quantum ESPRESSO}}
\def\NEB{\texttt{PWneb}} % to be decided
\usepackage{html}

% BEWARE: don't revert from graphicx for epsfig, because latex2html
% doesn't handle epsfig commands !!!
\usepackage{graphicx}

\textwidth = 17cm
\textheight = 24cm
\topmargin =-1 cm
\oddsidemargin = 0 cm

\def\pwx{\texttt{pw.x}}
\def\nebx{\texttt{neb.x}}
\def\configure{\texttt{configure}}
\def\PWscf{\texttt{PWscf}}
\def\make{\texttt{make}}

\begin{document} 
\author{}
\date{}

\def\qeImage{../../Doc/quantum_espresso}

\title{
  \includegraphics[width=5cm]{\qeImage} \\
  % title
  \Huge \NEB\ User's Guide (v. \version)
}

\maketitle

\tableofcontents

\section{Introduction}

This guide covers the usage of \NEB, version \version: 
an open-source package for the calculation of energy barriers 
and reaction pathway using the Nudged Elastic Band (NEB) method.

This guide assumes that you know the physics 
that \NEB\ describes and the methods it implements.
It also assumes  that you have already installed,
or know how to install, \qe. If not, please read
the general User's Guide for \qe, found in 
subdirectory \texttt{Doc/} of the main \qe\ directory,
or consult the web site:\\
\texttt{http://www.quantum-espresso.org}.

\NEB \ is part of the \qe \ distribution and uses the \PWscf\
package as electronic-structure computing tools (``engine''). 
It is however written in a modular way and could be adapted 
to use other codes as ``engine''. Since v.4.3 the NEB calculation
is performed by a separate executable \nebx\ and no longer by 
\pwx. Also note that NEB with Car-Parrinello molecular dynamics 
is no longer implemented since v.4.3.

\section{People and terms of use}
The current maintainers of \NEB\ are Layla Martin-Samos,
Paolo Giannozzi, Stefano de Gironcoli.
The original \qe \ implementation of NEB was written 
by Carlo Sbraccia.

\NEB\ is free software, released under the 
GNU General Public License. \\ See
\texttt{http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt}, 
or the file License in the distribution).
    
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\input ../../Doc/quote.tex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Compilation}

\NEB\ is a package of \qe\ and requires package \PWscf\ for
compilation.
For instruction on how to download and compile \qe, please refer 
to the general Users' Guide, available in file \texttt{Doc/user\_guide.pdf}
under the main \qe\ directory, or in web site 
\texttt{http://www.quantum-espresso.org}.

Once \qe\ is correctly configured, \NEB\ can be automatically 
downloaded, unpacked and compiled by
just typing \texttt{make neb}, from the main \qe\ directory.
\texttt{make neb} will produce 
the following codes in \texttt{NEB/src}:
\begin{itemize}
\item \nebx: calculates reaction barriers and pathways using NEB.
\item \texttt{path\_interpolation.x}: generates a reaction path (a set of points
in the configuration space of the atomic system, called ``images''), by
 interpolating the supplied path. The new path can have a 
 different number of images than the old one and the initial and final 
 images of the new path can differ from the original ones.
 The utility \texttt{path\_interpolation.sh} in the \texttt{tools/}
 directory shows how to use the code.
\end{itemize}

Symlinks to executable programs will be placed in the
\texttt{bin/} subdirectory of the main \qe\  directory.

\subsection{Running examples}
\label{SubSec:Examples}
As a final check that compilation was successful, you may want
to run the examples (presently only one). See the general documentation
for instructions on how to run the examples.

Go to \texttt{NEB/examples/example01} and execute:
\begin{verbatim}
      ./run_example
\end{verbatim}
This will create a subdirectory \texttt{results/} containing the input and
output files generated by the calculation.

The \texttt{reference/} subdirectory contains
verified output files, that you can check your results against.
The exact numbers depend upon the hardware, software stack,
execution mode: tiny differences are not a problem, but
a plain diff of your results against the reference data
doesn't work, or at least, it requires human inspection.

\section{Parallelism}
\label{Sec:para}

The \NEB\ code is interfaced to \PWscf, which is used as computational engine 
for total energies and forces. It can therefore take advantage from the two 
parallelization paradigms currently implemented in \qe, namely
  Message Passing Interface (MPI) and OpenMP threads, and exploit
all \PWscf-specific parallelization options.
For a detailed information about parallelization in \qe, 
please refer to the general documentation.

In addition, \NEB \ makes several independent evaluations
of energy and forces at each step of the path optimization:
one per ``image'', that is, a point in the path, corresponding
to a set of atomic positions.
It is thus possible and often convenient to distribute
images among processors, using the ``image'' parallelization,
as described in the general documentation. The number of image
groups is specified using the option \texttt{-ni N} (or,
equivalently,  \texttt{-nimage N}) after the executable name
(e.g., \nebx) in the command line. The default is a single
image group (no image parallelization)

Images are loosely coupled calculations: processors belonging to
different image groups communicate only once in a while, whereas
processors within the same image group are tightly coupled and 
communications are more significant (please refer to the user
guide of \PWscf).

\section{Using \NEB}

NEB calculations with \texttt{neb.x} can be started in two different ways:
\begin{enumerate}
\item by reading a single input file, specified with the command line 
option \texttt{-i} (or \texttt{-in}, or \texttt{-inp} );
\item by specifying the number $N$ of images with the command line option 
\texttt{-input\_images N}, and providing the input data for \NEB\ in
a file named \texttt{neb.dat} and for the \PWscf\ engine in the files
 \texttt{pw\_X.in} ($X=1,...,N$, see also below).
\end{enumerate}

In the first case, the input file contains keywords (described here below) 
that enable the code to distinguish between parts of the input containing 
NEB-specific parameters and parts containing instructions for the 
computational engine (only PW is currently supported).

\noindent\textbf{N.B.:} the \nebx\ code does not read from standard input,
so that input redirection (e.g., \texttt{neb.x < neb.in ...}) cannot be used.

The general structure of the file to be parsed should be as follows:
\begin{verbatim}
BEGIN
BEGIN_PATH_INPUT
~... neb specific namelists and cards
END_PATH_INPUT
BEGIN_ENGINE_INPUT
~...pw specific namelists and cards
BEGIN_POSITIONS
FIRST_IMAGE
~...pw ATOMIC_POSITIONS card
INTERMEDIATE_IMAGE
~...pw ATOMIC_POSITIONS card
LAST_IMAGE
~...pw ATOMIC_POSITIONS card
END_POSITIONS
~... other pw specific cards
END_ENGINE_INPUT
END
\end{verbatim}

After the parsing is completed, several files are generated by \NEB, more 
specifically: \texttt{neb.dat}, with NEB-related input data, 
and a set of input files in the \PWscf\ format, \texttt{pw\_1.in}, \ldots,
\texttt{pw\_N.in}, one for each set of atomic position (image) found in 
the original input file.
For the second case, the \texttt{neb.dat} file and all \texttt{pw\_X.in} 
should be already present in the directory where the code is started.
A detailed description of all NEB-specific input variables is contained 
in the input description files \texttt{Doc/INPUT\_NEB.*}, while for the
\PWscf\ engine all the options of a \texttt{scf} calculation apply (see
\texttt{PW/Doc/INPUT\_PW.*} and \texttt{example01} in the 
\texttt{NEB/examples} directory). 

A NEB calculation will produce a number of output files containing additional 
information on the minimum-energy path. The following files are created in the
directory were the code is started:
\begin{description}
\item[\texttt{prefix.dat}]
is a three-column file containing the position of each image on the reaction
coordinate (arb. units), its energy in eV relative to the energy of the first image
and the residual error for the image in eV/$a_0$.
\item[\texttt{prefix.int}]
contains an interpolation of the path energy profile that pass exactly through each
image; it is computed using both the image energies and their derivatives
\item[\texttt{prefix.path}]
information used by \qe\ 
to restart a path calculation, its format depends on the input
details and is undocumented
\item[\texttt{prefix.axsf}]
atomic positions of all path images in the XCrySDen animation format:
to visualize it, use \texttt{xcrysden -\--axsf prefix.axsf}
\item[\texttt{prefix.xyz}]
atomic positions of all path images in the generic xyz format, used by
many quantum-chemistry softwares
\item[\texttt{prefix.crd}]
path information in the input format used by \pwx, suitable for a manual
restart of the calculation
\end{description}
where \texttt{prefix} is the \PWscf\ variable specified in the input.
The more verbose output from the \PWscf\ engine is not printed on the standard
output, but is redirected into a file stored in the image-specific temporary 
directories (e.g. \texttt{outdir/prefix\_1/PW.out} for the first image, etc.).

NEB calculations are a bit tricky in general and require extreme care to be
setup correctly. Sometimes it can easily take hundreds of iterations for them
 to converge, depending on the number of atoms and of images. 
Here you can find some advice (courtesy of Lorenzo Paulatto):
\begin{enumerate}
\item 
Don't use Climbing Image (CI) from the beginning. It makes convergence slower, 
especially if the special image changes during the convergence process (this 
may happen if \texttt{CI\_scheme='auto'} and if it does it may mess up everything).
Converge your calculation, then restart from the last configuration with
CI option enabled (note that this will {\em increase} the barrier).
\item
Carefully choose the initial path. 
If you ask the code to use more images than those you have supplied on input,
the code will make a linear interpolation of the atomic positions between
consecutive input images.
You can visualize the \texttt{.axsf} file with XCrySDen as an animation:
 take some time to check if any atoms overlap or get very close in some
of the new images (in that case you will have to supply intermediate images).
Remember that \qe\ assumes continuity between two consecutive input images
 to initialize the path. In other words, periodic images are not used 
by default, so that an unwanted path could result if some atom crosses the 
border of the unit cell and it is refolded in the unit cell in the input image.
The problem can be solved by activating the mininum\_image option, which choses
an appropriate periodic replica of any atom that moves by more than half the
size of the unit cell between two consecutive input images.
If this does not work either, you may have to manually translate an atom by
one or more unit cell base vectors in order to have a meaningful initial path. 
\item
Try to start the NEB process with most atomic positions fixed, 
in order to converge the more "problematic" ones, before leaving
all atoms move.
\item
Especially for larger systems, you can start NEB with lower accuracy 
(less k-points, lower cutoff) and then increase it when it has
converged to refine your calculation.
\item
Use the Broyden algorithm instead of the default one: it is a bit more
fragile, but it removes the problem of "oscillations" in the calculated
activation energies. If these oscillations persist, and you cannot afford 
more images, focus to a smaller problem, decompose it into pieces.
\item
A gross estimate of the required number of iterations is
(number of images) * (number of atoms) * 3. Atoms that do not
move should not be counted. It may take half that many iterations, 
or twice as many, but more or less that's the order of magnitude, 
unless one starts from a very good or very bad initial guess.
\end{enumerate}

The code \texttt{path\_int.x} is
is a tool to generate a new path (what is actually
generated is the restart file) starting from an old one through
interpolation (cubic splines). The new path can be discretized with a
different number of images (this is its main purpose), images are
equispaced and the interpolation can be also
performed on a subsection of the old path. The input file needed by
\texttt{path\_int.x} can be easily set up  with the help of the self-explanatory
\texttt{path\_interpolation.sh} shell script in the \texttt{NEB/tools} folder.


\section{Performances}

\NEB \ requires roughly the time and memory 
needed for a single SCF calculation, times
\texttt{num\_of\_images}, times the number 
of NEB iterations needed to reach convergence.
We
refer the reader to the PW user\_guide for more information.

\section{Troubleshooting}

Almost all problems in \NEB \ arise from incorrect input data 
and result in
error stops. Error messages should be self-explanatory, but unfortunately
this is not always true. If the code issues a warning messages and continues,
pay attention to it but do not assume that something is necessarily wrong in
your calculation: most warning messages signal harmless problems.

\end{document}