user_guide.tex 12.6 KB
Newer Older
1
\documentclass[12pt,a4paper]{article}
2
\def\version{5.1.1}
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
\def\qe{{\sc Quantum ESPRESSO}}

\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\cpx{\texttt{cp.x}}
\def\phx{\texttt{ph.x}}
\def\nebx{\texttt{neb.x}}
\def\configure{\texttt{configure}}
\def\PWscf{\texttt{PWscf}}
\def\PHonon{\texttt{PHonon}}
\def\CP{\texttt{CP}}
\def\PostProc{\texttt{PostProc}}
\def\NEB{\texttt{PWneb}} % to be decided
\def\make{\texttt{make}}

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

\def\qeImage{../../Doc/quantum_espresso.pdf}
\def\democritosImage{../../Doc/democritos.pdf}

\begin{htmlonly}
\def\qeImage{quantum_espresso.png}
\def\democritosImage{democritos.png}
\end{htmlonly}

\title{
  \includegraphics[width=5cm]{\qeImage} \hskip 2cm
  \includegraphics[width=6cm]{\democritosImage}\\
  \vskip 1cm
  % title
  \Huge User's Guide for \PostProc\
  \Large (version \version)
}
%\endhtmlonly

%\latexonly
%\title{
% \epsfig{figure=quantum_espresso.png,width=5cm}\hskip 2cm
% \epsfig{figure=democritos.png,width=6cm}\vskip 1cm
%  % title
%  \Huge User's Guide for \qe \smallskip
%  \Large (version \version)
%}
%\endlatexonly

\maketitle

\tableofcontents

\section{Introduction}

This guide covers the usage of \PostProc, version \version: 
an open-source package for postprocessing of data produced by
\PWscf\ and \CP. \PostProc\ is part of the \qe\ distribution 
and requires \PWscf\ to be installed.

71 72 73 74 75 76 77
This guide assumes that you know the physics 
that \PostProc\ 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 
directory \texttt{Doc/} two levels above the 
one containing this guide; or consult the web site:\\
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
\texttt{http://www.quantum-espresso.org}.

Further documentation, beyond what is provided 
in this guide, can be found in the directory
\texttt{PP/Doc/}, containing a copy of this guide.
People who want to contribute to \qe\ should read the 
Developer Manual, found in directory \texttt{Doc/} two levels
above the one containing this guide: \texttt{Doc/developer\_man.pdf}.

\section{People and terms of use}

The \PostProc\ package was originally developed by Stefano Baroni, 
Stefano de Gironcoli, Andrea Dal Corso (SISSA), Paolo Giannozzi 
(Univ. Udine), and many others. We mention in particular: 
\begin{itemize}
\item Andrea Benassi (SISSA) for the \texttt{epsilon} utility;
\item Dmitry Korotin (Inst. Met. Phys. Ekaterinburg) for the
95
\texttt{wannier\_ham} utility;
96 97
\item Georgy Samsonidze (Bosch Research) for the interface
      with the Berkeley GW code.
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
\end{itemize}

\PostProc\ 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).
    
We shall greatly appreciate if scientific work done using this code will 
contain an explicit acknowledgment and the following reference:
\begin{quote}
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),
http://arxiv.org/abs/0906.2569
\end{quote}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Compilation}

\PostProc\ is distributed together with \qe.
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, \PostProc\ can be compiled by
just typing \texttt{make pp}, from the main \qe\ directory;
or typing \make\ from the \texttt{PP/} subdirectory.
129 130
Several executable codes are produced in \texttt{PP/bin}
and linked to \texttt{bin/}.
131

132
\section{Usage}
133

134 135 136 137
All codes for which input documentation is not explicitly mentioned below
havesome documentation in the header of the fortran sources.
In the following, ``Example N'' standes for subdirectory 
\texttt{examples/exampleN/}.
giannozz's avatar
giannozz committed
138 139 140 141 142 143

All quantities whose dimensions are not explicitly specified are in
RYDBERG ATOMIC UNITS. Charge is "number" charge (i.e. not multiplied 
by $e$); potentials are in energy units (i.e. they are multiplied by 
$e$).

144 145
\subsection{Plotting selected quantities}
  
146 147 148 149
The main postprocessing code \texttt{pp.x} extracts the specified data
from the data files produced by \PWscf\ (\pwx\ executable) or \CP\ 
(\cpx\ executable); prepares data for plotting by writing them into 
formats that can be read by several plotting programs.
150 151 152 153 154 155 156 157 158 159 160

Quantities that can be read or calculated are:
\begin{quote}
      charge density\\
      spin polarization\\
      various potentials\\
      local density of states at $E_F$\\
      local density of electronic entropy\\
      STM images\\
      selected squared wavefunction\\
      ELF (electron localization function)\\
161
      RDG (reduced density gradient)\\
162 163 164 165
      integrated local density of states
\end{quote}
Various types of plotting (along a line, on a plane, three-dimensional, polar)
and output formats (including the popular cube format) can be specified.
166 167
Moreover data can be saved to an intermediate (formatted) file so that
more data set can be summed or subracted in a later run.
168
The output files can be directly read by the free plotting system Gnuplot
169 170
(1D or 2D plots), or by code \texttt{plotrho.x} that comes with \PostProc\ 
and produces PostScript 2D plots,
171 172
or by advanced plotting software XCrySDen and gOpenMol (3D plots).

173 174 175
See file \texttt{Doc/INPUT\_PP.*} for a detailed description of the input
for code \texttt{pp.x}.
See Example 01 for an example of a charge density plot, Example 03
176 177
for an example of STM image simulation.

178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
\paragraph{Planar averages}
Code \texttt{plan\_avg.x} calculates planar averages of Kohn-Sham orbitals.
Code \texttt{average.x} calculates planar averages of quantities calculated
by \texttt{pp.x} (e.g. potentials, charge, magnetization densities).
Note that \texttt{average.x} reads the intermediate file produced
by \texttt{pp.x}, not data files produced by \pwx. Examples of usage 
of \texttt{average.x} can be found in \texttt{examples/WorcFct\_example/} 
and in \texttt{examples/dipole\_example/}.

\paragraph{All-electron charge}
\texttt{pawplot.x} produces plots of the all-electron charge
for PAW calculations.

\paragraph{About Bader's analysis}
In \texttt{http://theory.cm.utexas.edu/bader/} one can find a software 
that performs
Bader's analysis starting from charge on a regular grid. The required 
"cube" format can be produced by \qe\ using  \texttt{pp.x} (info by G. Lapenna
who has successfully used this technique, but adds: ``Problems occur with polar 
X-H bonds or in all cases where the zero-flux of density comes too close to 
atoms described with pseudo-potentials"). This code should perform 
decomposition into Voronoi polyhedra as well, in place of obsolete
code  \texttt{voronoy.x} (removed from distribution since v.4.2).

202 203 204 205 206
\subsection{Band structure, Fermi surface}

The code \texttt{bands.x} reads data file(s), extracts eigenvalues,
regroups them into bands (the algorithm used to order bands and to resolve
crossings may not work in all circumstances, though). The output is written
207 208 209
to a file in a simple format that can be directly read and converted to
plottable format by auxiliary code
\texttt{plotband.x}. Unpredictable plots may results if k-points are not 
210 211
in sequence along lines, or if two consecutive points are the same. 
The code \texttt{bands.x} performs as well a 
212 213 214
symmetry analysis of the band structure. For a complete input description,
see\texttt{Doc/INPUT\_bands.*}. See Example 01, Example 04 and Example 06 
for simple band plots.
215 216 217 218

The calculation of Fermi surface can be performed using 
\texttt{kvecs\_FS.x} and
\texttt{bands\_FS.x}. The resulting file in .xsf format can be read and plotted
219
using XCrySDen. See Example 02 for an example of Fermi surface 
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238
visualization (Ni, including the spin-polarized case).

\subsection{Projection over atomic states, DOS}

The code \texttt{projwfc.x} calculates projections of wavefunctions
over atomic orbitals. The atomic wavefunctions are those contained
in the pseudopotential file(s). The L\"owdin population analysis (similar to
Mulliken analysis) is presently implemented. The projected DOS (or PDOS:
the DOS projected onto atomic orbitals) can also be calculated and written
to file(s). More details on the input data are found in file
\texttt{Doc/INPUT\_PROJWFC.*}. The ordering of the various 
angular momentum components (defined in routine \texttt{flib/ylmr2.f90})
is as follows:
$P_{0,0}(t)$, $P_{1,0}(t)$, $P_{1,1}(t)cos\phi$, $P_{1,1}(t)sin\phi$,
 $P_{2,0}(t)$, $P_{2,1}(t)cos\phi$, $P_{2,1}(t)sin\phi$, 
 $P_{2,2}(t)cos2\phi$, $P_{2,2}(t)sin2\phi$
and so on, where $P_{l,m}$=Legendre Polynomials, 
$t = cos\theta = z/r$, $\phi= atan(y /x)$.

239 240 241 242 243 244 245 246 247 248
Data produced by code \texttt{projwfc.x} can be further 
analysed using auxiliary codes \texttt{sumpdos.x} (sums selected PDOS
by specifying the names of files containing the desired PDOS: type 
\texttt{sumpdos.x -h} or look into the source code for more details) 
and \texttt{plotproj.x} . 

The total electronic DOS can also be calculated by code \texttt{dos.x},
whose complete input documentation is in \texttt{Doc/INPUT\_DOS.*}
See Example 02 for total and projected electronic DOS calculations;
see Example 03 for projected and local DOS calculations.
249 250 251 252 253 254

\subsection{Wannier functions}

There are several Wannier-related utilities in \PostProc:
\begin{enumerate}
\item The "Poor Man Wannier" code \texttt{pmw.x}, to be used
255
in conjunction with DFT+U calculations (see Example 05)
256 257 258 259 260 261
\item The interface with Wannier90 code, \texttt{pw2wannier.x}:
see the documentation in \texttt{W90/} (you have to install the 
Wannier90 plug-in)
\item The \texttt{wannier\_ham.x} code generates a model Hamiltonian 
in Wannier functions basis: see \texttt{examples/WannierHam\_example/}.
\end{enumerate}
262
Note that the \texttt{wfdd.x} code has been moved to \CP.
263

264 265 266 267 268 269 270 271 272
\subsection{Interfaces to/from other code}

Codes \texttt{pw2bgw.x} and \texttt{bgw2pw.x} convert data files from
\pwx\ to a format suitable for usage by the Berkeley GW code, and vice
versa. See files \texttt{Doc/INPUT\_pw2bgw.*} and \texttt{Doc/INPUT\_bgw2pw.*}
for input data documentation.

Undocumented code \texttt{pw2gw.x} converts data files from \pwx\ to
a format suitable for usage by another GW code.
273

274 275 276 277 278 279
Code \texttt{pw\_export.x}, not compiled by default, is an interface
to other codes, documented in \texttt{Doc/INPUT\_pw\_export.*}
Code \texttt{qexml.x}, not compiled by default, is a template that
is useful to follow when wrting interfaces.

\subsection{Other tools}
280 281

Code \texttt{epsilon.x} calculates RPA frequency-dependent complex dielectric 
282 283 284 285 286 287
function. Documentation is in file \texttt{Doc/eps\_man.tex}.

Code \texttt{initial\_state.x} calculates the initial state contribution
to the Core-level shift. See \texttt{examples/CLS\_IS\_example/} for
an example, and \texttt{examples/CLS\_FS\_example/} for the corrsponding
final state calculation of Core-level shifts.
288 289 290

\section{Troubleshooting}

291
Almost all problems in \qe\ arise from incorrect input data and result in
292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312
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.

\paragraph{Some postprocessing codes complain that they do not find some files}
For Linux PC clusters in parallel execution: in at least some versions
of MPICH, the current directory is set to the directory where the executable
code resides, instead of being set to the directory where the code is executed.
This MPICH weirdness may cause unexpected failures in some postprocessing
codes that expect a data file in the current directory. Workaround: use
symbolic links, or copy the executable to the current directory.

\paragraph{{\em error in davcio} in postprocessing codes}
Most likely you are not reading the correct data files, or you are not
following the correct procedure for postprocessing. In parallel execution: 
if you did not set \texttt{wf\_collect=.true.}, the number of processors and 
pools for the phonon run should be the same as for the
self-consistent run; all files must be visible to all processors.

\end{document}