user_guide.tex 12.6 KB
 giannozz committed Jan 29, 2012 1 2 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 \documentclass[12pt,a4paper]{article} \def\version{5.0} \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.  giannozz committed Jan 30, 2012 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:\\  giannozz committed Jan 29, 2012 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  giannozz committed Mar 10, 2012 95 \texttt{wannier\_ham} utility;  gsamsonidze committed Mar 13, 2012 96 97 \item Georgy Samsonidze (Bosch Research) for the interface with the Berkeley GW code.  giannozz committed Jan 29, 2012 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.  giannozz committed Mar 10, 2012 129 130 Several executable codes are produced in \texttt{PP/bin} and linked to \texttt{bin/}.  giannozz committed Jan 29, 2012 131   giannozz committed Mar 10, 2012 132 \section{Usage}  giannozz committed Jan 29, 2012 133   giannozz committed Mar 10, 2012 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 committed Feb 17, 2012 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$).  giannozz committed Jan 29, 2012 144 145 \subsection{Plotting selected quantities}  giannozz committed Mar 10, 2012 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.  giannozz committed Jan 29, 2012 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)\\  dceresoli committed Jan 30, 2012 161  RDG (reduced density gradient)\\  giannozz committed Jan 29, 2012 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.  giannozz committed Mar 10, 2012 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.  giannozz committed Jan 29, 2012 168 The output files can be directly read by the free plotting system Gnuplot  giannozz committed Mar 10, 2012 169 170 (1D or 2D plots), or by code \texttt{plotrho.x} that comes with \PostProc\ and produces PostScript 2D plots,  giannozz committed Jan 29, 2012 171 172 or by advanced plotting software XCrySDen and gOpenMol (3D plots).  giannozz committed Mar 10, 2012 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  giannozz committed Jan 29, 2012 176 177 for an example of STM image simulation.  giannozz committed Mar 10, 2012 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).  giannozz committed Jan 29, 2012 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  giannozz committed Mar 10, 2012 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  giannozz committed Jun 06, 2012 210 211 in sequence along lines, or if two consecutive points are the same. The code \texttt{bands.x} performs as well a  giannozz committed Mar 10, 2012 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.  giannozz committed Jan 29, 2012 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  giannozz committed Mar 10, 2012 219 using XCrySDen. See Example 02 for an example of Fermi surface  giannozz committed Jan 29, 2012 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)$.  giannozz committed Mar 10, 2012 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.  giannozz committed Jan 29, 2012 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  giannozz committed Mar 10, 2012 255 in conjunction with DFT+U calculations (see Example 05)  giannozz committed Jan 29, 2012 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}  giannozz committed Mar 10, 2012 262 Note that the \texttt{wfdd.x} code has been moved to \CP.  giannozz committed Jan 29, 2012 263   giannozz committed Mar 10, 2012 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.  giannozz committed Jan 29, 2012 273   giannozz committed Mar 10, 2012 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}  giannozz committed Jan 29, 2012 280 281  Code \texttt{epsilon.x} calculates RPA frequency-dependent complex dielectric  giannozz committed Mar 10, 2012 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.  giannozz committed Jan 29, 2012 288 289 290  \section{Troubleshooting}  giannozz committed Mar 10, 2012 291 Almost all problems in \qe\ arise from incorrect input data and result in  giannozz committed Jan 29, 2012 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}