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

First set of updates to the developer's manual 

git-svn-id: http://qeforge.qe-forge.org/svn/q-e/trunk/espresso@12309 c92efa57-630b-4861-b058-cf58834340f0
This commit is contained in:
giannozz 2016-04-14 20:35:42 +00:00
parent a528fc89f3
commit 28bb0dbebc
1 changed files with 125 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
Doc/developer_man.tex
View File

@ -1,5 +1,5 @@
\documentclass[12pt,a4paper]{article}
\def\version{5.3}
\def\version{5.4}
\def\qe{{\sc Quantum ESPRESSO}}
\def\qeforge{\texttt{qe-forge.org}}
\textwidth = 17cm
@ -75,15 +75,16 @@ You can contribute to a better \qe, even as an ordinary user, by:
for reporting bugs".
\item Improving the documentation (generic complaints or suggestions
that "there should be this and that" do not qualify as improvements).
\item Suggesting changes: note however that suggestions requiring a
significant amount of work are welcome only if accompanied by
\item Suggesting changes: contact developers at
\texttt{q-e-developers[.at.]qe-forge[.dot.]org} mailing list,
Unless there are technical reasons not to follow your suggestion,
we will try to make you happy. 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 Adding new features to the code. If you like to have something
added to \qe, contact the developers via the
\texttt{q-e-developers[.at.]qe-forge[.dot.]org} mailing list.
Unless there are technical reasons not to include your changes, we
will try to make you happy (no warranty that we will actually succeed).
\item Adding new features to the code: see Sect.\ref{SubSec:BeDev},
"How to become a developer", in particular Sect.\ref{SubSec:Contrib},
"Contributing new developments".
\end{itemize}
\newpage
@ -106,8 +107,8 @@ molecular dynamics on the ground state;
\end{itemize}
\end{itemize}
Note that some libraries are downloaded on demand from the web
during the installation of the core distribution. Then comes a first
outer shell of {\em additional} packages, that can be downloaded and
during the installation of the core distribution. Then comes a
shell of {\em additional} packages, that can be downloaded and
installed from the core distribution using \texttt{make}:
\begin{itemize}
\item \texttt{atomic}: pseudopotential generation
@ -116,43 +117,42 @@ installed from the core distribution using \texttt{make}:
\item \texttt{PWCOND}: ballistic conductance
\item \texttt{XSPECTRA}: calculation of X-Ray spectra
\item \texttt{TDDFPT}: Time-dependent DFPT
\end{itemize}
All these packages use routines from the core distribution.
A second shell of additional packages, also downloaded and installed
on demand from the core distribution, includes
\begin{itemize}
\item \texttt{EPW}: electron-phonon
\item \texttt{GIPAW}: calculation of NMR coefficients and chemical shifts,
\item \texttt{EPW}: electron-phonon (under development,
requires \texttt{PHonon}).
\end{itemize}
The only difference between the ''first'' and ''second'' shell is that
the latter are stored in separate SVN repositories.
In a third shell of additional packages we find
\begin{itemize}
\item \texttt{GWL}: GW calculations using Lanczos chains.
\end{itemize}
This also uses routines from \qe, but it must be separately
downloaded and installed.
All these packages use routines from the core distribution. Note that
\begin{itemize}
\item \texttt{EPW} and \texttt{GWL} require \texttt{PHonon};
\item \texttt{GWL} must be separately downloaded;
\item \texttt{GIPAW} is stored in a separate SVN repository.
\end{itemize}
There is then a shell of {\em external} packages, which typically
read data produced by \qe\ but do not need it to work. Some of them
(notably Yambo and WanT) can be automatically downloaded and installed
from the core distribution using \texttt{make}.
(notably Yambo, Wannier90, WanT) can be automatically downloaded and
installed from the core distribution using \texttt{make}.
Finally there are {\em plugins}: these modify \qe\ packages, adding
new functionalities. The only plugin currently released is Plumed
(metadynamics), but other may come soon.
new functionalities. Currently the following plugins are available:
\begin{itemize}
\item \texttt{Plumed}, v.1.3 only, for metadynamics;
\item \texttt{Environ}, for calculations with a solvent.
\end{itemize}
\section{How to become a developer}
\label{SubSec:BeDev}
If you want to get involved as a developer and contribute serious
or nontrivial stuff (or even simple and trivial stuff), you should
first of all register on \qeforge\ as a developer for the \qe\
project.
first of all register on \qeforge, following the instructions.
\subsection{About \qeforge}
\label{SubSec:qeforge}
{\em Important notice: \qeforge\ will be upgraded in the next months
with new hardware and software. Some of the following pieces of
information may become obsolete.}
\qeforge\ is the portal for \qe\ developers, contributors,
and for anybody else wanting to develop a project in the
@ -169,13 +169,16 @@ you may open your own project, retaining all rights on it
the "projects" page, click on the link "add new project", fill
the form (note that the Unix name given to the project cannot
be modified). You have the choice between a repository using
CVS, SVN, \texttt{git}, plus other choices.
CVS, SVN, \texttt{git}, others. Please avoid CVS
(obsolete), prefer \texttt{git} (it is easier to move the
repository).
You may as well register as a developer
in an existing project: go to the project page, click on
button ''Request to become a developer'' under the ''Activity''
graph on the top of the column at the right, to obtain the permission
from the administrator of the project.
from the administrator of the project (please contact the
project administratior by mail!).
You need to register your SSH keys in order to have read-write
access the repository (if you have such permissions). Generate
@ -207,7 +210,7 @@ for communications among developers and people interested
in the development of \qe. Only registered users can post
but messages from unregistered users are monitored and
approved if relevant.
\item \texttt{q-e-commits}(medium traffic): for automatic
\item \texttt{q-e-commits} (medium traffic): for automatic
commit messages. Note that replies to commit messages go
to the mailing list: in case of doubts or questions or
remarks over a specific commit, feel free to reply.
@ -217,7 +220,7 @@ Everybody is encouraged to explore other capabilities of \qeforge.
All \qe\ developer are {\em strongly} invited to subscribe to the
two mailing lists \texttt{q-e-developers} and \texttt{q-e-commits}.
Those who don't lose i) the opportunity to follow what is going on,
Those who don't, lose i) the opportunity to follow what is going on,
ii) the right to complain if something has gone into a direction
they don't like. Note that subscription to mailing lists is not
automatic when you register: you should subscribe using the links
@ -228,61 +231,91 @@ Please also consider subscribing to the bug tracker: select the
bug is filed.
\subsection{Contributing new developments}
{\em Important notice: starting with release 5.3, there will be important
changes in the development model of \qe. Stay tuned.}
\label{SubSec:Contrib}
Various procedures can be followed to contribute new developments.
It is possible to contribute:
\begin{itemize}
\item a small (or large) piece of code to an existing package; or
\item a small, or large, piece of code to an existing package; or
\item a new package that uses \qe\ as a library; or
\item a ``plugin'' that modifies \qe, adding a new functionality; or
\item a new ``external'' package that just reads data file produced by QE.
\end{itemize}
The ideal procedure depends upon the kind of project you have in
mind. In all cases, you should learn how to use SVN: see Sect.\ref{Sec:SVN},
"Using SVN". The three typical cases are:
The ideal procedure depends upon the kind of project you have in mind.
As a rule: if you plan to release your work in the public release, you
should always keep your work aligned to the current development version
of \qe. This is especially important if your project
\begin{itemize}
\item[a)] If your project involves changes or additions affecting only
a small part of \qe, it is usually convenient to work directly on
the main SVN repository (the "trunk").
\item[b)]
If your project involves major or extensive changes to the core of
\qe, it may be a good idea to make a SVN "branch" and work on it.
Note that your branch will necessarily be public, since the SVN
trunk is public.
\item[c)]
If your project involves a major new addition (e.g. a new package),
or if you do not want it to be public during its development,
it may be a good idea to register it as a new \qeforge\ project
with a separate SVN repository. It is possible to restrict access
to selected \qe\ developers; or to keep it private; or to have
two repositories, one public and one private. It is possible to
have the public repository automatically downloaded into the
SVN copy of \qe\ (see Sect.\ref{SubSec:propedit}).
\item involves major or extensive or even small but critical or numerous
changes to existing \qe\ routines,
\item makes usage of existing (modified or unmodified) \qe\ routines.
\end{itemize}
Modifying the latest stable version is not a good idea. Modifying
an {\em old} stable version is an {\em even worse idea}. New code
based on old versions will invariably be obsolete after a few months,
{\em very} obsolete after a few years. Experience shows that new projects
may take a long time before reaching a public release, and that the
major stumbling block is the alignment to the newer \qe\ distribution.
For case a), you should from time to time update your copy (using command
\texttt{svn update}), verify if changes made meanwhile by other developers
The sole exception is when your changes are either relatively small, or
localized to a small part of \qe, or they are quite independent anyway
from the rest of \qe. In that case, you can just send a patch or the
modified routine(s) to an expert developer who will review it and
take the appropriate steps.
{\em Notice:} the development model of \qe\ has undergone
significant changes between releases 5.3 and 5.4. Since v.5.4, only
package maintainers and a few expert developers are allowed to commit
into the main ("trunk") SVN repository. Only ``safe'' changes can be
committed: the repository should always be at or close to production
status. SVN branches are discouraged: experience shows that too many
branches are never merged.
Due to various \qeforge\ limitations, anonymous SVN access is also disabled.
People who need to access a development version may use the link to the
"Daily Snapshot" on the www.quantum-espresso.org web site.
People who need to stay aligned to the development of \qe may use the official
\texttt{git} mirror, available on \qeforge\ under the project ``qe-private''.
Please apply for an acount on qe-forge if you haven't one
(see Sect.\ref{SubSec:qeforge} for details), contact support[.at.]qe-forge.org
and explain what you need and why. To check out the repository:
\begin{verbatim}
git clone ssh://username@qeforge.qe-forge.org/gitroot/q-e-private
\end{verbatim}
This repository is only for pull operation and it is one way repository,
meaning it is automatically aligned by a script with the SVN repository.
Committing into this repository does not produce a commit in the SVN.
So never commit ;-). See Sect.\ref{Sec:git}, ``Using git'', for more
instructions on how to use \texttt{git}. You should also
register to the q-e-commit@qe-forge.org mailing list in order to better
follow what is going on in the main repository.
If your project involves a major new addition (e.g. a new package),
consider registering it as a new \qeforge\ project, with a separate
SVN or (better) \texttt{git} repository. It is possible to keep the
project private, or to restrict access to selected \qe\ developers.
% or to have two repositories, one public and one private.
% It is also possible to have the public repository automatically
% downloaded into the SVN copy of \qe\ (see Sect.\ref{SubSec:propedit}).
{\em Important:} keep your copy of the distribution aligned to the SVN.
Don't work for years, or even for months, without keeping an eye to
what is going on in the SVN. This is especially true for projects that
are ``tightly bound'' to \qe, that is, use \qe\ code and routines.
Frequently update your copy (using command \texttt{svn update} or
\texttt{git pull}), verify if changes made meanwhile by other developers
conflict with your changes. Conflicts are in most cases easy to solve:
see Sect. \ref{SubSec:Conflicts} for hints on how to
remove conflicts and on how to figure out what went wrong.
Once you are happy with your modified version, you can commit your
changes, or ask one of the expert developers to do this if you do not
feel confident enough.
see Sect. \ref{SubSec:Conflicts} for hints on how to remove conflicts
and on how to figure out what went wrong.
For case b), you should from time to time align your branch with the
trunk. See Sect. \ref{SubSec:Merge} for hints on how to do this.
For case c): if your project is ``loosely coupled'' to \qe, that is,
it just uses the \qe\ installation procedure and/or data files, there
shouldn't be any major problems, since major incompatible changes are
very rare (note however that the files produced by the phonon code
change more frequently). If your project is ``tightly bound'', i.e.
it uses routines from \qe, it is prudent to notify the other
developers.
If instead your project is ``loosely coupled'', that is, it just uses the
\qe\ installation procedure and/or data files, it is less likely to run
into problems, since major incompatible changes are quite rare.
You may still need to verify from time to time that everything keeps
working. though.
\subsection{Hints, Caveats, Do's and Dont's for developers}
@ -293,7 +326,8 @@ page \texttt{www.quantum-espresso.org/road-map}, send a message to
\texttt{q-e-developers}.
\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.
{\em the only bug-free software line is the one that doesn't exist}
(citation adapted from Henry Ford).
\item When you make some changes:
\begin{itemize}
\item Check that are not spoiling other people's work. In particular,
@ -363,13 +397,14 @@ Typically, one should report
the bug
\end{itemize}
The provided input should be simple and quick to execute.
\item If a bug is found in a stable (released) version of \qe, it must
be reported in the \texttt{Doc/release-notes} file.
\item If a bug is found in a stable (released) version of \qe,
he/she who fixes it must report it in the \texttt{Doc/release-notes}
file.
\end{itemize}
\section{Stable releases and development cycle}
Stable releases are labelled as $N.M.p$, where $N$=major, $M$=minor,
$p$=bugfix. The logic goes more or less as follows:
Stable releases (until v.5.4) are labelled as $N.M.p$, where $N$=major,
$M$=minor, $p$=bugfix. The logic goes more or less as follows:
\begin{itemize}
\item {\em Major}: when something really important changes, e.g.
\begin{enumerate}
@ -389,7 +424,8 @@ It may be convenient to make a SVN branch at release $N.M.0$: this allows
to go on with the development while keeping track of bug fixes.
Since release 5.2 (June 20, 2015), stable release are packaged at
fixed dates. The initial schedule is a release every three months.
fixed dates. The initial schedule is a release every three to four months.
Since v.5.4 bugfix releases are no longer packaged.
Releases are stored to \qeforge. Given the size of the complete distribution,
the release is split into a ``core'' distribution and ``add-ons'',
@ -421,7 +457,7 @@ This manual and the user manual have to be updated.
Edit the script \texttt{dev-tools/release.sh} to make tarballs.
\paragraph{Updating web site} After the release has been uploaded to
\paragraph{Updating web site} After the release is uploaded to
\qeforge, the online documentation must be copied to directory
\texttt{/var/www/quantum\_wp\_db/wordpress-3.1.4/wp-content/uploads/Doc}
on the web site (this requires system privileges on the machine hosting
@ -2197,8 +2233,7 @@ The following web page may be useful:
\subsection{Including a repository into the trunk}
\label{SubSec:propedit}
It is possible to download other repositories into the main \qe\ repository.
Currently, this possibility works only for GIPAW (and EPW, which
however is not aligned to the svn version); you need to be authorized
Currently, this possibility works only for GIPAW; you need to be authorized
to access the GIPAW svn, though. From the trunk/ subdirectory
(the one containing espresso/), type ``svn propedit svn:externals espresso''.
An editor will open. Type the name of the subdirectory of ``espresso/''
@ -2206,9 +2241,11 @@ where you want the repository to be downloaded, followed by the address of
the repository, exit (not quit!) the editor. Example:
\begin{verbatim}
GIPAW http://qeforge.qe-forge.org/svn/qe-gipaw/trunk
EPW http://qeforge.qe-forge.org/svn/epw-public/trunk/EPW
\end{verbatim}
\section{Using git}
\label{Sec:git}
\section{Bibliography}
Fortran books: