01_download.tex 8.84 KB
Newer Older
1
\chapter{Setup and Installation}
2
3
\label{chapter:download}

4
5
\section{Dependencies and prerequisites}

6
ExaHyPE comes along with the following dependencies:
7
8
9

\begin{itemize}
  \item 
10
\exahype\ source code is C++ code.
tobias's avatar
tobias committed
11
For sequential simulations, only a C++ compiler is required.
12
All examples from this guidebook run and have been tested with 
tobias's avatar
tobias committed
13
newish GCC and Intel compilers.
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's avatar
tobias committed
16
pass.
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's avatar
tobias committed
21
22
you obviously need a Fortran besides a C++ compiler. \exahype\ itself does
not depend on Fortran.
23
24
25

  \item 
If you want \exahype\ to exploit your multi- or manycore computer, you have to
Tobias Weinzierl's avatar
Tobias Weinzierl committed
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.
28
29
30

  \item  
If you want to run \exahype\ on a distributed memory cluster, you have to have
tobias's avatar
tobias committed
31
32
MPI installed. \exahype\ uses only very basic MPI routines (as provided with
MPI 1.3, e.g.).
33
34

  \item 
35
ExaHyPE's default build environment uses GNU Make.
36

37
  \item 
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.
40

41
 
42
43
44
\end{itemize}

\noindent
tobias's avatar
tobias committed
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's avatar
tobias committed
49
50
51
The code itself is minimalistic, i.e.~in \exahype's basic form no further
libraries are required.

52
53
54

\section{Obtaining ExaHyPE}

55
\exahype\ is available as source code only. We discuss several variants how to
56
obtain the code below.
tobias's avatar
tobias committed
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.

62

tobias's avatar
tobias committed
63
\subsection*{Variant 1: Download an \exahype\ release}
64

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. 
72

73
The \exahype\ repository can then be cloned via:
74
\begin{code}
75
> git clone https://gitlab.lrz.de/exahype/ExaHyPE-Engine.git
76
\end{code}
77
78
or
\begin{code}
79
> git@gitlab.lrz.de:exahype/ExaHyPE-Engine.git
tobias's avatar
tobias committed
80
81
\end{code}

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.
134
135


tobias's avatar
tobias committed
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.
149

tobias's avatar
tobias committed
150

tobias's avatar
tobias committed
151
%\pagebreak
152

153
154
\section*{Obtaining the dependencies}
ExaHyPE's development environment relies on a few Python 3 dependencies. They are
155
156
all registered as git submodule to the project. Peano is also registered as a
git submodule 
157
158
159
160
161

To obtain them, run the update script: 
\begin{code}
> ./Submodules/updateSubmodules.sh
\end{code}
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}.
170

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
174

175
%\textcolor{red}{TODO Dominic: seems wrong}
176

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.

189
%\textcolor{red}{TODO Dominic: these are symlinks now, please update}
190

tobias's avatar
tobias committed
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.

202
203


204
\section{Dry run of development tools}
205

tobias's avatar
tobias committed
206
207
\vspace{0.8cm}
\noindent
208
209
To check whether you are ready to program new applications with \exahype, type
in
210
211

\begin{code}
212
> ./Toolkit/toolkit.sh -h
213
214
\end{code}

215
216

\noindent
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.
219

220
%\section{Optional installation variants}d
221

tobias's avatar
tobias committed
222
\section{Using a newer/other \peano\ version}
223
224

\exahype\ is based upon the PDE solver framework \peano\
225
(\href{http://www.peano-framework.org}{peano-framework.org}).
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.
240

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's avatar
tobias committed
245