Skip to content
Snippets Groups Projects
Commit 6ff5d7e3 authored by Christoph Grüninger's avatar Christoph Grüninger
Browse files

[handbook] External libraries and building documentation. 

Clean up a bunch of outdated stuff.


git-svn-id: svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk@12637 2fb0f335-1f38-0410-981e-8018bf24f1b0
parent cb418c5a
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/handbook/install.tex
+ 58
− 96
View file @ 6ff5d7e3
......@@ -170,7 +170,10 @@ $ svn checkout --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de
\end{lstlisting}
\paragraph{Hints for \Dumux-Developers}
If you also want to actively participate in the development of \Dumux, you can apply either for full developer
If you also want to actively participate in the development of \Dumux, you can allways send patches
to the Mailing list.
To get more involved, you can apply either for full developer
access or for developer access on certain parts of \Dumux. Granted developer access means that
you are allowed to commit own code and that you can access the \texttt{dumux-devel} module.
This enhances \texttt{dumux} by providing maybe unstable code from the developer group.
......@@ -197,95 +200,47 @@ Software like a compiler or even a standard library
changes at times. But, for example, a certain release of a software component that we depend on,
may not reflect that change and thus it has to be modified.
In the dynamic developing process of software which depends on other modules it is not always feasible
to adapt everything to the most recent version of each module. Consequently, patches exist or
they will be brought into existence. They may fix problems with a certain module
of a certain release without introducing too much structural change. It can also happen
that a release gets amendments (updates) and a formerly useful patch becomes obsolete.
to adapt everything to the most recent version of each module. They may fix problems with a certain module
of a certain release without introducing too much structural change.
\Dumux contains patches and documentation about their usage and application within the
directory \texttt{dumux/patches}.
Please check the README file in that directory for recent information.
In general, a patch can be applied as follows
(the exact command or the used parameters may be slightly different).
We include here an example of a patch against the 1.0.1 release of \Dune-PDELab
We include here an example of a patch against \Dune-PDELab 1.1
for the \Dumux release 2.3 for purpose of showing how a patch gets applied.
\begin{lstlisting}[style=Bash]
$ # make sure you are in DUNE-Root
$ cd dune-pdelab
$ patch -p0 < ../dumux/patches/pdelab-1.0.1.patch
$ patch -p0 < ../dumux/patches/pdelab-1.1.0.patch
\end{lstlisting}
It can be removed by
\begin{lstlisting}[style=Bash]
$ path -p0 -R < ../dumux/patches/pdelab-1.0.1.patch
$ path -p0 -R < ../dumux/patches/pdelab-1.1.0.patch
\end{lstlisting}
The \texttt{checkout-dumux} script also applies patches, if not explicitly requested not to do so.
\section{Building doxygen documentation} \label{sec:build-doxy-doc}
Doxygen documentation is done by especially formatted comments integrated in the source code, which can get extracted by the program
\texttt{doxygen}. Beside extracting these comments, \texttt{doxygen} builds up a web-browsable code structure documentation
like class hierarchy of code displayed as graphs, see \cite{DOXYGEN-HP}.
Building the doxygen documentation of a module is done as follows, provided the program \texttt{doxygen} is installed:
Set in building options the \texttt{--enable-doxygen} switch.
This is either accomplished by adding it in \texttt{dunecontrol} options-file to \texttt{CONFIGURE\_FLAGS}, or by adding
it to \texttt{dunecontrol}'s command-line-argument \texttt{--configure-opts}.
After running \texttt{dunecontrol} enter in module's root directory the subdirectory \texttt{doc/doxygen}.
You then run the command \texttt{doxygen} within that directory. Point your web browser to the file
The Doxygen documentation of a module can be built, provided the program \texttt{doxygen} is installed,
by running \texttt{dunecontrol}, entering the module's root directory, and execute \texttt{make doc}.
Point your web browser to the file
\texttt{module-root-directory/doc/doxygen/html/index.html} to read the generated documentation.
All \Dune-modules that are used here except \texttt{dune-grid-howto} including also \texttt{dumux} contain some doxygen documentation, which can be extracted as
described in the following lines. The external library UG has also a \texttt{doc/doxygen} directory for building its doxygen documentation.
\begin{lstlisting}[style=Bash]
$ # change before next command your directory to DUNE-Root
$ cd dumux/doc/doxygen
$ doxygen
$ firefox html/index.html
\end{lstlisting}
\section{Building documentation of other \Dune modules}
If the \texttt{--enable-documentation} switch has been set in the configure flags of
\texttt{dunecontrol}, this does not necessarily mean that for every
\Dune module the documentation is being built.
However, at least Makefiles for building the documentation are generated.
Provided you run \texttt{dunecontrol} with the option above,
it should be possible to build documentation if available.
Check the targets you can build in \texttt{module-root-directory/doc/Makefile.am}.
For example in the module \texttt{dune-istl} you can build the documentation \texttt{istl.pdf} by typing the following into the console, when you are in the \Dune-Root:
\begin{lstlisting}[style=Bash]
$ # change before next command your directory to DUNE-Root
$ cd dune-istl/doc
$ make istl.pdf
\end{lstlisting}
Or for module \texttt{dune-grid-howto} the documentation can be build by:
\begin{lstlisting}[style=Bash]
$ # change before next command your directory to DUNE-Root
$ cd dune-grid-howto/doc
$ make grid-howto.pdf
\end{lstlisting}
This applies for \Dumux, too. Rebuilding the handbook can be done as follows:
\begin{lstlisting}[style=Bash]
$ cd dumux/doc/handbook
$ make dumux-handbook.pdf
\end{lstlisting}
%As of writing this, no general method of building documentation contained in \Dune's modules is known to the author.
%Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details.
\Dune module the documentation is automatically being built. Run the target \texttt{make doc}
in the module's root directory to generate to build the module's documentation.
\section{External libraries and modules} \label{sec:external-modules-libraries}
The libraries described below provide additional functionality but are not generally required to run \Dumux.
If you are going to use an external library check the information provided on the \Dune website \cite{DUNE-EXT-LIB}.
If you are going to use an external \Dune module the website on external modules \cite{DUNE-EXT-MOD} can be helpful.
......@@ -297,46 +252,61 @@ Make sure that it uses the same library as \Dune when configuring the external l
In the following list, you can find some external modules and external libraries, and some more libraries and tools which are prerequisites for their use.
\begin{itemize}
\item \textbf{ALBERTA}: External library for use as grid. Adaptive multi Level finite element toolbox using Bisectioning refinement and Error control by Residual Techniques for scientific Applications. Building it requires a Fortran compiler \texttt{gfortran}. Download: \texttt{\url{http://www.alberta-fem.de}}. The most recent version works without patches and also in combination with SuperLU, \texttt{\url{http://www.ians.uni-stuttgart.de/nmh/downloads/alberta/snapshots/v3/}}.
\item \textbf{ALBERTA}: External grid library. Adaptive multi-level grid manager using bisectioning
refinement and error control by residual techniques for scientific Applications. Requires a Fortran
compiler like \texttt{gfortran}. Download: \texttt{\url{http://www.alberta-fem.de}} or for version 3.0
\texttt{\url{http://www.mathematik.uni-stuttgart.de/fak8/ians/lehrstuhl/nmh/downloads/alberta/}}.
\item \textbf{ALUGrid}: External library for use as grid. ALUGrid is built by a \Cplusplus compiler like \texttt{g++}. If you want to build a parallel version, you will need \texttt{MPI}. It was successfully run with \texttt{openmpi}. The parallel version needs also a graph partitioner, such as \texttt{METIS}. It was run successfully in combination with \Dune using \texttt{METIS}. \\
Download: \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}
\item \textbf{ALUGrid}: External grid library. ALUGrid is built by a \Cplusplus compiler like \texttt{g++}.
If you want to build a parallel version, you will need \texttt{MPI}. It was successfully run with \texttt{openmpi}.
The parallel version needs also a graph partitioner, such as \texttt{ParMETIS}.
Download: \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}
\item \textbf{\Dune-multidomaingrid} and \textbf{\Dune-multidomaingrid}: External modules which offer a meta grid that
has different sub-domains. Each subdomain can have a local operator that is coupled by a coupling condition. They are
used for multi-physics approaches or domain decomposition methods.
(\texttt{\url{http://users.dune-project.org/projects/dune-multidomaingrid}}
and \texttt{\url{http://users.dune-project.org/projects/dune-multidomain}})
\item \textbf{\Dune-PDELab}: External module to write more easily discretizations. PDELab provides already a sound number of discretizations like FEM or discontinuous Galerkin methods. Download: \texttt{\url{http://www.dune-project.org/pdelab}}.
\item \textbf{PARDISO}: External library for solving linear equations. The package PARDISO is a thread-safe, high-performance, robust, memory efficient and easy to use software for solving large sparse symmetric and asymmetric linear systems of equations on shared memory multiprocessors. The precompiled binary can be downloaded after personal registration from the PARDISO website (\texttt{\url{http://www.pardiso-project.org}}).
\item \textbf{SuperLU}: External library for solving linear equations. SuperLU is a general purpose library for the direct solution of large, sparse, non-symmetric systems of linear equations. Be aware that the version 4.3 is not supported by \Dune prior to 2.1.0. SuperLU requires BLAS and a linker problem might occur with the BLAS version provided with the SuperLU library. The best solution is to make sure that a BLAS version is installed on the computer. Note that \textbf{GotoBLAS2} might cause problems with new processor types.\\ (\texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}).
\item \textbf{UG}: External library for use as grid. UG is a toolbox for Unstructured Grids: For \Dumux it has to be build by GNU buildsystem and a \Cplusplus compiler. That's why \Dune specific patches need applied before use. Building it makes use of the tools \texttt{lex}/\texttt{yacc} or the GNU variants \texttt{flex}/\texttt{bison}.
has different sub-domains. Each sub-domain can have a local operator that is coupled by a coupling condition. They are
used for multi-physics approaches or domain decomposition methods. Download:
\texttt{\url{http://users.dune-project.org/projects/dune-multidomaingrid}}
and \texttt{\url{http://users.dune-project.org/projects/dune-multidomain}}
\item \textbf{\Dune-PDELab}: External module to write more easily discretizations. PDELab provides
a sound number of discretizations like FEM or discontinuous Galerkin methods.
Download: \texttt{\url{http://www.dune-project.org/pdelab}}
\item \textbf{PARDISO}: External library for solving linear equations. The package PARDISO is a thread-safe,
high-performance, robust, memory efficient and easy to use software for solving large sparse symmetric
and asymmetric linear systems of equations on shared memory multiprocessors. The precompiled binary
can be downloaded after personal registration from the PARDISO website: \texttt{\url{http://www.pardiso-project.org}}
\item \textbf{SuperLU}: External library for solving linear equations. SuperLU is a general purpose
library for the direct solution of large, sparse, non-symmetric systems of linear equations.
Download: \texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}
\item \textbf{UG}: External library for use as grid. UG is a toolbox for unstructured grids, it is not
available under a open source license. \Dune provides patches which have to be applied before
compiling UG. Building it makes use of the tools \texttt{lex}/\texttt{yacc} or the GNU variants of
\texttt{flex}/\texttt{bison}.
\end{itemize}
The following are dependencies of some of the used libraries. You will need them depending on which modules of \Dune and which external libraries you use.
\begin{itemize}
\item \textbf{MPI}: The parallel version of \Dune and also some of the external dependencies need MPI when they are going to be built for parallel computing. \texttt{Openmpi} version $\geqslant$ 1.4.2 and \texttt{MPICH} in a recent version have been reported to work.
\item \textbf{lex/yacc} or \textbf{flex/bison}: These are quite common developing tools, code generators for lexical analyzers and parsers. This is a prerequisite for UG.
\item \textbf{BLAS}: Alberta and SuperLU make use of BLAS. Thus install GotoBLAS2, ATLAS, non-optimized BLAS or BLAS provided by a chip manufacturer. Take care that the installation scripts select the intended version of BLAS. See \texttt{\url{http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms}}.
\item \textbf{MPI}: The parallel version of \Dune and also some of the external dependencies need MPI
when they are going to be built for parallel computing. \texttt{OpenMPI} and \texttt{MPICH} in a recent
version have been reported to work.
\item \textbf{GotoBLAS2}: This is an optimized version of BLAS. It covers not all processors of the day, but quite a broad range. Its license is now very open. A Fortran compiler like \texttt{gfortran} is needed to compile it.\\
Available by \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}.
\item \textbf{lex/yacc} or \textbf{flex/bison}: These are quite common developing tools, code generators
for lexical analyzers and parsers. This is a prerequisite for UG.
\item \textbf{METIS} and \textbf{ParMETIS}: This are dependencies of ALUGrid, if run in parallel.
\item \textbf{BLAS}: Alberta and SuperLU make use of BLAS. Thus install GotoBLAS2, ATLAS, non-optimized BLAS
or BLAS provided by a chip manufacturer. Take care that the installation scripts select the intended
version of BLAS.
\item \textbf{Compilers}: Beside \texttt{g++} it has been reported that \Dune was successfully built with \texttt{Clang++} from the LLVM project and the Intel \Cplusplus compiler.
C and Fortran compiler is needed for some external libraries. As code of different compilers is linked together they have to be be compatible with each other. A good choice is the GNU compiler suite \texttt{gcc}, \texttt{g++} and \texttt{gfortran}.
\item \textbf{METIS} and \textbf{ParMETIS}: This are dependencies of ALUGrid and can be used with UG, if run in parallel.
\item \textbf{libgomp}: External libraries, such as ALUGrid, can make use of OpenMP when used together with METIS. For that purpose it can be necessary to install the \texttt{libgomp} library.
% http://openmp.org/
\item \textbf{Compilers}: Beside \texttt{g++}, \Dune can be built with Clang from the LLVM project and
Intel \Cplusplus compiler. C and Fortran compilers are needed for some external libraries. As code of
different compilers is linked together they have to be be compatible with each other. A good choice
is the GNU compiler suite consisting of \texttt{gcc}, \texttt{g++} and \texttt{gfortran}.
\end{itemize}
\section{Hints for Users from IWS}
......@@ -353,7 +323,7 @@ $ svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external
\end{lstlisting}
This directory \texttt{external} contains a script to install external libraries, such as
ALBERTA, ALUGrid, UG, METIS and GotoBLAS2:
ALBERTA, ALUGrid, UG, and METIS:
\begin{lstlisting}[style=Bash]
$ cd external
$ ./installExternal.sh all
......@@ -369,11 +339,3 @@ The libraries are then compiled within that directory and are not installed in a
A \Dune build may need to know their location. Thus, one may have to refer to them as options for \texttt{dunecontrol},
for example via the options file \texttt{my-debug.opts}. Make sure you compile the required external libraries before
you run \texttt{dunecontrol}.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% End:
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment