Sven K committed Aug 22, 2016 1 \chapter{Setup and Installation}  Tobias Weinzierl committed Nov 18, 2015 2 3 \label{chapter:download}  Sven K committed Aug 22, 2016 4 5 \section{Dependencies and prerequisites}  tobias committed Feb 04, 2017 6 ExaHyPE comes along with the following dependencies:  Sven K committed Aug 22, 2016 7 8 9  \begin{itemize} \item  tobias committed Feb 04, 2017 10 \exahype\ source code is C++ code.  tobias committed Feb 28, 2017 11 For sequential simulations, only a C++ compiler is required.  Sven K committed Aug 22, 2016 12 All examples from this guidebook run and have been tested with  tobias committed Feb 13, 2017 13 newish GCC and Intel compilers.  tobias committed Apr 12, 2017 14 15 The code uses few C++14 features, but for many older versions enabling those features through \texttt{--std=c++0x} made the code  tobias committed Feb 13, 2017 16 pass.  tobias committed Feb 04, 2017 17 18 19 20 There are no further dependencies or libraries required. \item You may prefer to write parts of your \exahype\ code in Fortran. In this case,  tobias committed Feb 28, 2017 21 22 you obviously need a Fortran besides a C++ compiler. \exahype\ itself does not depend on Fortran.  tobias committed Feb 04, 2017 23 24 25  \item If you want \exahype\ to exploit your multi- or manycore computer, you have to  Tobias Weinzierl committed Nov 27, 2017 26 27 have Intel's TBB or OpenMP. Both are open source and work with GCC and Intel compilers. OpenMP 4 (coming along with GCC 4.9) or TBB 2017 are required.  tobias committed Feb 04, 2017 28 29 30  \item If you want to run \exahype\ on a distributed memory cluster, you have to have  tobias committed Feb 28, 2017 31 32 MPI installed. \exahype\ uses only very basic MPI routines (as provided with MPI 1.3, e.g.).  Sven K committed Aug 22, 2016 33 34  \item  tobias committed Feb 04, 2017 35 ExaHyPE's default build environment uses GNU Make.  Sven K committed Aug 22, 2016 36   tobias committed Feb 04, 2017 37  \item  Jean-Matthieu Gallard committed Sep 17, 2018 38 39 ExaHyPE's development environment relies on Python 3. All additional Python 3 dependencies can be downloaded using the git submodules and the provided script.  Jean-Matthieu Gallard committed Sep 14, 2017 40   tobias committed Feb 04, 2017 41   Sven K committed Aug 22, 2016 42 43 44 \end{itemize} \noindent  tobias committed Feb 28, 2017 45 46 47 48 The guidebook assumes that you use a Linux system. Members of the \exahype\ consortium and other users successfully use Windows and Mac systems. \exahype\ however focuses not on these platforms and thus no typical pitfalls are discussed here.  tobias committed Dec 15, 2016 49 50 51 The code itself is minimalistic, i.e.~in \exahype's basic form no further libraries are required.  Sven K committed Aug 22, 2016 52 53 54  \section{Obtaining ExaHyPE}  tobias committed Feb 04, 2017 55 \exahype\ is available as source code only. We discuss several variants how to  Dominic Etienne Charrier committed Sep 18, 2018 56 obtain the code below.  tobias committed Feb 11, 2017 57 58 59 60 61 \exahype\ is built on top of the AMR framework Peano. If you download a complete snapshot of \exahype\ (the \texttt{tar.gz} files), a snapshot of Peano is included. If you clone the repository (Variant 2), you have to add Peano manually.  Tobias Weinzierl committed Jan 06, 2016 62   tobias committed Feb 13, 2017 63 \subsection*{Variant 1: Download an \exahype\ release}  tobias committed Feb 04, 2017 64   Dominic Etienne Charrier committed Sep 18, 2018 65 66 67 68 69 70 71 Open a browser and go to \url{http://www.peano-framework.org}. Here, click on \texttt{Request Repository Access} and fill out the application form. Click on \texttt{Register}. The application will trigger a creation of a LRZ account linked to the Peano and \exahype\ projects. Eventually, you will get reporter access to the software repositories via \url{https://gitlab.lrz.de}. You will get notified by mail as soon as this is the case. The process can take a few days.  Jean-Matthieu Gallard committed Sep 17, 2018 72   Dominic Etienne Charrier committed Sep 18, 2018 73 The \exahype\ repository can then be cloned via:  Sven K committed Aug 22, 2016 74 \begin{code}  Anne Reinarz committed Jun 06, 2018 75 > git clone https://gitlab.lrz.de/exahype/ExaHyPE-Engine.git  Sven K committed Aug 22, 2016 76 \end{code}  tobias committed Feb 04, 2017 77 78 or \begin{code}  Dominic Etienne Charrier committed Sep 18, 2018 79 > git@gitlab.lrz.de:exahype/ExaHyPE-Engine.git  tobias committed Feb 11, 2017 80 81 \end{code}  Dominic Etienne Charrier committed Sep 18, 2018 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 % \subsection*{Variant 2: Clone the \exahype\ release repository} % % Alternatively, you might also want to clone the \exahype\ git repository % which has the advantage that you can quickly get new releases. % We host it on a gitlab at Leibniz Supercomputing Centre and grant free access to all sources and documentation. % However, we ask users who want to actively access the repository, the maillist, the bug lists, and so forth to register. % % Once you have access to the repository you can download the repository using % something along the lines of % \begin{code} % > git clone https://gitlab.lrz.de/exahype/ExaHyPE-Engine.git % \end{code} % or % \begin{code} % > git clone git@gitlab.lrz.de:exahype/ExaHyPE-Engine.git % \end{code} % There is consequently no need to unzip anything manually if you follow this variant. % % % While we do provide snapshots of Peano, \exahype's underlying meshing component, % with \exahype\ snapshots (the tar.gz files we offer), Peano itself is not % mirrored in the repository. % You therefore have to download Peano separately: % Visit \href{http://www.peano-framework.org}{peano-framework.org} and follow the % descriptions there. % Afterwards, add two symbolic links from \exahype's \texttt{Peano} directory to % your Peano installation\footnote{If you grab the Peano repository, the % sources are held in a subdirectory \texttt{src} as the checkout also comes % along with many other things such as development tools or documentation. % If you download the tarball from the webpage, it usually holds only Peano's % sources. In this case, you might have to omit the \texttt{src} subdirectory in % the symbolic links.}: % \begin{code} % > cd Peano % > ls % mpibalancing multiscalelinkedcell sharedmemoryoracles % > ln -s yourPeanodirectory/src/peano % > ln -s yourPeanodirectory/src/tarch % > ls % mpibalancing multiscalelinkedcell peano sharedmemoryoracles tarch % \end{code} % % \noindent % We do trigger that Peano is updated regularly and \exahype's build environment % does validate your Peano version against its on requirements. % Yet, as Peano is an independent package with a different release % model/schedule, we cannot enure that a tarball of Peano obtained from % SourceForge or \href{http://www.peano-framework.org}{peano-framework.org} is fully compatible with the % current ExaHyPE release. % If you encounter problems, we therefore recommend that you use the snapshot of % Peano provided in \texttt{ExaHyPE.tar.gz}. % It is guaranteed to be compatible with the ExaHyPE.  tobias committed Feb 04, 2017 134 135   tobias committed Feb 13, 2017 136 137 138 139 140 141 142 143 144 145 146 147 148 % \subsection*{Variant 3: Download \exahype\ as archives from the % webpages} % % Open a browser and go to \url{https://github.com/exahype}. % Switch to the \texttt{Code} tab and press on the \texttt{Clone or download} drop % down button. % Select the zip file and unzip the result. % % Alternatively, you should see on the webpage directly a file % \texttt{exahype.tar.gz}. % You need this one as well as either \texttt{ExaHyPE.jar} or % \texttt{ExaHyPE-toolkit.tar.gz}. % Please unzip the files.  Sven K committed Aug 22, 2016 149   tobias committed Dec 15, 2016 150   tobias committed Feb 11, 2017 151 %\pagebreak  Tobias Weinzierl committed Jan 06, 2016 152   Jean-Matthieu Gallard committed Sep 17, 2018 153 154 \section*{Obtaining the dependencies} ExaHyPE's development environment relies on a few Python 3 dependencies. They are  Dominic Etienne Charrier committed Sep 18, 2018 155 156 all registered as git submodule to the project. Peano is also registered as a git submodule  Jean-Matthieu Gallard committed Sep 17, 2018 157 158 159 160 161  To obtain them, run the update script: \begin{code} > ./Submodules/updateSubmodules.sh \end{code}  Dominic Etienne Charrier committed Sep 18, 2018 162 163 164 165 166 167 168 169 Different options to modify the download procedure are listed if you call the script with option \texttt{-h}'', e.g. use \texttt{git clone} with the \texttt{git} (\texttt{-s}'') or \texttt{https} protocol (\texttt{-w}''), We ensured that ExaHyPE can be setup on systems where you are required to create an SSH tunnel to \texttt{github.com} or \texttt{gitlab.lrz.de}.  Jean-Matthieu Gallard committed Sep 17, 2018 170   tobias committed Feb 04, 2017 171 172 173 \section*{Finish the setup} Once you have unzipped all the archives into a directory of your choice, you should see something like  Jean-Matthieu Gallard committed Sep 17, 2018 174   Jean-Matthieu Gallard committed Sep 18, 2018 175 %\textcolor{red}{TODO Dominic: seems wrong}  Jean-Matthieu Gallard committed Sep 17, 2018 176   tobias committed Feb 04, 2017 177 178 179 180 181 182 183 184 185 186 187 188 \begin{code} > cd mywellsuiteddirectory > ls ExaHyPE ExaHyPE.jar ExaHyPE.tar.gz ExaHyPE-toolkit.tar.gz LICENSE.txt Peano \end{code} \noindent You might choose to maintain a different directory structure or rely on a previous \peano\ or \exahype\ installation. In this case, you have to adopt pathes in all of your \exahype\ scripts from hereon.  Jean-Matthieu Gallard committed Sep 18, 2018 189 %\textcolor{red}{TODO Dominic: these are symlinks now, please update}  Jean-Matthieu Gallard committed Sep 17, 2018 190   tobias committed Feb 11, 2017 191 192 193 194 195 196 197 198 199 200 201 Please also check that your \texttt{Peano} subdirectory holds the Peano AMR directories: \begin{code} > cd mywellsuiteddirectory > ls Peano mpibalancing multiscalelinkedcell peano sharedmemoryoracles tarch \end{code} \noindent There might be more subdirectories. However, these five are absolutely mandatory.  tobias committed Feb 04, 2017 202 203   tobias committed Jan 24, 2017 204 \section{Dry run of development tools}  Tobias Weinzierl committed Jan 06, 2016 205   tobias committed Feb 11, 2017 206 207 \vspace{0.8cm} \noindent  tobias committed Jan 24, 2017 208 209 To check whether you are ready to program new applications with \exahype, type in  Tobias Weinzierl committed Nov 18, 2015 210 211  \begin{code}  Jean-Matthieu Gallard committed Sep 17, 2018 212 > ./Toolkit/toolkit.sh -h  Tobias Weinzierl committed Nov 18, 2015 213 214 \end{code}  Tobias Weinzierl committed Jan 06, 2016 215 216  \noindent  Jean-Matthieu Gallard committed Sep 17, 2018 217 218 This should give you a description of the various toolkit options. If you encounter an error, please make sure the submodules are downloaded.  Tobias Weinzierl committed Nov 18, 2015 219   tobias committed Feb 04, 2017 220 %\section{Optional installation variants}d  Tobias Weinzierl committed Nov 18, 2015 221   tobias committed Dec 15, 2016 222 \section{Using a newer/other \peano\ version}  Tobias Weinzierl committed Nov 18, 2015 223 224  \exahype\ is based upon the PDE solver framework \peano\  Sven K committed Apr 20, 2017 225 (\href{http://www.peano-framework.org}{peano-framework.org}).  Tobias Weinzierl committed Jan 06, 2016 226 227 228 229 230 231 232 233 234 235 236 237 238 239 With the present scripts, you use the newest stable \peano\ release. As \peano\ is still improved, it might make sense to download a new archive from time to time. \exahype\ uses a couple of \peano\ toolboxes. These toolboxes are part of \peano's framework, but they are not by default included in the release. While normal \peano\ users have to download them manually, we provide a snapshot with \exahype. These snapshots are help in \exahype's \texttt{Peano} directory. If you want to try newer versions, download the corresponding toolboxes from \peano's webpage and extract them manually into \exahype's \texttt{Peano} subdirectory.  Tobias Weinzierl committed Nov 18, 2015 240   Tobias Weinzierl committed Jan 06, 2016 241 242 243 244 If you use \peano\ in several projects, it might make sense to skip the download of the archive into \exahype's \texttt{Peano} directory and instead add two symbolic links with \texttt{ln -s} in the \texttt{Peano} directory to \peano's \texttt{peano} and \texttt{tarch} directory.  tobias committed Dec 15, 2016 245