scnc
/
quantum-espresso
mirror of https://gitlab.com/QEF/q-e.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
marsamos 2012-01-16 14:41:40 +00:00
parent 745a96197a
commit 9f81ddc657
3 changed files with 79 additions and 983 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

799
Doc/user_guide.tex
View File

@ -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}

21
PHonon/Doc/Makefile
View File

@ -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 . ; \

242
PHonon/Doc/user_guide.tex
View File

@ -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,45 +146,31 @@ 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
@ -184,21 +178,18 @@ for phonon calculations:
not support USPP and PAW.
\end{itemize}
Links from the main \qe\ texttt{bin} directory are automatically generated.
\subsection{Running examples}
\label{SubSec:Examples}
\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}