2004-09-06 23:46:21 +08:00
|
|
|
\documentclass[12pt,a4paper]{article}
|
|
|
|
\def\version{2.1}
|
|
|
|
|
|
|
|
\usepackage{epsfig}
|
|
|
|
\usepackage{html}
|
|
|
|
%\def\htmladdnormallink#1#2{#1}
|
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\begin{document}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
|
|
|
\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
|
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\tableofcontents
|
2004-09-06 23:46:21 +08:00
|
|
|
|
|
|
|
\clearpage
|
2004-08-10 00:35:51 +08:00
|
|
|
|
|
|
|
\section{Introduction}
|
|
|
|
|
|
|
|
\subsection{Who should read this guide (and who should {\em write} it)}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
|
|
|
The intended audience of this guide is everybody who wants to:
|
2004-08-10 00:35:51 +08:00
|
|
|
\begin{itemize}
|
2004-09-06 23:46:21 +08:00
|
|
|
\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
|
2004-08-10 00:35:51 +08:00
|
|
|
\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,
|
2004-09-06 23:46:21 +08:00
|
|
|
or who want just to use PWscf, should read the User's Guide,
|
2004-08-10 00:35:51 +08:00
|
|
|
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.
|
2004-09-06 23:46:21 +08:00
|
|
|
\medskip
|
2004-08-10 00:35:51 +08:00
|
|
|
|
2004-09-06 23:46:21 +08:00
|
|
|
\noindent
|
2004-08-10 00:35:51 +08:00
|
|
|
Density-functional Theory (DFT), general:
|
2004-09-06 23:46:21 +08:00
|
|
|
\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}
|
2004-08-10 00:35:51 +08:00
|
|
|
Density-Functional Perturbation Theory (DFPT), phonons:
|
2004-09-06 23:46:21 +08:00
|
|
|
\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}
|
2004-08-10 00:35:51 +08:00
|
|
|
Plane-Wave (PW) pseudopotential (PP) method:
|
2004-09-06 23:46:21 +08:00
|
|
|
\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}
|
2004-08-10 00:35:51 +08:00
|
|
|
|
|
|
|
\section{Structure of the distribution}
|
|
|
|
|
|
|
|
\subsection{Contents of the various directories}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsubsection{Modules}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsubsection{Sources}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsubsection{Utilities}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsubsection{Libraries}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsection{Installation mechanism}
|
|
|
|
|
|
|
|
The code contains C-style preprocessing directives.
|
|
|
|
There are two ways to do preprocessing of fortran files:
|
|
|
|
\begin{itemize}
|
2004-09-06 23:46:21 +08:00
|
|
|
\item directly with the fortran compiler, if supported;
|
|
|
|
\item by first pre-compiling with the C preprocessor {\tt cpp}.
|
2004-08-10 00:35:51 +08:00
|
|
|
\end{itemize}
|
|
|
|
The file "make.rules" select what is done.
|
|
|
|
In the first case, the file install/Make.rules\_nocpp is copied
|
|
|
|
to make.rules.
|
|
|
|
In the second case, the file install/Make.rules\_cpp is
|
|
|
|
copied to make.rules. This is done by the script "configure".
|
|
|
|
|
|
|
|
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}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsection{Diagonalization}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsection{Self-consistency}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsection{Structural optimization}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsection{Symmetrization}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsection{...}
|
|
|
|
|
|
|
|
\section{Structure of the code}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsection{Modules and global variables}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsection{Meaning of the most important variables}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\subsection{Conventions for indices}
|
2004-09-06 23:46:21 +08:00
|
|
|
|
2004-08-10 00:35:51 +08:00
|
|
|
\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}.
|
|
|
|
|
2004-09-06 23:46:21 +08:00
|
|
|
The C preprocessor may:
|
2004-08-10 00:35:51 +08:00
|
|
|
\begin{itemize}
|
2004-09-06 23:46:21 +08:00
|
|
|
\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})
|
2004-08-10 00:35:51 +08:00
|
|
|
\end{itemize}
|
2004-09-06 23:46:21 +08:00
|
|
|
The file \texttt{include/defs.h.README} contains a list of definitions
|
|
|
|
that are used in the code.
|
2004-08-10 00:35:51 +08:00
|
|
|
|
|
|
|
\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.
|
|
|
|
|
|
|
|
\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}
|
|
|
|
|
2004-09-06 23:46:21 +08:00
|
|
|
Define environment variables:
|
2004-08-10 00:35:51 +08:00
|
|
|
\begin{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
setenv CVS_RSH ssh
|
|
|
|
setenv CVSROOT :pserver:cvsanon@democritos.sissa.it:/home/cvs
|
2004-08-10 00:35:51 +08:00
|
|
|
\end{verbatim}
|
|
|
|
(tcsh/csh) or
|
|
|
|
\begin{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
export CVS_RSH=ssh
|
|
|
|
export CVSROOT=:pserver:cvsanon@democritos.sissa.it:/home/cvs
|
2004-08-10 00:35:51 +08:00
|
|
|
\end{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
(sh/bash/ksh). Then do:
|
2004-08-10 00:35:51 +08:00
|
|
|
\begin{verbatim}
|
|
|
|
cvs login
|
|
|
|
\end{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
and enter password: \texttt{cvsanon}
|
2004-08-10 00:35:51 +08:00
|
|
|
|
|
|
|
\subsection{Read/Write CVS}
|
|
|
|
|
|
|
|
Define environmental variables:
|
|
|
|
\begin{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
setenv CVS_RSH ssh
|
|
|
|
setenv CVSROOT :ext:your-account@democritos.sissa.it:/home/cvs
|
2004-08-10 00:35:51 +08:00
|
|
|
\end{verbatim}
|
|
|
|
(tcsh/csh) or
|
|
|
|
\begin{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
export CVS_RSH=ssh
|
|
|
|
export CVSROOT=:ext:your account@democritos.sissa.it:/home/cvs
|
2004-08-10 00:35:51 +08:00
|
|
|
\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}
|
2004-09-06 23:46:21 +08:00
|
|
|
The code appears in directory \texttt{espresso/}.
|
2004-08-10 00:35:51 +08:00
|
|
|
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}
|
2004-09-06 23:46:21 +08:00
|
|
|
cvs server: Updating Modules
|
|
|
|
P Modules/Makefile
|
|
|
|
U Modules/control_flags.f90
|
2004-08-10 00:35:51 +08:00
|
|
|
\end{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
where P means "patched", U means "updated" (a new file is added); or
|
2004-08-10 00:35:51 +08:00
|
|
|
\begin{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
M PW/Makefile
|
2004-08-10 00:35:51 +08:00
|
|
|
\end{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
where M means "locally modified" (i.e., wrt the CVS repository
|
|
|
|
version); or
|
2004-08-10 00:35:51 +08:00
|
|
|
\begin{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
cvs server: FPMD/control.f90 is no longer in the repository
|
2004-08-10 00:35:51 +08:00
|
|
|
\end{verbatim}
|
|
|
|
if a file has been meanwhile deleted, or moved, or renamed; but no lines like
|
|
|
|
\begin{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
C Somedir/SomeFile
|
|
|
|
cvs server: conflict while updating Somedir/SomeFile
|
2004-08-10 00:35:51 +08:00
|
|
|
\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}
|
2004-09-06 23:46:21 +08:00
|
|
|
>>>>>>>>>>>>>
|
|
|
|
something
|
|
|
|
============
|
|
|
|
something else
|
|
|
|
<<<<<<<<<<<<<
|
2004-08-10 00:35:51 +08:00
|
|
|
\end{verbatim}
|
2004-09-06 23:46:21 +08:00
|
|
|
If this happen, you must edit the file manually to remove conflicts.
|
2004-08-10 00:35:51 +08:00
|
|
|
|
|
|
|
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}
|