From 9f81ddc657c08c02ff900b009b00676d6179cb53 Mon Sep 17 00:00:00 2001 From: marsamos Date: Mon, 16 Jan 2012 14:41:40 +0000 Subject: [PATCH] some changes in main doc and PHonon/Doc added link to input_xx.xsl for PHonon/Doc git-svn-id: http://qeforge.qe-forge.org/svn/q-e/trunk/espresso@8450 c92efa57-630b-4861-b058-cf58834340f0 --- Doc/user_guide.tex | 799 +------------------------------------- PHonon/Doc/Makefile | 21 +- PHonon/Doc/user_guide.tex | 242 +++--------- 3 files changed, 79 insertions(+), 983 deletions(-) diff --git a/Doc/user_guide.tex b/Doc/user_guide.tex index ad9e26eee..16f346473 100644 --- a/Doc/user_guide.tex +++ b/Doc/user_guide.tex @@ -140,8 +140,8 @@ or patch some \qe\ routines can be installed as {\em plug-ins}: Available at \texttt{http://qe-forge.org/frs/?group\_id=37} (see also \texttt{http://www.gipaw.net}). \end{itemize} -This guide documents \PWscf, \CP, \PHonon, \PostProc. -The remaining packages have separate documentation. + +We refer the reader to the pachage-specific documentation for more information. The \qe\ codes work on many different types of Unix machines, including parallel machines using both OpenMP and MPI @@ -215,24 +215,6 @@ using the Nudged Elastic Band (NEB) and Fourier String Method Dynamics by the \pwx\ executable of \PWscf. Also note that NEB with Car-Parrinello Molecular Dynamics is currently not implemented. -\PHonon\ can perform the following types of calculations: -\begin{itemize} - \item phonon frequencies and eigenvectors at a generic wave vector, - using Density-Functional Perturbation Theory; - \item effective charges and dielectric tensors; - \item electron-phonon interaction coefficients for metals; - \item interatomic force constants in real space; - \item third-order anharmonic phonon lifetimes; - \item Infrared and Raman (nonresonant) cross section. -\end{itemize} -\PHonon\ can be used whenever \PWscf\ can be -used, with the exceptions of DFT+U, nonlocal VdW and hybrid functionals. -USPP and PAW are not implemented for higher-order response calculations. -See the header of file \texttt{PH/phonon.f90} for a complete and -updated list of what \PHonon\ can and cannot do. -Calculations, in the Quasi-Harmonic approximations, of the vibrational -free energy can be performed using the \texttt{QHA} package. - \PostProc\ can perform the following types of calculations: \begin{itemize} \item Scanning Tunneling Microscopy (STM) images; @@ -261,7 +243,7 @@ Paolo Giannozzi (Univ.Udine, Italy) and Layla Martin-Samos of the CINECA National Supercomputing Center in Bologna under the responsibility of Carlo Cavazzoni. -The \PWscf\ package (which included \PHonon\ and \PostProc\ +The \PWscf\ package (which included \PostProc\ in earlier releases) was originally developed by Stefano Baroni, Stefano de Gironcoli, Andrea Dal Corso (SISSA), Paolo Giannozzi, and many others. @@ -286,13 +268,6 @@ We quote in particular: free boundary conditions; \item Norbert Nemec and Mike Towler (U.Cambridge) for interface with \texttt{CASINO}. \end{itemize} -For \PHonon, we mention in particular: -\begin{itemize} - \item Michele Lazzeri (Univ.Paris VI) for the 2n+1 code and Raman - cross section calculation with 2nd-order response; - \item Andrea Dal Corso for USPP, noncolinear, spin-orbit - extensions to \PHonon. - \end{itemize} For \PostProc, we mention: \begin{itemize} \item Andrea Benassi (SISSA) for the \texttt{epsilon} utility; @@ -544,7 +519,6 @@ common to all packages: \texttt{include/} & files *.h included by fortran and C source files\\ \texttt{clib/} & external libraries written in C\\ \texttt{flib/} & external libraries written in Fortran\\ -\texttt{extlibs/ }& archive of external libraries LAPACK, BLAS and iotk\\ \texttt{install/} & installation scripts and utilities\\ \texttt{pseudo}/ & pseudopotential files used by examples\\ \texttt{upftools/}& converters to unified pseudopotential format (UPF)\\ @@ -562,12 +536,8 @@ while others are specific to a single package: \texttt{NEB/} &\texttt{PWneb}: source files for NEB calculations (\nebx)\\ \texttt{PP/} &\PostProc: source files for post-processing of \pwx\ data file\\ -\texttt{PH/} &\PHonon: source files for phonon calculations (\phx) - and analysis\\ -\texttt{Gamma/} &\PHonon: source files for Gamma-only phonon calculation - (\texttt{phcg.x})\\ -\texttt{D3/} &\PHonon: source files for third-order derivative - calculations (\texttt{d3.x})\\ +\texttt{PHonon/} &\PHonon: source files for phonon calculations (\phx) + and analysis, gamma-only phonon calculations and third-order derivatives.\\ \texttt{PWCOND/} &\texttt{PWcond}: source files for conductance calculations (\texttt{pwcond.x})\\ \texttt{vdW/} &\texttt{VdW}: source files for molecular polarizability @@ -575,7 +545,6 @@ while others are specific to a single package: \texttt{CPV/} &\CP: source files for Car-Parrinello code (\cpx)\\ \texttt{atomic/} &\texttt{atomic}: source files for the pseudopotential generation package (\texttt{ld1.x})\\ -\texttt{atomic\_doc/} &Documentation, tests and examples for \texttt{atomic}\\ \texttt{GUI/} & \texttt{PWGui}: Graphical User Interface\\ \end{tabular} @@ -886,33 +855,8 @@ for NEB calculations: different number of images. The initial and final points of the new path can differ from those in the original one. \end{itemize} -\item \texttt{make ph} produces the following codes in \texttt{PH/} -for phonon calculations: -\begin{itemize} - \item \phx\ : Calculates phonon frequencies and displacement patterns, - dielectric tensors, effective charges (uses data produced by \pwx). - \item \texttt{dynmat.x}: applies various kinds of Acoustic Sum Rule (ASR), - calculates LO-TO splitting at ${\bf q} = 0$ in insulators, IR and Raman - cross sections (if the coefficients have been properly calculated), - from the dynamical matrix produced by \phx - \item \texttt{q2r.x}: calculates Interatomic Force Constants (IFC) in real space - from dynamical matrices produced by \phx\ on a regular {\bf q}-grid - \item \texttt{matdyn.x}: produces phonon frequencies at a generic wave vector - using the IFC file calculated by \texttt{q2r.x}; may also calculate phonon DOS, - the electron-phonon coefficient $\lambda$, the function $\alpha^2F(\omega)$ -\item \texttt{lambda.x}: also calculates $\lambda$ and $\alpha^2F(\omega)$, - plus $T_c$ for superconductivity using the McMillan formula - \end{itemize} -\item \texttt{make d3} produces \texttt{D3/d3.x}: - calculates anharmonic phonon lifetimes (third-order derivatives - of the energy), using data produced by \pwx\ and \phx\ (USPP - and PAW not supported). -\item \texttt{make gamma} produces \texttt{Gamma/phcg.x}: - a version of \phx\ that calculates phonons at ${\bf q} = 0$ using - conjugate-gradient minimization of the density functional expanded to - second-order. Only the $\Gamma$ (${\bf k} = 0$) point is used for Brillouin zone - integration. It is faster and takes less memory than \phx, but does - not support USPP and PAW. +\item \texttt{make ph} produces several codes for the calculation of vibrational properties +and third-order derivatives. \item \texttt{make pp} produces several codes for data postprocessing, in \texttt{PP/} (see list below). \item \texttt{make tools} produces several utility programs in \texttt{pwtools/} (see @@ -2108,45 +2052,6 @@ convenient in some cases that the two sets are not the same. In particular, it is often convenient to have \texttt{nrx1}=\texttt{nr1}+1 to reduce memory conflicts. -\subsection{Pseudopotential files} -\label{SubSec:pseudo} -Pseudopotential files for tests and examples are found in the -\texttt{pseudo/} -subdirectory. A much larger set of PP's can be found under -the "pseudo'' link of the web site. \qe\ uses a unified -pseudopotential format (UPF) for all types of pseudopotentials, -but still accepts a number of older formats. If you do not find -what you need, you may -\begin{itemize} -\item Convert pseudopotentials written in a different format, -using the converters listed in \texttt{upftools/UPF} (compile with -\texttt{make upf}). -\item Generate it, using \texttt{atomic}. See the documentation in -\texttt{atomic\_doc/} and in particular the library of input files -in \texttt{pseudo\_library/}. -\item Generate it, using other packages: -\begin{itemize} -\item David Vanderbilt's code (UltraSoft and Norm-Conserving) -\item OPIUM (Norm-Conserving) -\item The Fritz Haber code (Norm-Conserving) -\end{itemize} -The first two codes produce pseudopotentials in one of the -supported formats; the third, in a format that can be converted -to UPF. -\end{itemize} -Remember: {\em always} test the pseudopotentials on simple test -systems before proceeding to serious calculations. - -Note that the type of XC used in the calculation is read from -pseudopotential files. As a rule, you should use only -pseudopotentials that have been generated using the same -XC that you are using in your simulation. You can override -this restriction by setting input variable \texttt{input\_dft}. The list of -allowed XC functionals and of their acronyms can be found in -\texttt{Modules/funct.f90}. - -More documentation on pseudopotentials and on the UPF format -can be found in the Wiki. \section{Using \PWscf} @@ -2451,130 +2356,6 @@ file formats used by the two codes. the UPFv2 format (though it will read other `deprecated' formats). This can be done through the `casino2upf' and `upf2casino' tools included in the upftools directory (see the upftools/README file for instructions). An alternative converter `casinogon' is included in the \texttt{CASINO} distribution which produces the deprecated GON format but which can be useful when using non-standard grids. -\section{Phonon calculations} - -Phonon calculation is presently a two-step process. -First, you have to find the ground-state atomic and electronic configuration; -Second, you can calculate phonons using Density-Functional Perturbation Theory. -Further processing to calculate Interatomic Force Constants, to add macroscopic -electric field and impose Acoustic Sum Rules at q=0 may be needed. -In the following, we will indicate by $q$ the phonon wavevectors, -while $k$ will indicate Bloch vectors used for summing over the Brillouin Zone. - -Since version 4.0 it is possible to safely stop execution of -\phx\ code using -the same mechanism of the \pwx\ code, i.e. by creating a file \texttt{prefix.EXIT} in the -working directory. Execution can be resumed by setting \texttt{recover=.true.} -in the subsequent input data. - -\subsection{Single-q calculation} - -The phonon code \phx\ calculates normal modes at a given q-vector, starting -from data files produced by \pwx with a simple SCF calculation. -NOTE: the alternative procedure in which a band-structure calculation -with \texttt{calculation='phonon} was performed as an intermediate step is no -longer implemented since version 4.1. It is also no longer needed to -specify \texttt{lnscf=.true.} for $q\ne 0$. - -The output data file appear in the directory specified by variables outdir, -with names specified by variable prefix. After the output file(s) has been -produced (do not remove any of the files, unless you know which are used -and which are not), you can run \phx. - -The first input line of \phx\ is a job identifier. At the second line the -namelist \&INPUTPH starts. The meaning of the variables in the namelist -(most of them having a default value) is described in file -\texttt{Doc/INPUT\_PH.*}. Variables \texttt{outdir} and \texttt{prefix} -must be the same as in the input data of \pwx. Presently -you must also specify \texttt{amass(i)} (a real variable): the atomic mass -of atomic type $i$. - -After the namelist you must specify the q-vector of the phonon mode, -in Cartesian coordinates and in units of $2\pi/a$. - -Notice that the dynamical matrix calculated by \phx\ at $q=0$ does not -contain the non-analytic term occurring in polar materials, i.e. there is no -LO-TO splitting in insulators. Moreover no Acoustic Sum Rule (ASR) is -applied. In order to have the complete dynamical matrix at $q=0$ including -the non-analytic terms, you need to calculate effective charges by specifying -option \texttt{epsil=.true.} to \phx. This is however not possible (because -not physical!) for metals (i.e. any system subject to a broadening). - -At $q=0$, use program \texttt{dynmat.x} to calculate the correct LO-TO -splitting, IR cross sections, and to impose various forms of ASR. -If \phx\ was instructed to calculate Raman coefficients, -\texttt{dynmat.x} will also calculate Raman cross sections -for a typical experimental setup. -Input documentation in the header of \texttt{PH/dynmat.f90}. - -A sample phonon calculation is performed in Example 02. - -\subsection{Calculation of interatomic force constants in real space} - -First, dynamical matrices are calculated and saved for a suitable uniform -grid of q-vectors (only those in the Irreducible Brillouin Zone of the -crystal are needed). Although this can be done one q-vector at the time, a -simpler procedure is to specify variable \texttt{ldisp=.true.} and to set -variables \texttt{nq1}, \texttt{nq2}, \texttt{nq3} to some suitable -Monkhorst-Pack grid, that will be automatically generated, centered at $q=0$. -Do not forget to specify \texttt{epsil=.true.} in the input data of -\phx\ if you want the correct TO-LO splitting in polar -materials. - -Second, code \texttt{q2r.x} reads the dynamical matrices produced in the -preceding step and Fourier-transform them, writing a file of Interatomic Force -Constants in real space, up to a distance that depends on the size of the grid -of q-vectors. Input documentation in the header of \texttt{PH/q2r.f90}. - -Program \texttt{matdyn.x} may be used to produce phonon modes and -frequencies at any q using the Interatomic Force Constants file as input. -Input documentation in the header of \texttt{PH/matdyn.f90}. - -For more details, see Example 06. - -\subsection{Calculation of electron-phonon interaction coefficients} - -The calculation of electron-phonon coefficients in metals is made difficult -by the slow convergence of the sum at the Fermi energy. It is convenient to -use a coarse k-point grid to calculate phonons on a suitable wavevector grid; -a dense k-point grid to calculate the sum at the Fermi energy. The calculation -proceeds in this way: -\begin{enumerate} -\item a scf calculation for the dense k-point grid (or a scf calculation -followed by a non-scf one on the dense k-point grid); specify -option \texttt{la2f=.true.} to \pwx\ in order to save a file with -the eigenvalues on the dense k-point grid. The latter MUST contain -all k and k+q grid points used in the subsequent electron-phonon -calculation. All grids MUST be unshifted, i.e. include $k=0$. -\item a normal scf + phonon dispersion calculation on the coarse k-point -grid, specifying option \texttt{elph=.true.}. and the file name where -the self-consistent first-order variation of the potential is to be -stored: variable \texttt{fildvscf}). -The electron-phonon coefficients are calculated using several -values of Gaussian broadening (see \texttt{PH/elphon.f90}) because this quickly -shows whether results are converged or not with respect to the k-point grid -and Gaussian broadening. -\item Finally, you can use \texttt{matdyn.x} and \texttt{lambda.x} -(input documentation in the header of \texttt{PH/lambda.f90}) -to get the $\alpha^2F(\omega)$ function, the electron-phonon coefficient -$\lambda$, and an estimate of the critical temperature $T_c$. -\end{enumerate} -For more details, see Example 07. - -\subsection{Distributed Phonon calculations} -A complete phonon dispersion calculation can be quite long and -expensive, but it can be split into a number of semi-independent -calculations, using options \texttt{start\_q}, \texttt{last\_q}, -\texttt{start\_irr}, \texttt{last\_irr}. An example on how to -distribute the calculations and collect the results can be found -in \texttt{examples/GRID\_example}. Reference:\\ -{\it Calculation of Phonon Dispersions on the GRID using Quantum - ESPRESSO}, - R. di Meo, A. Dal Corso, P. Giannozzi, and S. Cozzini, in - {\it Chemistry and Material Science Applications on Grid Infrastructures}, - editors: S. Cozzini, A. Lagan\`a, ICTP Lecture Notes Series, - Vol. 24, pp.165-183 (2009). - \section{Post-processing} There are a number of auxiliary codes performing postprocessing tasks such @@ -3373,570 +3154,4 @@ 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. -\subsection{ph.x errors} - -\paragraph{ph.x stops with {\em error reading file}} -The data file produced by \pwx\ is bad or incomplete or produced -by an incompatible version of the code. -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. - -\paragraph{ph.x mumbles something like {\em cannot recover} or {\em error - reading recover file}} -You have a bad restart file from a preceding failed execution. -Remove all files \texttt{recover*} in \texttt{outdir}. - -\paragraph{ph.x says {\em occupation numbers probably wrong} and - continues} You have a -metallic or spin-polarized system but occupations are not set to -\texttt{'smearing'}. - -\paragraph{ph.x does not yield acoustic modes with zero frequency at $q=0$} -This may not be an error: the Acoustic Sum Rule (ASR) is never exactly -verified, because the system is never exactly translationally -invariant as it should be. The calculated frequency of the acoustic -mode is typically less than 10 cm$^{-1}$, but in some cases it may be -much higher, up to 100 cm$^{-1}$. The ultimate test is to diagonalize -the dynamical matrix with program \texttt{dynmat.x}, imposing the ASR. If you -obtain an acoustic mode with a much smaller $\omega$ (let us say -$< 1 \mbox{cm}^{-1}$ ) -with all other modes virtually unchanged, you can trust your results. - -''The problem is [...] in the fact that the XC -energy is computed in real space on a discrete grid and hence the -total energy is invariant (...) only for translation in the FFT -grid. Increasing the charge density cutoff increases the grid density -thus making the integral more exact thus reducing the problem, -unfortunately rather slowly...This problem is usually more severe for -GGA than with LDA because the GGA functionals have functional forms -that vary more strongly with the position; particularly so for -isolated molecules or system with significant portions of "vacuum" -because in the exponential tail of the charge density a) the finite -cutoff (hence there is an effect due to cutoff) induces oscillations -in rho and b) the reduced gradient is diverging.''(info by Stefano de -Gironcoli, June 2008) - -\paragraph{ph.x yields really lousy phonons, with bad or negative - frequencies or wrong symmetries or gross ASR violations} -Possible reasons -\begin{itemize} -\item if this happens only for acoustic modes at $q=0$ that should - have $\omega=0$: Acoustic Sum Rule violation, see the item before - this one. -\item wrong data file read. -\item wrong atomic masses given in input will yield wrong frequencies - (but the content of file fildyn should be valid, since the force - constants, not the dynamical matrix, are written to file). -\item convergence threshold for either SCF (\texttt{conv\_thr}) or phonon - calculation (\texttt{tr2\_ph}) too large: try to reduce them. -\item maybe your system does have negative or strange phonon - frequencies, with the approximations you used. A negative frequency - signals a mechanical instability of the chosen structure. Check that - the structure is reasonable, and check the following parameters: -\begin{itemize} -\item The cutoff for wavefunctions, \texttt{ecutwfc} -\item For USPP: the cutoff for the charge density, \texttt{ecutrho} -\item The k-point grid, especially for metallic systems. -\end{itemize} -\end{itemize} -Note that "negative" frequencies are actually imaginary: the negative -sign flags eigenvalues of the dynamical matrix for which $\omega^2 < -0$. - -\paragraph{{\em Wrong degeneracy} error in star\_q} -Verify the q-vector for which you are calculating phonons. In order to -check whether a symmetry operation belongs to the small group of $q$, -the code compares $q$ and the rotated $q$, with an acceptance tolerance of -$10^{-5}$ (set in routine \texttt{PW/eqvect.f90}). You may run into trouble if -your q-vector differs from a high-symmetry point by an amount in that -order of magnitude. - -\section{Frequently Asked Questions (FAQ)} - -\subsection{General} - -If you search information on \qe, the best starting point is the web site -\texttt{html://www.quantum-espresso.org}. See in particular the -links ``learn'' for documentation, ``contacts'' if you need -somebody to talk with. The mailing list \texttt{pw\_forum} is -the typical place where to ask questions about \qe. - -%More FAQS: -% how/where to submit problems -% whom to contact for which problem (download, web, qeforge, -% mailing list, bug, help ...) -% how to contact maintainers -% how to submit a bug report -% which hardware for QE - -\subsection{Installation} - -Most installation problems have obvious origins and can be solved by reading -error messages and acting accordingly. Sometimes the reason for a failure -is less obvious. In such a case, you should look into -Sec.\ref{Sec:Installation}, and into the \texttt{pw\_forum} archive to -see if a similar problem (with solution) is described. If you get -really weird error messages during installation, look for them with -your preferred Internet search engine (such as Google): very often you -will find an explanation and a workaround. - -\paragraph{What Fortran compiler do I need to compile \qe?} - -Any non-buggy, or not-too-buggy, fortran-95 compiler should work, -with minimal or no changes to the code. \configure may not -be able to recognize your system, though. - -\paragraph{Why is \configure\ saying that I have no fortran compiler?} - -Because you haven't one (really!); or maybe you have one, but it is not -in your execution path; or maybe it has been given an unusual name by your -system manager. Install a compiler if you have none; if you have one, fix -your execution path, or define an alias if it has a strange name. -Do not pass an executable with the path as an argument to \configure, -as in e.g. \texttt{./configure F90=/some/strange/f95}: it doesn't work. - -\paragraph{Why is \configure\ saying that my fortran compiler doesn't work?} - -Because it doesn't work (really!); more exactly, \configure\ has tried -to compile a small test program and didn't succeed. Your compiler may not be -properly installed. For Intel compiler on PC's: you may have forgotten to run -the required initialization script for the compiler. See also above. - -\paragraph{\configure\ doesn't recognize my system, what should I do?} - -If compilation/linking works, never mind; otherwise, try to supply a suitable -supported architecture, or/and manually edit the \texttt{make.sys} file. -Detailed instructions in Sec.\ref{Sec:Installation}. - -\paragraph{Why doesn't \configure\ recognize that I have a parallel machine?} - -You need a properly configured complete parallel environment. If any piece -is missing, \configure\ will revert to serial compilation. -Detailed instructions in Sec.\ref{Sec:Installation}. - -\paragraph{Compilation fails with {\em internal error}, what should I do?} - -Any message during compilation saying something like {\em internal compiler -error} -and the like means that your compiler is buggy. You should report the problem -to the compiler maker -- especially if you paid real money for it. -Sometimes reducing the optimization level, or rearranging the code in a -strategic place, will make the problem disappear. In other cases you -will need to move to a different compiler, or to a less buggy version -(or buggy in a different way that doesn't bug you) of the same compiler. - -\paragraph{Compilation fails at linking stage: {\em symbol ... not found}} -If the missing symbols (i.e. routines that are called but not found) -are in the code itself: most likely the fortran-to-C conventions used -in file \texttt{include/c\_defs.h} are not appropriate. Edit this file -and retry. - -If the missing symbols are in external libraries (BLAS, LAPACK, FFT, -MPI libraries): -there is a name mismatch between what the compiler expects and what the -library provides. See Sec.\ref{Sec:Installation}). - -If the missing symbols aren't found anywhere either in the code or in the -libraries: they are system library symbols. i) If they are called by external -libraries, you need to add a missing system library, or to use a different -set of external libraries, compiled with the same compiler you are using. -ii) If you are using no external libraries and still getting missing symbols, -your compiler and compiler libraries are not correctly installed. - -\paragraph{Compilation works but the executable doesn't start because -{\em shared libraries ... not found}} -This is a frequent problem with MKL libraries. You need to set some -environment variables telling the system where the shared libraries are. -See the documentation by Intel that comes with MKL libraries. - -\subsection{Pseudopotentials} - -\paragraph{Can I mix USPP/NCPP/PAW ?} - -Yes, you can (if implemented, of course: a few kinds of calculations -are not available with USPP, a few more are not for PAW). A small -restrictions exists in \cpx, expecting atoms with USPP listed before -those with NCPP, which in turn are expected before local PP's (if any). -A further restriction, that can be overridden, -is that all PP's should be generated with the same XC. -Otherwise, you can mix and match. Note that -it is the hardest atom that determines the cutoff. - -\paragraph{Where can I find pseudopotentials for atom X?} - -First, a general rule: when you ask for a pseudopotential, you should -always specify which kind of PP you need (NCPP, USPP -PAW, full- or scalar-relativistic, for which XC functional, -and, for many elements, with how many electrons in valence). -If you do not find anything suitable in the pseudopotential page -of the web site, or in the links thereof, we have bad news for you: -you have to produce it by yourself. -See \ref{SubSec:pseudo} for more. - -\paragraph{Where can I find pseudopotentials for rare-earth X?} - -Please consider first if DFT is suitable for your system! In many cases, -it isn't (at least ``plain'' DFT: GGA and the like). If you are still -convinced that it is, see above. - -\paragraph{Is there a converter from format XYZ to UPF?} - -What is available (no warranty) is in directory \texttt{upftools/}. -You are most welcome to contribute a new converter. - - -\subsection{Input data} - -A large percentage of the problems reported to the mailing list are -caused by incorrect input data. Before reporting a problem with -strange crashes or strange results, {\em please} have -a look at your structure with XCrySDen. XCrySDen can directly -visualize the structure from both \PWscf\ input data: -\begin{verbatim} - xcrysden --pwi "input-data-file" -\end{verbatim} -and from \PWscf\ output as well: -\begin{verbatim} - xcrysden --pwo "output-file". -\end{verbatim} -Unlike most other visualizers, XCrySDen is periodicity-aware: you can -easily visualize periodically repeated cells. -You are advised to always use XCrySDen to check your input data! - -\paragraph{Where can I find the crystal structure/atomic positions of XYZ?} - -The following site contains a lot of crystal structures: -\texttt{http://cst-www.nrl.navy.mil/lattice}.\\ -"Since this seems to come up often, I'd like to point out that the -American Mineralogist Crystal Structure Database -(\texttt{http://rruff.geo.arizona.edu/AMS/amcsd}) -is another excellent place to -find structures, though you will have to use it in conjunction with -the Bilbao crystallography server (\texttt{http://www.cryst.ehu.es}), -and have some understanding of space groups and Wyckoff positions". -See also: -\texttt{http://cci.lbl.gov/cctbx/index.html}. - -\paragraph{My crystal has a $^4H^{21}_{3_11c}\times \sqrt{\pi}$ -structure, how does this translate to QE input data?} - -There are several different way to specify structures, -described in detail in \texttt{Doc/INPUT\_PW.*}. - -\paragraph{How can I generate a supercell?} - -If you need to create a supercell and are too lazy to create a -small program to translate atoms, you can -\begin{itemize} -\item ``use the 'spacegroup' program in EXCITING package -(http://exciting-code.org) to generate the supercell, -use 'fropho' (http://fropho.sourceforge.net) to check the symmetry'' -(Kun Yin, April 2009) -\item ``use the PHON code: http://www.homepages.ucl.ac.uk/\~{}ucfbdxa/'' -(Eyvaz Isaev, April 2009). -\end{itemize} - -\paragraph{Where can I find the Brillouin Zone/high-symmetry - points/irreps for XYZ?} - -"You might find this web site useful: -\texttt{http://www.cryst.ehu.es/cryst/get\_kvec.html}" (info by Cyrille -Barreteau, nov. 2007). Or else: in textbooks, such as e.g. {\em The -mathematical theory of symmetry in solids} by Bradley and Cracknell. - -\paragraph{Where can I find Monkhorst-Pack grids of k-points?} - -Auxiliary code \texttt{kpoints.x}, found in \texttt{pwtools/} and -produced by \texttt{make tools}, generates uniform grids of k-points -that are equivalent to Monkhorst-Pack grids. - - -\subsection{Parallel execution} - -Effective usage of parallelism requires some basic knowledge on how -parallel machines work and how parallelism is implemented in -\qe. If you have no experience and no clear ideas (or not -idea at all), consider reading Sec.\ref{Sec:para}. - -\paragraph{How do I choose the number of processors/how do I setup my parallel calculation?} - -Please see above. - -\paragraph{Why is my parallel job running in such a lousy way?} - -A frequent reason for lousy parallel performances is a -conflict between MPI parallelization (implemented in \qe) -and the autoparallelizing feature of MKL libraries. Set the -environment variable \texttt{OPEN\_MP\_THREADS} to 1. -See Sec.\ref{Sec:para} for more info. - -\paragraph{Why is my parallel job crashing when reading input data / doing nothing?} - -If the same data work in serial execution, use -\texttt{code -inp input\_file} instead of \texttt{code $<$ input\_file}. -Some MPI libraries do not properly handle input redirection. - -\paragraph{The code stops with an {\em error reading namelist xxxx}} - -Most likely there is a misspelled variable in namelist xxxx. -If there isn't any (have you looked carefully? really?? REALLY???), -beware control characters like DOS control-M: they can confuse -the namelist-reading code. If this happens to the first namelist -to be read (usually "\&CONTROL") in parallel execution, see above. - - - -\subsection{Frequent errors during execution} - -\paragraph{Why is my job crashing with ``segmentation fault''?} - -Possible reasons: too much memory requested; executable or libraries -fitted to a different hardware; code bug; compiler bug. The latter are -typically not reproducible on different architectures or compilers; -code bugs may sometimes be elusive, but typically yield a more -reproducible, pattern of problems. - -Mysterious, unpredictable, erratic errors in parallel execution are -almost always coming from bugs in the compiler or/and in the MPI -libraries and sometimes even from flaky hardware. Sorry, not our fault. - -\paragraph{Why is the code saying {\em Wrong atomic coordinates}?} - -Because they are: two or more atoms in the list of atoms have -overlapping, or anyway too close, positions. Can't you see why? look better -(or use XCrySDen: see above) and remember that the code checks periodic -images as well. - -\paragraph{The code stops with an {\em error in davcio}} - -Possible reasons: disk is full; \texttt{outdir} is not writable for -any reason; you changed some parameter(s) in the input (like -\texttt{wf\_collect}, or the number of processors/pools) without -doing a bit of cleanup in your temporary files; you were running -more than one instance of \pwx\ in the same temporary -directory with the same file names. - -\paragraph{The code stops with a {\em wrong charge} error} - -In most cases: you are treating a metallic system -as if it were insulating. - -\paragraph{The code stops with a mysterious error in IOTK} - -IOTK is a toolkit that reads/writes XML files. There are frequent -reports of mysterious errors with IOTK not finding some variable -in the XML data file. If this error has no obvious explanation -(e.g. the file is properly written and read, the searched variable -is present, etc) and if it appears to be erratic or irreproducible -(e.g. it occurs only with version X of compiler Y), it is almost -certainly due to a compiler bug. Try to reduce optimization level, -or use a different compiler. If you paid real money for your -compiler, complain with the vendor. - -\subsection{Self Consistency} - -\paragraph{What are the units for quantity XYZ?} - -Unless otherwise specified, all \PWscf\ input and output -quantities are in atomic "Rydberg" units, i.e. energies in Ry, lengths -in Bohr radii, etc.. Note that \CP\ uses instead atomic "Hartree" -units: energies in Ha, lengths in Bohr radii. - -\paragraph{Self-consistency is slow or does not converge at all} - -In most cases: your input data is bad, or else your system is metallic -and you are treating it as an insulator. If this is not the case: -reduce \texttt{mixing\_beta} to $\sim 0.3\div 0.1$ or smaller, -try the \texttt{mixing\_mode} value that is more - appropriate for your problem. - - -\paragraph{What is the difference between total and absolute magnetization?} - -The total magnetization is the integral of the magnetization -in the cell: -$$ -M_T = \int (n_{up}-n_{down}) d^3r. -$$ -The absolute magnetization is the integral of the absolute value of -the magnetization in the cell: -$$ -M_A= \int |n_{up}-n_{down}| d^3r. -$$ -In a simple ferromagnetic material they should be equal (except -possibly for an overall sign)`. In simple antiferromagnets (like FeO, -NiO) $M_T$ is zero and $M_A$ is twice the magnetization of each of the -two atoms. (info by Stefano de Gironcoli) - -\paragraph{How can I calculate magnetic moments for each atom?} - -There is no 'right' way of defining the local magnetic moment -around an atom in a multi-atom system. However an approximate way to define -it is via the projected density of states on the atomic orbitals (code -projwfc.x, see example08 for its use as a postprocessing tool). This -code generate many files with the density of states projected on each -atomic wavefunction of each atom and a BIG amount of data on the -standard output, the last few lines of which contain the decomposition -of Lowdin charges on angular momentum and spin component of each atom. - -\paragraph{What is the order of $Y_{lm}$ components in projected - DOS / projection of atomic wavefunctions?} - -See input data documentation for \texttt{projwfc.x}. - -\paragraph{Why is the sum of partial Lowdin charges not equal to - the total charge?} - -"Lowdin charges (as well as other conventional atomic charges) do not -satisfy any sum rule. You can easily convince yourself that this is the -case because the atomic orbitals that are used to calculate them are -arbitrary to some extent. If you like, you can think that the missing -charge is "delocalized" or "bonding" charge, but this would be another -way of naming the conventional (to some extent) character of L\"owdin -charge." (Stefano Baroni, Sept. 2008). - -See also the definition of "spilling parameter": Sanchez-Portal et -al., Sol. State Commun. 95, 685 (1995). The spilling parameter -measures the ability of the basis provided by the pseudo-atomic wfc to -represent the PW eigenstates, by measuring how much of the subspace of -the Hamiltonian eigenstates falls outside the subspace spanned by the -atomic basis. - -\paragraph{I cannot find the Fermi energy, where is it?} - -It is printed in the output. If not, the information on Gaussian smearing, -needed to calculate a sensible Fermi energy, was not provided in input. -In this case, \pwx\ prints instead the highest occupied and lowest -unoccupied levels. If not, the number of bands to be calculated was not -provided in input and \pwx\ calculates occupied bands only. - -\paragraph{What is the reference level for Kohn-Sham energies? -Why do I get positive values for Kohn-Sham levels?} - -The reference level is an ill-defined quantity in calculations -in solids with periodic boundary conditions. Absolute values of -Kohn-Sham eigenvalues are meaningless. - -\paragraph{Why do I get a positive/unexpected/strange value -of the Fermi energy?} - -"The value of the Fermi energy (as well as of any energy, for that -matter) depends of the reference level. What you are referring to is -probably the "Fermi energy referred to the vacuum level" (i.e. -the work function). In order to obtain that, you need to know what the -vacuum level is, which cannot be said from a bulk calculation only" -(Stefano Baroni, Sept. 2008). - -Also note that the current algorithm for Fermi energy calculation -is not able to set the Fermi energy to the textbook value (i.e. in the -middle of the gap) for insulators. You will get an unpredictable -value located somewhere in the gap. - -\paragraph{Why I don't get zero pressure/stress at equilibrium?} -If you make a calculation with fixed cell parameters, you -will never get exactly zero pressure/stress, unless you use the cell -that yields perfect equilibrium for your pseudopotentials, cutoffs, -k-points, etc.. Such cell will anyway be slightly different from the -experimental one. Note however that pressures/stresses in the order of -a few KBar correspond to very small differences in terms of lattice parameters. - -\paragraph{Why do I get different results from vc-relax and from scf -on the same structure?} -First of all, you should verify that the structure is really the same -(hint: compare Ewald energies). Also note that -that: a) the modified kinetic energy functional (often used in -variable-cell calculations) affects the calculated pressure/stress; -b) the PW basis set used in a variable-cell calculations is -determined by the cutoff and the {\em initial} cell gemometry. -If you make a calculation with the final geometry at the same -cutoff, you get slightly different results. The difference should -be small, though, unless you are using a too low cutoff for your -system. Since v.4.3.1, a final scf is performed at the end of the -vc-relax run to check for this. - -\paragraph{Why do I get {\em negative starting charge}?} -Self-consistency requires an initial guess for the charge density in -order to bootstrap the iterative algorithm. This first guess is -usually built from a superposition of atomic charges, constructed from -pseudopotential data. - -More often than not, this charges are a slightly too hard to be -expanded very accurately in PWs, hence some aliasing error -will be introduced. Especially if the unit cell is big and mostly -empty, some local low negative charge density will be produced. - -''This is NOT harmful at all, the negative charge density is handled -properly by the code and will disappear during the self-consistent -cycles'', but if it is very high (let's say more than 0.001*number of -electrons) it may be a symptom that your charge density cutoff is too -low. (L. Paulatto - November 2008) - -\paragraph{How do I calculate the work function?} - -Work function = (average potential in the vacuum) - (Fermi -Energy). The former is estimated in a supercell with the slab -geometry, by looking at the average of the electrostatic potential -(typically without the XC part). See the example in -examples/WorkFct\_example. - -\subsection{ Phonons } - -\paragraph{ Is there a simple way to determine the symmetry of a given -phonon mode?} - -A symmetry analyzer was added in v.3.2 by Andrea Dal Corso. -Other packages that perform symmetry analysis of phonons and normal modes:\\ -ACKJ, ACMI packages: http://www.cpc.cs.qub.ac.uk\\ -ISOTROPY package: http://stokes.byu.edu/iso/isotropy.html.\\ -``The Isotropy Software has a module, called SMODES, that does a full -analysis of phonon modes; including their Raman/Infrared activity. It -uses 'simple' group theory only, and the only input it needs is the -structure: Therefore, it cannot be affected by any lack of convergence -or other errors in the DF(P)T calculation. I suggest always using -SMODES -before- doing a phonon calculation to know what to expect.'' -(info by Turan Birol, dec. 2011) - -\paragraph{I am not getting zero acoustic mode frequencies, why? } - -Because the Acoustic Sum Rule (ASR), i.e. the translational invariance, -is violated in approximated calculations. In PW calculations, -the main and most irreducible violation comes from the discreteness -of the FFT grid. There may be other reasons, though, notably -insufficient convergence: "Recently I found that the parameters -\texttt{tr2\_ph} for the phonons and \texttt{conv\_thr} for the -ground state can affect the quality of the phonon calculation, - especially the "vanishing" frequencies for molecules." -(Info from Katalyn Gaal-Nagy). Anyway: if the nonzero frequencies are -small, you can impose the ASR to the dynamical matrix, usually with -excellent results. - -Nonzero frequencies for rotational modes of a molecule are a fictitious -effect of the finite supercell size, or else, of a less than perfect -convergence of the geometry of the molecule. - -\paragraph{Why do I get negative phonon frequencies? } - -"Negative" frequencies actually are "imaginary" frequencies -($\omega^2<0$). If these occur for acoustic frequencies at Gamma point, -or for rotational modes of a molecule, see above. -In all other cases: it depends. It may be a problem of bad -convergence (see above), or it may signal a real instability. - -\paragraph{Why do I get a message {\em no elec. field with metals}? } - -If you want to calculate the contribution of macroscopic electric -fields to phonons -- a quantity that is well-defined in insulators -only --- you cannot use smearing in the scf calculation, or else the -code will complain. - -\paragraph{How can I calculate Raman/IR coefficients in metals?} - -You cannot: they are well defined only for insulators. - -\paragraph{How can I calculate the electron-phonon coefficients -in insulators?} - -You cannot: the current implementation is for metals only. - \end{document} diff --git a/PHonon/Doc/Makefile b/PHonon/Doc/Makefile index 72a21606d..275ae3e3f 100644 --- a/PHonon/Doc/Makefile +++ b/PHonon/Doc/Makefile @@ -23,9 +23,9 @@ clean: - rm -f $(PDFS) $(AUXS) $(LOGS) $(OUTS) $(TOCS) *~ - rm -rf user_guide/ - rm -f INPUT_*.html INPUT_*.txt INPUT_*.xml + - rm -rf input_xx.xsl - rm -rf ../../Doc/INPUT_PH.* ../../Doc/INPUT_D3.* - user_guide: user_guide.pdf rm -rf user_guide/ latex2html \ @@ -47,15 +47,24 @@ user_guide: user_guide.pdf @echo "" -defs: INPUT_PH.html INPUT_PH.txt INPUT_D3.html INPUT_D3.txt link_on_main_doc -INPUT_PH.html: %.html: %.def - $(HELPDOC) $< +defs: link_input_xx INPUT_PH.txt INPUT_D3.txt INPUT_PH.html INPUT_D3.html link_on_main_doc INPUT_PH.txt: %.txt: %.def $(HELPDOC) $< -INPUT_D3.html: %.html: %.def - $(HELPDOC) $< INPUT_D3.txt: %.txt: %.def $(HELPDOC) $< +link_input_xx: + if test -f ../../doc-def/input_xx.xsl ; then \ + (ln -s ../../doc-def/input_xx.xsl input_xx.xsl) ; \ + else \ + echo ; \ + echo " Sorry, can not find input_xx.xsl html style file !!!" ; \ + echo ; \ + fi + +INPUT_PH.html: %.html: %.def input_xx.xsl + $(HELPDOC) $< +INPUT_D3.html: %.html: %.def input_xx.xsl + $(HELPDOC) $< link_on_main_doc: -( cd ../../Doc ; ln -fs ../PHonon/Doc/INPUT_PH.html . ; \ diff --git a/PHonon/Doc/user_guide.tex b/PHonon/Doc/user_guide.tex index de8243ea1..7ff872c12 100644 --- a/PHonon/Doc/user_guide.tex +++ b/PHonon/Doc/user_guide.tex @@ -1,5 +1,5 @@ \documentclass[12pt,a4paper]{article} -\def\version{4.3.2} +\def\version{5.0.0} \def\qe{{\sc Quantum ESPRESSO}} \usepackage{html} @@ -14,14 +14,10 @@ \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\make{\texttt{make}} \begin{document} @@ -75,21 +71,31 @@ Further documentation, beyond what is provided in this guide, can be found in: You can subscribe to this list, browse and search its archives (links in \texttt{http://www.quantum-espresso.org/contacts.php}). See section \ref{SubSec:Contacts}, ``Contacts'', for more info. - \item the \texttt{Doc/} directory of the \qe\ distribution, - containing a detailed description of input data for most codes + \item the \texttt{Doc/} directory. It + contains a detailed description of the \PHonon\ codes input data in files \texttt{INPUT\_*.txt} and \texttt{INPUT\_*.html}, - plus and a few additional pdf documents + plus and a few additional pdf documents. \item the \qe\ web site:\\ - \texttt{http://www.quantum-espresso.org}; - \item the \qe\ Wiki:\\ - \texttt{http://www.quantum-espresso.org/wiki/index.php/Main\_Page}. + \texttt{http://www.quantum-espresso.org}. \end{itemize} -People who want to contribute to \qe\ should read the -Developer Manual: \texttt{Doc/developer\_man.pdf}. -All trademarks mentioned in this guide belong to their respective owners. +All trademarks mentioned in this guide belong to their respective owners. \\ -\PHonon\ can perform the following types of calculations: + +\PHonon\ has the following directory structure: + +\begin{tabular}{ll} +\texttt{Doc/} & : contains the user\_guide and input data description \\ +\texttt{examples/} & : some running examples \\ +\texttt{PH/} & : source files for phonon calculations (\texttt{ph.x}) + and analysis\\ +\texttt{Gamma/} & : source files for Gamma-only phonon calculation + (\texttt{phcg.x})\\ +\texttt{D3/} & : source files for third-order derivative + calculations (\texttt{d3.x})\\ +\end{tabular} + +The codes availables inside \PHonon\ can perform the following types of calculations: \begin{itemize} \item phonon frequencies and eigenvectors at a generic wave vector, using Density-Functional Perturbation Theory; @@ -99,10 +105,11 @@ All trademarks mentioned in this guide belong to their respective owners. \item third-order anharmonic phonon lifetimes; \item Infrared and Raman (nonresonant) cross section. \end{itemize} -\PHonon\ can be used whenever \PWscf\ can be + +\texttt{ph.x} can be used whenever \PWscf\ can be used, with the exceptions of DFT+U, nonlocal VdW and hybrid functionals. USPP and PAW are not implemented for higher-order response calculations. -See the header of file \texttt{PH/phonon.f90} for a complete and +See the header of file \texttt{PHonon/PH/phonon.f90} for a complete and updated list of what \PHonon\ can and cannot do. Calculations, in the Quasi-Harmonic approximations, of the vibrational free energy can be performed using the \texttt{QHA} package. @@ -110,6 +117,7 @@ free energy can be performed using the \texttt{QHA} package. In the following, the cited affiliation is either the current one or the one where the last known contribution was done. +\section{People} The \PHonon\ package was originally developed by Stefano Baroni, Stefano de Gironcoli, Andrea Dal Corso (SISSA), Paolo Giannozzi, and many others. @@ -121,7 +129,7 @@ We quote in particular: extensions to \PHonon. \end{itemize} -This guide was mostly written by Paolo Giannozzi. +This guide was mostly written by Paolo Giannozzi. \\ We shall greatly appreciate if scientific work done using this code will contain an explicit acknowledgment and the following reference: @@ -138,51 +146,39 @@ http://arxiv.org/abs/0906.2569 \section{Installation} -\subsection{Download} - -\begin{tabular}{ll} -\texttt{PH/} & \PHonon: source files for phonon calculations (\texttt{ph.x}) - and analysis\\ -\texttt{Gamma/} & \PHonon: source files for Gamma-only phonon calculation - (\texttt{phcg.x})\\ -\texttt{D3/} & \PHonon: source files for third-order derivative - calculations (\texttt{d3.x})\\ -\end{tabular} - -\subsection{Prerequisites} -\label{Sec:Installation} - -\subsection{\configure} - +The \PHonon\ package can be downloaded together with the \qe\ distribution. Please follow first +the instructions for downloading and compiling the \qe\ distribution. \subsection{Compilation} -for phonon calculations: +Typing \texttt{make} from the \PHonon\ directory produces the following codes: \begin{itemize} \item \phx\ : Calculates phonon frequencies and displacement patterns, dielectric tensors, effective charges (uses data produced by \pwx). - \item \texttt{dynmat.x}: applies various kinds of Acoustic Sum Rule (ASR), + \item \texttt{PH/dynmat.x}: applies various kinds of Acoustic Sum Rule (ASR), calculates LO-TO splitting at ${\bf q} = 0$ in insulators, IR and Raman cross sections (if the coefficients have been properly calculated), from the dynamical matrix produced by \phx - \item \texttt{q2r.x}: calculates Interatomic Force Constants (IFC) in real space + \item \texttt{PH/q2r.x}: calculates Interatomic Force Constants (IFC) in real space from dynamical matrices produced by \phx\ on a regular {\bf q}-grid - \item \texttt{matdyn.x}: produces phonon frequencies at a generic wave vector + \item \texttt{PH/matdyn.x}: produces phonon frequencies at a generic wave vector using the IFC file calculated by \texttt{q2r.x}; may also calculate phonon DOS, the electron-phonon coefficient $\lambda$, the function $\alpha^2F(\omega)$ -\item \texttt{lambda.x}: also calculates $\lambda$ and $\alpha^2F(\omega)$, +\item \texttt{PH/lambda.x}: also calculates $\lambda$ and $\alpha^2F(\omega)$, plus $T_c$ for superconductivity using the McMillan formula -\item \texttt{make d3} produces \texttt{D3/d3.x}: +\item \texttt{D3/d3.x}: calculates anharmonic phonon lifetimes (third-order derivatives of the energy), using data produced by \pwx\ and \phx\ (USPP and PAW not supported). -\item \texttt{make gamma} produces \texttt{Gamma/phcg.x}: +\item \texttt{Gamma/phcg.x}: a version of \phx\ that calculates phonons at ${\bf q} = 0$ using conjugate-gradient minimization of the density functional expanded to second-order. Only the $\Gamma$ (${\bf k} = 0$) point is used for Brillouin zone integration. It is faster and takes less memory than \phx, but does not support USPP and PAW. \end{itemize} + +Links from the main \qe\ texttt{bin} directory are automatically generated. \subsection{Running examples} \label{SubSec:Examples} @@ -190,15 +186,10 @@ for phonon calculations: \section{Parallelism} \label{Sec:para} -\subsection{Running on parallel machines} -\label{SubSec:para} - \subsection{Parallelization levels} {\bf images}: Processors can then be divided into different "images", -corresponding to a point in configuration space (i.e. to -a different set of atomic positions) for NEB calculations; -to one (or more than one) "irrep" or wave-vector in phonon +corresponding to one (or more than one) "irrep" or wave-vector in phonon calculations. {\bf pools}: When k-point sampling is used, each image group can be @@ -214,29 +205,6 @@ parallelized by distributing planes of the 3D grid in real space to processors (in reciprocal space, it is columns of G-vectors that are distributed to processors). -{\bf task groups}: -In order to allow good parallelization of the 3D FFT when -the number of processors exceeds the number of FFT planes, -data can be redistributed to "task groups" so that each group -can process several wavefunctions at the same time. - -{\bf linear-algebra group}: -A further level of parallelization, independent on -PW or k-point parallelization, is the parallelization of -subspace diagonalization (\pwx) or iterative orthonormalization -(\cpx). Both operations required the diagonalization of -arrays whose dimension is the number of Kohn-Sham states -(or a small multiple). All such arrays are distributed block-like -across the ``linear-algebra group'', a subgroup of the pool of processors, -organized in a square 2D grid. As a consequence the number of processors -in the linear-algebra group is given by $n^2$, where $n$ is an integer; -$n^2$ must be smaller than the number of processors of a single pool. -The diagonalization is then performed -in parallel using standard linear algebra operations. -(This diagonalization is used by, but should not be confused with, -the iterative Davidson algorithm). One can choose to compile -ScaLAPACK if available, internal built-in algorithms otherwise. - {\bf Communications}: Images and pools are loosely coupled and processors communicate between different images and pools only once in a while, whereas @@ -246,29 +214,21 @@ cheap PC clusters) is ok up to 4-8 processors per pool, but {\em fast} communication hardware (e.g. Mirynet or comparable) is absolutely needed beyond 8 processors per pool. -{\bf Choosing parameters}: -To control the number of processors in each group, -command line switches: \texttt{-nimage}, \texttt{-npools}, -\texttt{-ntg}, \texttt{northo} (for \cpx) or \texttt{-ndiag} -(for \pwx) are used. -As an example consider the following command line: -\begin{verbatim} -mpirun -np 4096 ./pw.x -nimage 8 -npool 2 -ntg 8 -ndiag 144 -input my.input -\end{verbatim} -This executes \PWscf\ on 4096 processors, to simulate a system -with 8 images, each of which is distributed across 512 processors. -k-points are distributed across 2 pools of 256 processors each, -3D FFT is performed using 8 task groups (64 processors each, so -the 3D real-space grid is cut into 64 slices), and the diagonalization -of the subspace Hamiltonian is distributed to a square grid of 144 -processors (12x12). +Default values are: \texttt{-nimage 1 -npool 1} ; -Default values are: \texttt{-nimage 1 -npool 1 -ntg 1} ; -\texttt{ndiag} is set to 1 if ScaLAPACK is not compiled, -it is set to the square integer smaller than or equal to half the number -of processors of each pool. - -\paragraph{phonon on grid} +\subsection{Distributed Phonon calculations} +A complete phonon dispersion calculation can be quite long and +expensive, but it can be split into a number of semi-independent +calculations, using options \texttt{start\_q}, \texttt{last\_q}, +\texttt{start\_irr}, \texttt{last\_irr}. An example on how to +distribute the calculations and collect the results can be found +in \texttt{examples/GRID\_example}. Reference:\\ +{\it Calculation of Phonon Dispersions on the GRID using Quantum + ESPRESSO}, + R. di Meo, A. Dal Corso, P. Giannozzi, and S. Cozzini, in + {\it Chemistry and Material Science Applications on Grid Infrastructures}, + editors: S. Cozzini, A. Lagan\`a, ICTP Lecture Notes Series, + Vol. 24, pp.165-183 (2009). \section{Using \PHonon} @@ -324,7 +284,7 @@ splitting, IR cross sections, and to impose various forms of ASR. If \phx\ was instructed to calculate Raman coefficients, \texttt{dynmat.x} will also calculate Raman cross sections for a typical experimental setup. -Input documentation in the header of \texttt{PH/dynmat.f90}. +Input documentation in the header of \texttt{PHonon/PH/dynmat.f90}. A sample phonon calculation is performed in Example 02. @@ -343,13 +303,11 @@ materials. Second, code \texttt{q2r.x} reads the dynamical matrices produced in the preceding step and Fourier-transform them, writing a file of Interatomic Force Constants in real space, up to a distance that depends on the size of the grid -of q-vectors. Input documentation in the header of \texttt{PH/q2r.f90}. +of q-vectors. Input documentation in the header of \texttt{PHonon/PH/q2r.f90}. Program \texttt{matdyn.x} may be used to produce phonon modes and frequencies at any q using the Interatomic Force Constants file as input. -Input documentation in the header of \texttt{PH/matdyn.f90}. - -For more details, see Example 06. +Input documentation in the header of \texttt{PHonon/PH/matdyn.f90}. \subsection{Calculation of electron-phonon interaction coefficients} @@ -370,48 +328,14 @@ grid, specifying option \texttt{elph=.true.}. and the file name where the self-consistent first-order variation of the potential is to be stored: variable \texttt{fildvscf}). The electron-phonon coefficients are calculated using several -values of Gaussian broadening (see \texttt{PH/elphon.f90}) because this quickly +values of Gaussian broadening (see \texttt{PHonon/PH/elphon.f90}) because this quickly shows whether results are converged or not with respect to the k-point grid and Gaussian broadening. \item Finally, you can use \texttt{matdyn.x} and \texttt{lambda.x} -(input documentation in the header of \texttt{PH/lambda.f90}) +(input documentation in the header of \texttt{PHonon/PH/lambda.f90}) to get the $\alpha^2F(\omega)$ function, the electron-phonon coefficient $\lambda$, and an estimate of the critical temperature $T_c$. \end{enumerate} -For more details, see Example 07. - -\subsection{Distributed Phonon calculations} -A complete phonon dispersion calculation can be quite long and -expensive, but it can be split into a number of semi-independent -calculations, using options \texttt{start\_q}, \texttt{last\_q}, -\texttt{start\_irr}, \texttt{last\_irr}. An example on how to -distribute the calculations and collect the results can be found -in \texttt{examples/GRID\_example}. Reference:\\ -{\it Calculation of Phonon Dispersions on the GRID using Quantum - ESPRESSO}, - R. di Meo, A. Dal Corso, P. Giannozzi, and S. Cozzini, in - {\it Chemistry and Material Science Applications on Grid Infrastructures}, - editors: S. Cozzini, A. Lagan\`a, ICTP Lecture Notes Series, - Vol. 24, pp.165-183 (2009). - -\section{Performances} - -\subsection{Execution time} - - -\subsection{Memory requirements} - -A typical self-consistency or molecular-dynamics run requires a maximum -memory in the order of $O$ double precision complex numbers, where -$$ O = m M N + P N + p N_1 N_2 N_3 + q N_{r1} N_{r2} N_{r3}$$ -with $m, p, q$ = small factors; all other variables have the same meaning as -above. Note that if the $\Gamma-$point only ($k=0$) is used to sample the -Brillouin Zone, the value of N will be cut into half. - -The memory required by the phonon code follows the same patterns, with -somewhat larger factors $m, p, q$. - -\subsection{File space requirements} \section{Troubleshooting} @@ -492,56 +416,4 @@ $10^{-5}$ (set in routine \texttt{PW/eqvect.f90}). You may run into trouble if your q-vector differs from a high-symmetry point by an amount in that order of magnitude. -\section{Frequently Asked Questions} - -\paragraph{ Is there a simple way to determine the symmetry of a given -phonon mode?} - -A symmetry analyzer was added in v.3.2 by Andrea Dal Corso. -Other packages that perform symmetry analysis of phonons and normal modes:\\ -ISOTROPY package: http://stokes.byu.edu/iso/isotropy.html\\ -ACKJ, ACMI packages: http://www.cpc.cs.qub.ac.uk. - -\paragraph{I am not getting zero acoustic mode frequencies, why? } - -Because the Acoustic Sum Rule (ASR), i.e. the translational invariance, -is violated in approximated calculations. In PW calculations, -the main and most irreducible violation comes from the discreteness -of the FFT grid. There may be other reasons, though, notably -insufficient convergence: "Recently I found that the parameters -\texttt{tr2\_ph} for the phonons and \texttt{conv\_thr} for the -ground state can affect the quality of the phonon calculation, - especially the "vanishing" frequencies for molecules." -(Info from Katalyn Gaal-Nagy). Anyway: if the nonzero frequencies are -small, you can impose the ASR to the dynamical matrix, usually with -excellent results. - -Nonzero frequencies for rotational modes of a molecule are a fictitious -effect of the finite supercell size, or else, of a less than perfect -convergence of the geometry of the molecule. - -\paragraph{Why do I get negative phonon frequencies? } - -"Negative" frequencies actually are "imaginary" frequencies -($\omega^2<0$). If these occur for acoustic frequencies at Gamma point, -or for rotational modes of a molecule, see above. -In all other cases: it depends. It may be a problem of bad -convergence (see above), or it may signal a real instability. - -\paragraph{Why do I get a message {\em no elec. field with metals}? } - -If you want to calculate the contribution of macroscopic electric -fields to phonons -- a quantity that is well-defined in insulators -only --- you cannot use smearing in the scf calculation, or else the -code will complain. - -\paragraph{How can I calculate Raman/IR coefficients in metals?} - -You cannot: they are well defined only for insulators. - -\paragraph{How can I calculate the electron-phonon coefficients -in insulators?} - -You cannot: the current implementation is for metals only. - \end{document}