User Guide
user_guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 8
PWneb User’s Guide (v. 6.2.1)
(only partially updated)
Contents
1 Introduction 1
2 People and terms of use 1
3 Compilation 2
3.1 Runningexamples .................................. 2
4 Parallelism 3
4.1 Running on parallel machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.2 Parallelizationlevels ................................. 4
5 Using PWneb 5
6 Performances 7
7 Troubleshooting 7
1 Introduction
This guide covers the usage of PWneb, version 6.2.1: an open-source package for the calculation
of energy barriers and reaction pathway using the Nudged Elastic Band (NEB) method.
Important notice: due to the lack of time and of manpower, this manual is only partially
updated and may contain outdated information.
This guide assumes that you know the physics that PWneb describes and the methods it
implements. It also assumes that you have already installed, or know how to install, Quantum
ESPRESSO. If not, please read the general User’s Guide for Quantum ESPRESSO, found
in directory Doc/ two levels above the one containing this guide; or consult the web site:
http://www.quantum-espresso.org.
PWneb is part of the Quantum ESPRESSO 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”. Note that since v.4.3 PWscf no longer
1
performs NEB calculations. Also note that NEB with Car-Parrinello molecular dynamics is
not implemented anymore since v.4.3.
2 People and terms of use
The current maintainers of PWneb are Layla Martin-Samos, Paolo Giannozzi, Stefano de Giron-
coli. The original Quantum ESPRESSO implementation of NEB was written by Carlo
Sbraccia.
PWneb is free software, released under the GNU General Public License.
See http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt, or the file License in the
distribution).
We shall greatly appreciate if scientific work done using the Quantum ESPRESSO dis-
tribution will contain an acknowledgment to the following references:
P. Giannozzi, S. Baroni, N. Bonini, M. Calandra, R. Car, C. Cavazzoni, D. Ceresoli,
G. L. Chiarotti, M. Cococcioni, I. Dabo, A. Dal Corso, S. Fabris, G. Fratesi, S. de
Gironcoli, R. Gebauer, U. Gerstmann, C. Gougoussis, A. Kokalj, M. Lazzeri, L.
Martin-Samos, N. Marzari, F. Mauri, R. Mazzarello, S. Paolini, A. Pasquarello, L.
Paulatto, C. Sbraccia, S. Scandolo, G. Sclauzero, A. P. Seitsonen, A. Smogunov, P.
Umari, R. M. Wentzcovitch, J.Phys.: Condens.Matter 21, 395502 (2009)
and
P. Giannozzi, O. Andreussi, T. Brumme, O. Bunau, M. Buongiorno Nardelli, M.
Calandra, R. Car, C. Cavazzoni, D. Ceresoli, M. Cococcioni, N. Colonna, I. Carn-
imeo, A. Dal Corso, S. de Gironcoli, P. Delugas, R. A. DiStasio Jr, A. Ferretti, A.
Floris, G. Fratesi, G. Fugallo, R. Gebauer, U. Gerstmann, F. Giustino, T. Gorni, J
Jia, M. Kawamura, H.-Y. Ko, A. Kokalj, E. K¨u¸c¨ukbenli, M .Lazzeri, M. Marsili, N.
Marzari, F. Mauri, N. L. Nguyen, H.-V. Nguyen, A. Otero-de-la-Roza, L. Paulatto,
S. Ponc´e, D. Rocca, R. Sabatini, B. Santra, M. Schlipf, A. P. Seitsonen, A. Smo-
gunov, I. Timrov, T. Thonhauser, P. Umari, N. Vast, X. Wu, S. Baroni J.Phys.:
Condens.Matter 29, 465901 (2017)
Note the form Quantum ESPRESSO for textual citations of the code. Please also see
package-specific documentation for further recommended citations. Pseudopotentials should
be cited as (for instance)
[ ] We used the pseudopotentials C.pbe-rrjkus.UPF and O.pbe-vbc.UPF from
http://www.quantum-espresso.org.
3 Compilation
PWneb is a package tightly bound to Quantum ESPRESSO. For instruction on how to down-
load and compile Quantum ESPRESSO, please refer to the general Users’ Guide, available
in file Doc/user guide.pdf under the main Quantum ESPRESSO directory, or in web site
http://www.quantum-espresso.org.
Once Quantum ESPRESSO is correctly configured, PWneb can be automatically down-
loaded, unpacked and compiled by just typing make neb, from the main Quantum ESPRESSO
directory. make neb will produce the following codes in NEB/src:
2
•neb.x: calculates reaction barriers and pathways using NEB.
•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 path interpolation.sh in
the tools/ directory shows how to use the code.
Symlinks to executable programs will be placed in the bin/ subdirectory of the main Quan-
tum ESPRESSO directory.
3.1 Running examples
As a final check that compilation was successful, you may want to run some or all of the
examples (presently only one). To run the examples, you should follow this procedure:
1. Edit the environment variables file in the main Quantum ESPRESSO directory,
setting the following variables as needed:
BIN DIR: directory where executables reside
PSEUDO DIR: directory where pseudopotential files reside
TMP DIR: directory to be used as temporary storage area
The default values of BIN DIR and PSEUDO DIR should be fine, unless you have installed
things in nonstandard places. The TMP DIR variable must point to a directory where you have
read and write permissions, with enough available space to host the temporary files produced by
the example runs, and possibly offering good I/O performance (i.e., don’t use an NFS-mounted
directory). N.B. Use a dedicated directory, because the example script will automatically delete
all data inside TMP DIR. If you have compiled the parallel version of Quantum ESPRESSO
(this is the default if parallel libraries are detected), you will usually have to specify a driver
program (such as mpirun or mpiexec) and the number of processors: see Sec.4.1 for details. In
order to do that, edit again the environment variables file and set the PARA PREFIX and
PARA POSTFIX variables as needed. Parallel executables will be started with a command
line like this:
$PARA_PREFIX neb.x $PARA_POSTFIX -inp file.in > file.out
For example, the command for IBM’s POE looks like this:
poe neb.x -procs 4 -inp file.in > file.out
therefore you will need to set PARA PREFIX=”poe”, PARA POSTFIX=”-procs 4”. Further-
more, if your machine does not support interactive use, you must run the commands specified
below through the batch queuing system installed on that machine. Ask your system adminis-
trator for instructions.
Go to NEB/examples/examplex01 and execute:
./run_example
3
This will create a subdirectory results/ containing the input and output files generated by
the calculation.
The reference/ subdirectory contains verified output files, that you can check your results
against. They were generated on a Linux PC using the Intel compiler. On different architectures
the precise numbers could be slightly different, in particular if different FFT dimensions are
automatically selected. For this reason, a plain diff of your results against the reference data
doesn’t work, or at least, it requires human inspection of the results.
4 Parallelism
The PWneb 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 im-
plemented in Quantum ESPRESSO, namely Message Passing Interface (MPI) and OpenMP
threads, and exploit all PWscf-specific parallelization options. For a detailed information about
parallelization in Quantum ESPRESSO, please refer to the general documentation.
As PWneb makes several independent evaluations of energy and forces at each step of the
path optimization (one for each point in the configurational space, called “image”, consitut-
ing the path) it is possible to distribute them among processors using an additional level of
parallelization (see later).
4.1 Running on parallel machines
Parallel execution is strongly system- and installation-dependent. Typically one has to specify:
1. a launcher program (not always needed), such as poe,mpirun,mpiexec, with the appro-
priate options (if any);
2. the number of processors, typically as an option to the launcher program, but in some
cases to be specified after the name of the program to be executed;
3. the program to be executed, with the proper path if needed: for instance, ./neb.x, or
$HOME/bin/neb.x, or whatever applies;
4. other PWscf-specific parallelization options, to be read and interpreted by the running
code;
5. the number of image groups used by NEB (see next subsection).
Items 1) and 2) are machine- and installation-dependent, and may be different for interactive
and batch execution. Note that large parallel machines are often configured so as to disallow
interactive execution: if in doubt, ask your system administrator. Item 3) also depend on your
specific configuration (shell, execution path, etc). Item 4) is optional but may be important:
see the following section for the meaning of the various options.
For illustration, here is how to run neb.x on 16 processors partitioned into 4 image groups
(4 processors each), for a path containing at least 4 images with POE:
poe neb.x -procs 16 -ni 4 -i input
4
4.2 Parallelization levels
Data structures are distributed across processors. Processors are organized in a hierarchy of
groups, which are identified by different MPI communicators level. The groups hierarchy is as
follow:
world - image_group - PWscf hierarchy
world: is the group of all processors (MPI COMM WORLD).
image group: Processors can then be divided into different image groups, each of them
taking care of one or more NEB images.
Image parallelization is of loosely coupled type, so that 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).
The default number of image groups is one, corresponding to the option -ni 1 (or, equiva-
lently, -nimage 1).
5
5 Using PWneb
NEB calculations with neb.x can be started in two different ways:
1. by reading a single input file, specified with the command line option -i (or -in, or -inp
);
2. by specifying the number Nof images with the command line option -input images N,
and providing the input data for PWneb in a file named neb.dat and for the PWscf engine
in the files pw X.in (X= 1, ..., N , see also below).
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).
N.B.: the neb.x code does not read from standard input, so that input redirection (e.g., neb.x
< neb.in ...) cannot be used.
The general structure of the file to be parsed should be as follows:
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
After the parsing is completed, several files are generated by PWneb, more specifically:
neb.dat, with NEB-related input data, and a set of input files in the PWscf format, pw 1.in,
. . . , pw N.in, one for each set of atomic position (image) found in the original input file. For the
second case, the neb.dat file and all 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 Doc/INPUT NEB.*, while for the PWscf engine all the options of a scf
calculation apply (see PW/Doc/INPUT PW.* and example01 in the 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:
prefix.dat is a three-column file containing the position of each image on the reaction co-
ordinate (arb. units), its energy in eV relative to the energy of the first image and the
residual error for the image in eV/a0.
6
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
prefix.path information used by Quantum ESPRESSO to restart a path calculation, its
format depends on the input details and is undocumented
prefix.axsf atomic positions of all path images in the XCrySDen animation format: to visu-
alize it, use xcrysden --axsf prefix.axsf
prefix.xyz atomic positions of all path images in the generic xyz format, used by many
quantum-chemistry softwares
prefix.crd path information in the input format used by pw.x, suitable for a manual restart
of the calculation
where 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. 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):
1. Don’t use Climbing Image (CI) from the beginning. It makes convergence slower, espe-
cially if the special image changes during the convergence process (this may happen if
CI scheme=’auto’ and if it does it may mess up everything). Converge your calcula-
tion, then restart from the last configuration with CI option enabled (note that this will
increase the barrier).
2. 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 .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 Quantum ESPRESSO 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.
3. Try to start the NEB process with most atomic positions fixed, in order to converge the
more ”problematic” ones, before leaving all atoms move.
4. 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.
5. 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 oscil-
lations persist, and you cannot afford more images, focus to a smaller problem, decompose
it into pieces.
7
6. 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.
The code 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 path int.x can be easily set up with the help of the self-explanatory
path interpolation.sh shell script in the NEB/tools folder.
6 Performances
PWneb requires roughly the time and memory needed for a single SCF calculation, times
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.
7 Troubleshooting
Almost all problems in PWneb 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.
8
