quantum-espresso/Doc/refman.tex

\documentclass[12pt,a4paper]{article}
 \def\version{3.1.1}

 \usepackage{epsfig}
 \usepackage{html}
  %\def\htmladdnormallink#1#2{#1}

\begin{document} 

\author{}
\date{}
\title{
  % PWscf and Democritos logos, raise the latter to align
  \epsfig{figure=pwscf,width=4cm}\hfill%
  \raisebox{0.5cm}{\epsfig{figure=democritos,width=8cm}}
  \vspace{1.5cm}
  \\
  % title
  \huge Developer's Guide and Reference Manual for Quantum-ESPRESSO
       v.\version
}
\maketitle

\tableofcontents

\clearpage

\section{Introduction}

\subsection{Who should read (and who should {\em write}) this guide}

The audience of this guide is everybody who wants to:
\begin{itemize}
  \item know how Quantum-ESPRESSO works, including its internals
  \item modify/customize/add/extend/improve/clean up Quantum-ESPRESSO
  \item know how to read data produced by Quantum-ESPRESSO
\end{itemize}
The same category of people should also {\em write} this guide, of course.

\subsection{Who may read this guide but will not necessarily
profit from it}

People who want to know about the capabilities of Quantum-ESPRESSO,
or who want just to use Quantum-ESPRESSO, should read the User's Guide, 
coming with the Quantum-ESPRESSO distribution.

People who want to know about the methods or the physics
behind Quantum-ESPRESSO should read the relevant literature. The
following references are chosen for their completeness.

\begin{itemize}
\item Density-functional Theory (DFT) and Density-Functional Perturbation
Theory (DFPT), in general: 
\medskip \\
\emph{Density Functional Theory of Atoms and Molecules}, 
R.G. Parr and W. Yang,
Oxford University Press, New York (1989).\\
\emph{Density Functional Theory},
R.M. Dreizler and E.K.U. Gross,
Springer-Verlag, Berlin (1990) (more formal).\\
\emph{Phonons and related crystal properties from density-functional
  perturbation theory},
S. Baroni, S. de Gironcoli, A. Dal Corso, and P. Giannozzi,
Rev. Mod. Phys. \textbf{73}, 515--562 (2001).

\item Plane-Wave (PW) pseudopotential (PP) method:
\medskip \\
  \emph{Pseudopotential methods in condensed matter applications},
  W.E. Pickett,Computer Phys. Reports \textbf{9}, 115 (1989).\\
  \emph{Iterative minization techniques for ab-initio total-energy 
    calculations: molecular dynamics and conjugate gradient},
  M.C. Payne, M.P. Teter, D.C. Allen, T.A. Arias, and J.D. Joannopoulos,
  Rev. Mod. Phys. \textbf{64}, 1045 (1992).

\item Car-Parrinello (CP), first-principles Molecular Dynamics (MD) method:
\medskip \\
  D. Marx, J. Hutter,
  in \emph{Modern Methods and Algorithms of Quantum Chemistry},
  p.301--449,
  John von Neumann Institute for Computing, FZ J\"ulich (2000).\\
  \emph{A parallel and modular deformable cell Car-Parrinello code},
  C. Cavazzoni, G.L. Chiarotti,
  Computer Phys. Commun. \textbf{123}, 56 (1999). \\
  \emph{First-principle molecular dynamics with ultrasoft pseudopotentials:
  Parallel implementation and application to extended bioinorganic systems},
  P. Giannozzi, F. de Angelis, R. Car, J. Chem. Phys. \textbf{120}, 5903 (2004)
  (\htmladdnormallink%
  {\texttt{http://web1.sns.it/\~{}giannozz/Papers/JCP\_57.pdf}}%
  {http://web1.sns.it/~giannozz/Papers/JCP_57.pdf}).

\item Variable-cell MD: 
\medskip \\
  \emph{Invariant molecular-dynamics approach to structural phase
    transitions}, M. Wentzcovitch, Phys. Rev. B \textbf{44}, 2358-2361 
  (1991).\\
   \emph{First-principle constant-pressure molecular dynamics},
   M. Bernasconi \emph{et al.}, J. Phys. Chem. Solids \textbf{56}, 501 (1995).

\item Advanced Topics: Nudged Elastic Band (NEB) and Strings Methods
\medskip \\
  \emph{A dimer method for finding saddle points on high dimensional 
    potential surfaces using only first derivatives}, G. Henkelman and 
    H. J{\'o}nsson, J. Chem. Phys. \textbf{111}, 7010 (1999).\\
  \emph{String method for the study of rare events}, W.E \emph{et al.},
  Phys. Rev. B \textbf{66}, 052301 (2002).\\
  \emph{First-principles string molecular dynamics: An efficient approach
    for finding chemical reaction pathways}, Y. Kanai \emph{et al.},
  J. Chem. Phys. \textbf{121}, 3359 (2004).\\
  {\em Finding transition states for crystalline solid-solid phase 
    transformations}, K. J. Caspersen, E. A. Carter, 
  PNAS \textbf{102}, no.19, 6738-43 (2005).
\item Advanced Topics: Metadynamics
\medskip \\
  \emph{Reconstructing the Density of States by History-Dependent 
  Metadynamics}, C. Micheletti, A. Laio, and M. Parrinello,
  Phys. Rev. Lett. \textbf{92}, 170601 (2004).
\end{itemize}

% Online tutorials, lecture notes, etc:
%
% \texttt{http://ocw.mit.edu/OcwWeb/Materials-Science-and-Engineering/3-320Spring-2005/LectureNotes/index.htm}

\subsection{How to Contribute to Quantum-ESPRESSO}

You can contribute to a better Quantum-ESPRESSO by
\begin{itemize}
\item answering other people's questions on the mailing list
  (correct answers are strongly preferred to wrong ones).
\item 
  suggesting changes: note however that suggestions requiring a
  significant amount of work are welcome only if accompanied by
  implementation or by a promise of future implementation
  (fulfilled promises are strongly preferred to forgotten ones)
\item 
  porting to new/unsupported architectures or configurations:
  see the users' guide and the files \texttt{README.install}, 
  \texttt{README.configure}.
  You shouldn't need new preprocessing flags (see Sect.\ref{preproc}):
  those already existing should be sufficient, but if in case, 
  look into the header of file \texttt{include/f\_defs.h}
\item
  pointing out bugs in the software and in the documentation
  (reports of real bugs are strongly preferred to reports of
  nonexistent bugs). A bug report should include enough information
  to reproduce it: typically, version number, hardware/software
  combination(s) for which the problem arises, whether it is 
  reproducible or erratic, whether it happens in serial or parallel 
  execution or both, and, most important, an input and output 
  exhibiting such behavior (fast to execute if possible). The error
  message alone is usually not a sufficient piece of information
\item
  adding new features to the code. If you like to have something added
  to Quantum-ESPRESSO, contact the developers.
  Unless there are technical reasons not to include your changes,
  we will try to make you happy (no warranty that we will actually succeed)
\end{itemize}
  If your changes are straightforward, it will be sufficient to send 
  the modified file(s), or patches, to the developers.

For extensive changes, the ideal procedure is as follows:
\begin{itemize}
   \item download the current CVS version (see Sec.\ref{cvs})
    and work on that version
   \item when you are happy with your modified version, make a copy of it,
    then update your copy with \texttt{cvs update}
  \item if you get no conflicts and everything is still working, you have
    won. Send the modified files to the developers.
  \item if you get conflicts, or if the updated code doesn't work any
    longer, you haven't yet won. Look into the conflicting section:
    in most cases conflicts are trivial (format changes, white spaces) 
    or easily solved (the part of the code you were modifying has
    been moved to another place, for instance). Sometimes, somebody
    else has done changes that are incompatible with yours during the
    same period. Look into the ChangeLog (use the script \texttt{cvs2cl.pl}
    to get an updated ChangeLog) to understand what may have happened.
    Use \texttt{cvs update -D}{\em date} to update to the CVS version 
    at date {\em date}:
    this may be useful if you suspect that the incompatibile change 
    happened after date {\em date}.
    CVS versions can be ``tagged"; tags are visible with 
    \texttt{cvs status -v}. Use \texttt{cvs update -r}{\em tag} 
    to update to the CVS version with tag {\em tag}.
    In all cases, use \texttt{cvs update -A} to revert to the last version.
\end{itemize}

Developers can be reached at the e-mail address \texttt{pwscf@pwscf.org}.
Since this may change in the future, check the web site for 
Quantum-ESPRESSO: 
\htmladdnormallink{\texttt{http://www.quantum-espresso.org/}}%
{http://www.quantum-espresso.org/}, or for
PWscf: \htmladdnormallink{\texttt{http://www.pwscf.org}}%
{http://www.pwscf.org/License.txt}.

\section{Structure of the distribution}

\subsection{Contents of the various directories}

\subsubsection{Modules}

\subsubsection{Sources}

\subsubsection{Utilities}

\subsubsection{Libraries}

\subsection{Installation mechanism}

The code contains C-style preprocessing directives. 
There are two ways to do preprocessing of fortran files:
\begin{itemize}
  \item directly with the fortran compiler, if supported;
  \item by first pre-compiling with the C preprocessor {\tt cpp}.
\end{itemize}
In the first case, one needs to specify in the ``make.sys" file the
fortran compiler option that tells the compiler 
to pre-process first. In the second case, one needs to 
specify the C precompiler and options (if needed) in ``make.sys".

\subsection{Adding new directories or routines}

\section{Algorithms}

\subsection{Diagonalization}

\subsection{Self-consistency}

\subsection{Structural optimization}

\subsection{Symmetrization}

\subsection{...}

\section{Structure of the code}

\subsection{Modules and global variables}

\subsection{Meaning of the most important variables}

\subsection{Conventions for indices}

\subsection{Preprocessing}

\label{preproc}
The code contains C-style preprocessing directives. Most
fortran compilers directly support them; some don't, and
preprocessing is ``hand-made" by the makefile using the C
preprocessor {\tt cpp}.

The C preprocessor may:
\begin{itemize}
  \item
    assign a value to a given expression. For instance, command
    \texttt{\#define THIS that}, or the option in the command line:
    \texttt{-DTHIS=that}, will replace all occurrence of \texttt{THIS}
    with \texttt{that}.
    ``Preprocessed" variables are usually, but not always nor 
    necessarily,  written in uppercase.
  \item
    execute conditional expressions such as
\begin{verbatim}
  #ifdef expression
    ...code A...
  #else
    ...code B...
  #endif
\end{verbatim}
    If ``expression" is defined (with a \texttt{\#define} command or
    from the command line with option \texttt{-Dexpression}), then
    \texttt{...code A...} is sent to output; otherwise
    \texttt{...code B...} is sent to output.
  \item
    include file (command \texttt{\#include})
  \item
    expand macros (command \texttt{\#define})
\end{itemize}
The file \texttt{include/defs.h.README} contains a list of definitions
that are used in the code.

\subsection{Performance issues}
\subsection{Portability issues}

\section{Parallelization}

In parallel execution, PW starts N independent
processes (no more than one per processor!)
that communicate via calls to MPI libraries. 
Each process has its own set of variables and knows 
nothing about other processes' variables. Variables 
that take little memory are replicated, those that 
take a lot of memory (wavefunctions, G-vectors, R-space
grid) are distributed.

Beware: replicated calculations may either be performed independently
on each processor, or performed on one processor and broadcast to all
others. The first approach requires less programming, but it is unsafe:
in principle all processors should yield exactly the same results, if 
they work on the same data, but sometimes they don't (depending on the 
machine, compiler, and libraries). Even a tiny difference in the last
significant digit can eventually cause serious trouble if allowed to 
build up, especially when a replicated check is performed (in which 
case the code may "hang" if the check yields different results on 
different processors). Never assume that the value of a variable 
produced by replicated calculations is exactly the same on all processors: 
when in doubt, broadcast the value calculated on a specific processor.

\subsection{Paradigms}
\subsection{Implementation}
\subsubsection{Data distribution}
\subsubsection{Parallel fft}
\subsubsection{...}

\section{File Formats}
\subsection{Data file(s)}
\subsection{Restart files}

\section{Modifying/adding/extending Quantum-ESPRESSO}
\subsection{Hints, Caveats, Do's and Dont's}
\begin{itemize}
\item
Before doing anything, inquire whether it is already there,
or under development.
\item 
Before starting writing code, inquire whether you can reuse
code that is already available in the distribution. Avoid 
redundancy: the only bug-free software line is the one that 
doesn't exist.
\item When you make some change:
\begin{itemize}
\item Check that are not spoiling other people's work.
In particular, search the distribution for codes using the routine 
or module you are modifying and change its usage or its calling 
sequence everywhere.
\item Do not forget to add/update documentation and examples as well.
\item Do not forget that your change must work on many different 
combinations of hardware and software, in both serial and parallel
execution.
\end{itemize}
\end{itemize}
\subsection{Programming style (or lack of it)}

Guidelines for developers:
\begin{itemize}
\item preprocessing options should be capitalized and start with two
underscores. Examples: \texttt{\_\_AIX}, \texttt{\_\_LINUX}, ...
\item fortran commands should be capitalized: \texttt{CALL something( )}
\item variable names should be lowercase: \texttt{foo = bar/2}
\item use \texttt{KIND=DP} to define the type of real and complex variables
(\texttt{DP} is defined in module ``kinds'')
\item all constants should be defined to be of kind \texttt{DP}.
Preferred syntax: \texttt{0.0\_dp}.
\item conversions should be explicitely indicated. For conversions to real
(including taking the real part of a complex number), use \texttt{DBLE}.
For conversions to complex, use \texttt{CMPLX}. For the complex conjugate,
use \texttt{CONJG}. For the imaginary part, use \texttt{AIMAG}.
Note that \texttt{CMPLX} is preprocessed by \texttt{f\_defs.h} 
and performs an explicit cast:
\begin{verbatim}
    #define CMPLX(a,b)  cmplx(a,b,kind=DP)
\end{verbatim}
This implies that 1) \texttt{f\_defs.h} must be included whenever a
\texttt{CMPLX} is present, 2) \texttt{CMPLX} should stay in a single line, 
3) \texttt{DP} must be defined.
\item indent \texttt{DO}'s and  \texttt{IF}'s with three white spaces
(editors like emacs will do this automatically for you)
\item do not write crammed code: leave spaces, insert empty separation
lines
\item comments (introduced by \texttt{!}) should be used to explain 
what is not obvious from the code, not to repeat what is already 
evident. Obscure comments serve no purpose.
\item do not use machine-dependent extensions or sloppy syntax.
Standard f90 requires that a \& is needed both at end of line 
AND at the beginning of continuation line if there is a ' ' 
or " " spanning two lines. Some compilers do not complain
if the latter \& is missing, others do.
\end{itemize}

\subsection{Adding or modifying input variables}

New input variables should be added to \texttt{Modules/input\_parameters.f90}, 
and then copied to the code internal variables in the \texttt{input.f90}
subroutine. The namelists and cards parsers are in :
\texttt{Modules/read\_namelists.f90} and \texttt{Modules/read\_cards.f90}.
Files \texttt{input\_parameters.f90}, \texttt{read\_namelists.f90},
\texttt{read\_cards.f90} are shared by all codes, while each code 
has its own version of \texttt{input.f90}  used to copy input values 
into internal variables ).

EXAMPLE:
suppose you need to add a new input variable called ``pippo"
to the namelist control, then:

\begin{verbatim}
1) add pippo to the input_parameters.f90 file containing the namelist
control

              INTEGER :: pippo = 0
              NAMELIST / control / ....., pippo
              remember: always set an initialization value!

2) add pippo to the control_default subroutine (contained in module
read_namelists.f90 )

              subroutine control_default( prog )
              ...
              IF( prog == 'PW' ) pippo = 10
              ...
              end subroutine

              this routine set the default value for pippo,
              that could vary with the code

3) add pippo to the control_bcast subroutine (contained in module 
read_namelists.f90 )

                subroutine control_bcast( )
                ...
                call mp_bcast( pippo )
                ...
                end subroutine
\end{verbatim}

\section{Using CVS}

\label{cvs}
The package is available read-only using anonymous CVS. Developers 
may have read-write access if needed. Note that the latest
(development) version may not work properly, and sometimes not 
even compile properly. Use at your own risk.

CVS (Concurrent Version System) is a software that allows many
developers to work and maintain a single copy of a software in
a central location (repository). It is installed by default on
most Unix machines, or otherwise it can be very easily installed:
see {\tt http://www.cvshome.org}. For a tutorial, see:\\
{\tt http://www.loria.fr/\~{}molli/cvs/cvs-tut/cvs\_tutorial\_toc.html}

\subsection{Anonymous CVS}

Define environment variables:
\begin{verbatim}
  setenv CVS_RSH ssh
  setenv CVSROOT :pserver:cvsanon@democritos.sissa.it:/home/cvs
\end{verbatim}
(tcsh/csh) or
\begin{verbatim}
  export CVS_RSH=ssh
  export CVSROOT=:pserver:cvsanon@democritos.sissa.it:/home/cvs
\end{verbatim}
(sh/bash/ksh). Then do:
\begin{verbatim}
   cvs login
\end{verbatim}
and enter password: \texttt{cvsanon}

\subsection{Read/Write CVS}

Define environmental variables:
\begin{verbatim}
 setenv CVS_RSH ssh
 setenv CVSROOT :ext:your-account@democritos.sissa.it:/home/cvs
\end{verbatim}
(tcsh/csh) or
\begin{verbatim}
 export CVS_RSH=ssh
 export CVSROOT=:ext:your account@democritos.sissa.it:/home/cvs
\end{verbatim}
(sh/bash). You need to have an account defined on democritos.sissa.it.
You will be prompted for your password at each cvs operation.

\subsection{CVS operations}

For the first code download:
\begin{verbatim}
   cvs co espresso
\end{verbatim}
The code appears in directory \texttt{espresso/}.
To update the code to the current version:
\begin{verbatim}
   cvs update -d
\end{verbatim}
in the directory containing the distribution. It is possible 
to download the version at a given date, or corresponding to 
a given ``tag'' (set by the developers, usually just before 
extensive changes or at public releases).

When updating, you should get lines looking like
\begin{verbatim}
  cvs server: Updating Modules
  P Modules/Makefile
  U Modules/control_flags.f90
\end{verbatim}
where P means ``patched", U means ``updated" (a new file is added); or
\begin{verbatim}
  M PW/Makefile
\end{verbatim}
where M means ``locally modified" (i.e., wrt the CVS repository
version); or
\begin{verbatim}
  cvs server: FPMD/control.f90 is no longer in the repository
\end{verbatim}
if a file has been meanwhile deleted, or moved, or renamed; but no lines like
\begin{verbatim}
  C Somedir/SomeFile
  cvs server: conflict while updating Somedir/SomeFile
\end{verbatim}
This means that somebody else has modified the same parts of the code 
that you have locally modified; conflicting files will contain lines like
\begin{verbatim}
  >>>>>>>>>>>>>
     something
  ============
     something else
  <<<<<<<<<<<<<
\end{verbatim}
If this happen, you must edit the file manually to remove conflicts.

You can compare your local copy with any version of the repository
using 
\begin{verbatim}
  cvs diff -r tag
\end{verbatim}
or with the repository at a given date using 
\begin{verbatim}
  cvs diff -D date
\end{verbatim}
You can also compare two different versions/snapshots of the repository, 
by specifying two different tags or dates. Options \texttt{-i} (ignore case),  
\texttt{-w} (ignore all white spaces), \texttt{-b} (ignore changes in 
the number of white spaces) may be useful to distinguish true changes
from ``esthetic'' changes such as indentation.

READ-WRITE ACCESS ONLY:

In order to save your changes to the repository, use
{\tt cvs commit}. In order to add a file, first use
{\tt cvs add}, then {\tt cvs commit}. In order to delete
a file, first use {\tt cvs delete}, then {\tt cvs commit}.
In order to rename a file, delete the file with the old
name, add the file with the new name.

In order to add a new directory (let us say {\tt dir/}, 
and if you have the permission to do so:
\begin{itemize}
\item create directory {\tt dir/}; do {\tt cvs add dir} (this
will create the CVS subdirectory in the new directory {\tt dir/})
\item 
copy all files into {\tt dir/}, then from inside {\tt dir/}, add files:
{\tt cvs add *.f90 Makefile} (for instance)
\item
{\tt cvs commit} will save the new directory
\end{itemize}

\end{document}