mirror of https://gitlab.com/QEF/q-e.git
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:
parent
745a96197a
commit
9f81ddc657
|
@ -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}
|
||||
|
|
|
@ -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 . ; \
|
||||
|
|
|
@ -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}
|
||||
|
|
Loading…
Reference in New Issue