3_detailedinstall.tex 16.1 KB
 1 Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory  2 3 4 (section \ref{sc:ObtainingSourceCode}). In a second step of the installation, all modules are configured with CMake (section \ref{buildIt}).  5 After the successful installation of \Dumux, we guide you to start a test application,  6 described in section \ref{quick-start-guide}.  7 In section \ref{sec:build-doc}, we explain how to build the \Dumux documentation.  8 Lastly, section \ref{sec:external-modules-libraries} provides details on optional libraries and modules.  Thomas Fetzer committed Jul 09, 2015 9   10 In a technical sense, \Dumux is a module of \Dune.  Thomas Fetzer committed Jul 09, 2015 11 Thus, the installation procedure of \Dumux is the same as that of \Dune.  Sina Ackermann committed Mar 17, 2017 12 Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-HP}.  David Werner committed Jan 17, 2011 13   14   Johannes Hommel committed Dec 18, 2018 15 \section{Obtaining Source Code for \Dune and \Dumux}  16 17 \label{sc:ObtainingSourceCode} The \Dumux release and trunk (developer tree) are based on the most recent  Katharina Heck committed Apr 20, 2020 18 \Dune release 2.7, comprising the core modules \texttt{dune-common}, \texttt{dune-geometry},  19 \texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}.  Beatrix Becker committed Dec 20, 2018 20 For working with \Dumux, these modules are required.  21 All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it  22 23 is done in a typical \Dune installation. We usually name our root directory \texttt{DUMUX}, but an arbitrary name can be chosen.  Timo Koch committed Dec 19, 2018 24 25 Source code files for each \Dune module are contained in their own sub-directory within the root directory. The sub-directories for the modules are named after the module names (depending on how  Beatrix Becker committed Dec 20, 2018 26 the modules were obtained, a version number is added to the module name).  27 28 The name of each \Dune module is defined in the file \texttt{dune.module}, which is in the root directory of the respective module. This should not be changed by the user.  David Werner committed Jan 13, 2011 29   30 In section \ref{sec:prerequisites}, we list some prerequisites for running \Dune and \Dumux.  31 Please check in said paragraph whether you can fulfill them before continuing.  Klaus Mosthaf committed Oct 12, 2010 32   Thomas Fetzer committed Jul 09, 2015 33 \paragraph{Obtaining \Dune and \Dumux from software repositories}  Timo Koch committed Aug 26, 2020 34 35 \Dune and \Dumux use Git for their software repositories. To access them, you need to have a working installation of the version control software Git.  Christoph Grüninger committed Jan 18, 2016 36   Timo Koch committed Aug 26, 2020 37 In the jargon of Git, \emph{cloning a certain software version} means nothing more then fetching  Christoph Grueninger committed Mar 19, 2014 38 a local copy from the software repository and laying it out in the file system.  Kilian Weishaupt committed Sep 20, 2016 39 In addition to the software, some more files for the use of the software revision  Timo Koch committed Aug 26, 2020 40 control system itself are created. (If you have developer access to \Dumux, it is  Christoph Grueninger committed Mar 19, 2014 41 also possible to do the opposite, i.\,e. to load up a modified revision of software  Timo Koch committed Aug 26, 2020 42 into the software repository. This is usually termed as \emph{commit} and \emph{push}.)  David Werner committed Jan 13, 2011 43   Timo Koch committed Aug 26, 2020 44 The download procedure is done as follows:  45 Create a common root directory, named e.g. \texttt{DUMUX} in the lines below.  Thomas Fetzer committed Jul 09, 2015 46 Then, enter the previously created directory and check out the desired modules.  Christoph Grueninger committed Mar 19, 2014 47 As you see below, the check-out uses two different servers for getting the sources,  Christoph Grüninger committed Jan 18, 2016 48 one for \Dune and one for \Dumux.  David Werner committed Jan 14, 2011 49   50 \begin{lstlisting}[style=Bash,escapechar=\%]  51 52 $mkdir DUMUX$ cd DUMUX  Katharina Heck committed Apr 20, 2020 53 54 55 56 57 $git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-common.git$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-geometry.git $git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-grid.git$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-istl.git $git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-localfunctions.git  58 $ git clone -b releases/%\DumuxVersion% https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git  David Werner committed Jan 14, 2011 59 \end{lstlisting}  Bernd Flemisch committed Jul 16, 2010 60   61 62 The newest and maybe unstable developments of \Dune and \Dumux are also provided in these repositories and can be found in the \emph{master} branch. Please check the \Dune website \cite{DUNE-HP} for further information on the \Dune development. We always try to keep up with the latest developments of \Dune.  Katharina Heck committed Apr 20, 2020 63 However, the current \Dumux release is based on the stable 2.7 release and it might not compile without further adaptations using the newest versions of \Dune.  David Werner committed Jan 14, 2011 64   Roman Winter committed Oct 08, 2019 65 \section{Building \Dune and \Dumux}  66 \label{buildIt}  67 Configuring \Dune and \Dumux is done by the shell-command \texttt{dunecontrol}, which is part of the \Dune build system.  68 If you are interested in more details about the build system that is used,  Timo Koch committed Dec 19, 2018 69 they can be found in the \Dune build system documentation\footnote{\url{https://www.dune-project.org/buildsystem/}} and  70 CMake's documentation\footnote{\url{https://cmake.org/documentation/}}.  Beatrix Becker committed Dec 20, 2018 71 If something fails during the execution of \texttt{dunecontrol}, feel free to report it to the \Dune or \Dumux developer mailing list,  Johannes Hommel committed Dec 18, 2018 72 but please include error details.  73   Timo Koch committed Jun 02, 2021 74 75 76 77 78 It is possible to compile \Dumux without explicitly passing options to the build system. However, this will usually not result in the most performant code. A set of default options that will usually work well is provided with \Dumux in a file and can be passed to \texttt{dunecontrol}. The following command will configure \Dune and \Dumux and build all necessary libraries  79 80 \begin{lstlisting}[style=Bash] $# make sure you are in the common root directory  Timo Koch committed Jun 02, 2021 81 $ ./dune-common/bin/dunecontrol --opts=dumux/cmake.opts all  82 83 \end{lstlisting}  Timo Koch committed Jun 02, 2021 84 If you are going to compile with modified options, the following  85 86 87 can be a starting point: \begin{lstlisting}[style=Bash] $# make sure you are in the common root directory  Dennis Gläser committed Dec 19, 2018 88 89 90 $ cp dumux/cmake.opts my-cmake.opts # create a personal version $gedit my-cmake.opts # optional editing the options file$ ./dune-common/bin/dunecontrol --opts=my-cmake.opts all  91 92 \end{lstlisting}  Johannes Hommel committed Dec 18, 2018 93 Sometimes, it is necessary to have additional options which  94 95 are specific to a package set of an operating system or sometimes you have your own preferences.  96 97 98 Feel free to work with your own set of options, which may change over time. The option file, that comes with the distribution, is to be understood more as a starting point for setting up own customization than as something which is fixed.  99 The use of external libraries can make it necessary to add quite many options in an option file.  100 It can be helpful to give your customized option file a unique name, as done above,  101 102 to avoid confusing it with the option files which came out of the distribution.  Johannes Hommel committed Dec 18, 2018 103 \section{The First Run of a Test Application}  104 \label{quick-start-guide}  Timo Koch committed Jun 02, 2021 105 106 107 108  We recommend the "Getting Started" guide on the \Dumux website: \url{https://dumux.org/gettingstarted/}. Nevertheless, here is a brief description of how to run a first application.  Johannes Hommel committed Dec 18, 2018 109 The previous section showed how to install and compile \Dumux. This section  110 shall give a very brief introduction on how to run a first test application and how  Melanie Lipp committed Dec 18, 2018 111 to visualize the first output files.\par  112 All executable files are compiled in the \texttt{build} sub-directories of \Dumux.  Dennis Gläser committed Dec 19, 2018 113 If not specified differently in the options file, this is \texttt{build-cmake} as default.  114 115  \begin{enumerate}  Timo Koch committed Jun 02, 2021 116 \item Enter the folder \texttt{test/porousmediumflow/2p/incompressible} within your build directory.\\ Type \texttt{make test{\_}2p{\_}incompressible{\_}tpfa}  Melanie Lipp committed Dec 18, 2018 117  in order to compile the application\\\texttt{test{\_}2p{\_}incompressible{\_}tpfa}. To run the simulation,  Johannes Hommel committed Dec 18, 2018 118 119 120  type \texttt{./test{\_}2p{\_}incompressible{\_}tpfa params.input} into the console. The added \texttt{params.input} specifies that all  121  important run-time parameters (such as first time step size, end of simulation and location  122  of the grid file) can be found in a text file in the same directory with the  Johannes Hommel committed Dec 18, 2018 123  name \texttt{params.input}.  Beatrix Becker committed Dec 20, 2018 124 125 \item The simulation starts and produces some VTU output files and also a PVD file. The PVD file can be used to examine time series and summarizes the VTU  Timo Koch committed Jun 02, 2021 126  files. (It is possible to abort a running application by pressing $<$Ctrl$><$c$>$.)  127 128 \item You can display the results using the visualization tool ParaView (or alternatively VisIt). Just type \texttt{paraview} in the console and open the  129  PVD file. On the upper left-hand side, you can choose the desired parameter to be displayed.  130 131 \end{enumerate}  Johannes Hommel committed Dec 18, 2018 132 \section{Building Documentation}  Beatrix Becker committed Dec 20, 2018 133 \label{sec:build-doc}  Roman Winter committed Oct 08, 2019 134 Building the included documentation like this handbook requires \LaTeX{} and the auxiliary tool  Johannes Hommel committed Dec 18, 2018 135 \texttt{bibtex}. One usually chooses a \LaTeX{} distribution like \texttt{texlive} for this purpose.  Roman Winter committed Oct 08, 2019 136 It is possible to switch off building the documentation by setting the switch \texttt{--disable-documentation}  Johannes Hommel committed Dec 18, 2018 137 138 139 in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{buildIt}. \subsection{Doxygen}  Thomas Fetzer committed Apr 01, 2015 140 \label{sec:build-doxy-doc}  141 142 Doxygen documentation is done by specifically formatted comments included in the source code, which can get extracted by the program \texttt{doxygen}. Besides extracting these comments,  Roman Winter committed Oct 08, 2019 143 \texttt{doxygen} builds up a web-browsable code-structure documentation  144 like class hierarchy of code displayed as graphs, see \url{https://www.doxygen.nl/index.html}.  David Werner committed Jan 17, 2011 145   146 The Doxygen documentation of a module can be built by running \texttt{dunecontrol} (if \texttt{doxygen} is installed), entering the \texttt{build-*}directory, and executing  Thomas Fetzer committed Jul 09, 2015 147 \texttt{make doc}. Then point your web browser to the file  Thomas Fetzer committed Apr 01, 2015 148 149 \texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation. This should also work for other \Dune modules.  David Werner committed Jan 17, 2011 150   Johannes Hommel committed Dec 18, 2018 151 \subsection{Handbook}  152 To build the \Dumux handbook, navigate to the \texttt{build-}directory and  153 154 run \texttt{make doc} or \texttt{make doc\_handbook\_0\_\\dumux-handbook\_pdf}. The pdf can then be found in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumux\\-handbook.pdf}.  David Werner committed Jan 17, 2011 155   Johannes Hommel committed Dec 18, 2018 156 \section{External Libraries and Modules} \label{sec:external-modules-libraries}  Thomas Fetzer committed Jul 09, 2015 157 The libraries described below provide additional functionality but are not generally required to run \Dumux.  Beatrix Becker committed Dec 20, 2018 158 If you are going to use an external library, check the information provided on the \Dune website%  159 160 161 162 163 164 \footnote{DUNE: External libraries, \url{https://www.dune-project.org/doc/external-libraries/}}. You can consult the \Dune website for higher-level \Dune modules, such as Grid Modules \footnote{DUNE: Grid modules, \url{https://www.dune-project.org/groups/grid/}}, Discretization Modules \footnote{DUNE: Discretization modules, \url{https://www.dune-project.org/groups/disc/}}, and Extension Modules \footnote{DUNE: Extension modules, \url{https://www.dune-project.org/groups/extension/}}.  David Werner committed Jan 19, 2011 165   Thomas Fetzer committed Jul 09, 2015 166 Installing an external library can require additional libraries which are also used by \Dune.  Viktor Szukitsch committed Sep 01, 2011 167 For some libraries, such as BLAS or MPI, multiple versions can be installed on the system.  Klaus Mosthaf committed Feb 24, 2011 168 Make sure that it uses the same library as \Dune when configuring the external library.  David Werner committed Jan 19, 2011 169   Thomas Fetzer committed Oct 05, 2015 170 171 Some of the libraries are then compiled within that directory and are not installed in a different place, but \Dune may need to know their location. Thus, one may have to refer to  Dennis Gläser committed Dec 19, 2018 172 them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-cmake.opts}.  Thomas Fetzer committed Oct 05, 2015 173 Make sure you compile the required external libraries before you run \texttt{dunecontrol}.  174 An easy way to install some of the libraries and modules, given below, is the \texttt{installexternal.py} script located in \texttt{bin}. The script has to be called from your common root directory.  Thomas Fetzer committed Oct 05, 2015 175   Thomas Fetzer committed Apr 01, 2015 176   Johannes Hommel committed Dec 18, 2018 177 \subsection{List of External Libraries and Modules}  Timo Koch committed Nov 12, 2019 178 179 \label{sec:listofexternallibs}  Thomas Fetzer committed Jul 09, 2015 180 181 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.  David Werner committed Oct 25, 2010 182   Philipp Nuske committed Sep 27, 2010 183 \begin{itemize}  Christoph Grüninger committed Jan 18, 2016 184 \item \textbf{dune-ALUGrid}: Grid library, comes as a \Dune module.  Sina Ackermann committed Mar 17, 2017 185 186  The parallel version needs also a graph partitioner, such as {ParMETIS}. Download: \url{https://gitlab.dune-project.org/extensions/dune-alugrid}  Philipp Nuske committed Sep 27, 2010 187   Timo Koch committed Feb 02, 2016 188 189 190 191 192 \item \textbf{dune-foamgrid}: External grid module. One- and two-dimensional grids in a physical space of arbitrary dimension; non-manifold grids, growth, element paramterizations, and movable vertices. This makes FoamGrid the grid data structure of choice for simulating structures such as foams, discrete fracture networks, or network flow problems.  Sina Ackermann committed Mar 17, 2017 193  Download: \url{https://gitlab.dune-project.org/extensions/dune-foamgrid}  Timo Koch committed Dec 19, 2018 194   Johannes Hommel committed Dec 18, 2018 195 \item \textbf{opm-grid}: opm-grid is a DUNE module supporting grids in a corner-point format.  Kilian Weishaupt committed Nov 06, 2020 196  Download: \url{https://github.com/OPM/opm-grid.git} and \url{https://github.com/OPM/opm-common.git}  Timo Koch committed Dec 19, 2018 197 198  \item \textbf{dune-subgrid}: The dune-subgrid module is a meta-grid implementation that allows  Johannes Hommel committed Dec 18, 2018 199 to mark elements of another hierarchical dune grid and use this sub-grid just like a regular grid.  Johannes Hommel committed Dec 18, 2018 200 The set of marked elements can then be accessed as a hierarchical dune grid in its own right.  201 Dune-Subgrid provides the full grid interface including adaptive mesh refinement.  Johannes Hommel committed Dec 18, 2018 202  Download: \url{https://git.imp.fu-berlin.de/agnumpde/dune-subgrid.git}  Timo Koch committed Dec 19, 2018 203   204 205 \item \textbf{dune-spgrid}: The DUNE module dune-spgrid provides a structured, parallel grid and supports periodic boundary conditions.  Johannes Hommel committed Dec 18, 2018 206  Download: \url{https://gitlab.dune-project.org/extensions/dune-spgrid.git}  Timo Koch committed Feb 02, 2016 207   Christoph Grueninger committed Mar 19, 2014 208 209 \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.  Sina Ackermann committed Mar 17, 2017 210  Download: \url{http://crd.lbl.gov/~xiaoye/SuperLU}  Christoph Grueninger committed Mar 19, 2014 211   Timo Koch committed Dec 19, 2018 212 \item \textbf{UMFPack}: External library for solving linear equations. It is part of SuiteSparse.  Timo Koch committed Nov 12, 2019 213  See: \url{http://faculty.cse.tamu.edu/davis/suitesparse.html}. On Debian/Ubuntu you can install the package \texttt{libsuitesparse-dev}.  Christoph Grüninger committed Jan 18, 2016 214   215 \item \textbf{dune-UG}: External library for use as grid. UG is a toolbox for unstructured grids, released under GPL.  Christoph Grueninger committed Apr 01, 2014 216  To build UG the tools \texttt{lex}/\texttt{yacc} or the GNU variants of \texttt{flex}/\texttt{bison} must be provided.  Sina Ackermann committed Mar 17, 2017 217  Download: \url{https://gitlab.dune-project.org/staging/dune-uggrid}  David Werner committed Oct 25, 2010 218 219 \end{itemize}  Thomas Fetzer committed Jul 09, 2015 220 221 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.  David Werner committed Jan 19, 2011 222   David Werner committed Oct 25, 2010 223 \begin{itemize}  Christoph Grueninger committed Mar 19, 2014 224 225 \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  Christoph Grueninger committed Jul 09, 2014 226  version have been reported to work.  David Werner committed Oct 25, 2010 227   Timo Koch committed Feb 02, 2016 228 \item \textbf{BLAS}: SuperLU makes use of BLAS. Thus install GotoBLAS2, ATLAS, non-optimized BLAS  Christoph Grueninger committed Mar 19, 2014 229 230  or BLAS provided by a chip manufacturer. Take care that the installation scripts select the intended version of BLAS.  Klaus Mosthaf committed Feb 23, 2011 231   Christoph Grueninger committed Mar 19, 2014 232 \item \textbf{METIS} and \textbf{ParMETIS}: This are dependencies of ALUGrid and can be used with UG, if run in parallel.  David Werner committed Oct 25, 2010 233   Christoph Grueninger committed Mar 19, 2014 234 235 \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  Beatrix Becker committed Dec 20, 2018 236  different compilers is linked together, they have to be be compatible with each other.  Sina Ackermann committed Mar 17, 2017 237 \end{itemize}  Ned Coltman committed Apr 20, 2020 238 239 240 241  \section{Backwards Compatibility} \label{sec:backwardscompatibility}  242 243 244 Dumux Releases are split into major (e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3, 3.4) releases. Major releases are not required to maintain backwards compatibility but would provide a detailed guide on updating dependent modules.  Ned Coltman committed Apr 20, 2020 245 246 247 248 249 250 For each minor release, maintaining backwards compatibility is strongly encouraged and recommended. Maintaining backwards compatibility means for all changes made to the dumux master, each tests and all dumux dependent modules should still compile. In addition, the user should be warned at compile time of any relevant interface changes. This can be done by deprecating the old method with a deprecation message and forwarding it to the new method. Examples of this are shown in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}{contribution guide}. Each of these deprecation messages should also include the release in which the interface will be removed, and all changes should be documented thoroughly in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CHANGELOG.md}{changelog.md}. Despite the goal of maintaining backwards compatibility across minor releases, for more complicated changes, this is to be decided upon on a case-by-case basis, due to limited developer resources.  251 In the case that implementing full backwards compatibility for an update is not feasible, or would require unreasonable resources, the degree of backwards compatibility will be decided by a vote in one of the monthly core developer meetings.