quantum-espresso/Doc/refman.tex

\documentclass[12pt,a4paper]{article}
 \def\version{2.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 PWscf v.\version
        -- (template)
}
\maketitle

\tableofcontents

\clearpage

\section{Introduction}

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

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

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

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

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

\noindent
Density-functional Theory (DFT), general:
\begin{enumerate}
  \item
    \emph{Density Functional Theory of Atoms and Molecules}, 
    R.G. Parr and W. Yang,
    Oxford University Press, New York (1989).
  \item
    \emph{Density Functional Theory},
    R.M. Dreizler and E.K.U. Gross,
    Springer-Verlag, Berlin (1990) (more formal).
\end{enumerate}
Density-Functional Perturbation Theory (DFPT), phonons:
\begin{enumerate}
  \setcounter{enumi}{2}
  \item
    S. Baroni, S. de Gironcoli, A. Dal Corso, and P. Giannozzi,
    Rev. Mod. Phys. \textbf{73}, 515--562 (2001).
\end{enumerate}
Plane-Wave (PW) pseudopotential (PP) method:
\begin{enumerate}
  \setcounter{enumi}{3}
  \item
    W.E. Pickett,
    Computer Phys. Reports \textbf{9}, 115 (1989)
    (hard to find).
  \item
    M.C. Payne, M.P. Teter, D.C. Allen, T.A. Arias, and
    J.D. Joannopoulos,
    Rev. Mod. Phys. \textbf{64}, 1045 (1992).
\end{enumerate}
Car-Parrinello (CP), first-principles Molecular Dynamics (MD) method:
\begin{enumerate}
  \setcounter{enumi}{5}
  \item
    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).
  \item
    C. Cavazzoni, G.L. Chiarotti,
    Computer Phys. Commun. \textbf{123}, 56 (1999).
  \item
    P. Giannozzi, F. de Angelis, R. Car,
    J. Chem. Phys. \textbf{120}, 5903 (2004)
    (\htmladdnormallink%
     {\texttt{http://www.nest.sns.it/\~{}giannozz/Papers/JCP\_57.pdf}}%
     {http://www.nest.sns.it/~giannozz/Papers/JCP_57.pdf}).
\end{enumerate}

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

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.

\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 PWscf}
\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 van 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, do not forget to check whether you need to make changes 
as well to specialised codes (noncolinear, Gamma-only etc.) that may
use the routine or module you are changing.
\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.
\end{itemize}
\end{itemize}
\subsection{Programming style (or lack of it)}

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.

\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 internals 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}

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.

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}