fix hash in Emmy example
[dealii.wiki.git] / deal.II-in-Spack.md
1 # Using deal.II on Mac OS X and Linux via Spack
2
3 The deal.II suite is also available on Spack (https://github.com/LLNL/spack) -- a flexible package manager developed with High-Performance-Computing in mind. It is intended to let you build for many combinations of compiler, architectures, dependency libraries, and build configurations, all with a friendly, intuitive user interface.
4
5 For a quick overview of Spack's features, we recommend this short presentation https://tgamblin.github.io/files/Gamblin-Spack-SC15-Talk.pdf
6 or the following videos from lead developers:
7 [Massimiliano Culpo - SPACK: A Package Manager for Supercomputers, Linux and MacOS](https://www.youtube.com/watch?v=Qok-nXfIWfg) and 
8 [Todd Gamblin (LLNL) - Managing HPC Software Complexity with Spack](https://www.youtube.com/watch?v=Ie1cZTR09kk).
9
10 [Spack tutorial 101](http://spack.readthedocs.io/en/latest/tutorial.html) is good place to start as well.
11
12 Note: Spack is in active development and is in alpha state, thereby below we recommend using the specific snapshot of the code (hash), that was tested on macOS / Ubuntu / CentOS7 with deal.II and is being used to run the complete testsuite on `Unbutu16.04` with `openmpi` and `openblas`. See [Experimental section of CDash](https://cdash.kyomu.43-1.org/index.php?project=deal.II).
13
14 ## Quick installation on the desktop
15
16 Add the following to `~/.bashrc` (or equivalent)
17 ```
18 export SPACK_ROOT=/path/to/spack
19 PATH="$SPACK_ROOT/bin:$PATH"
20 ```
21 `SPACK_ROOT` is the destination where you want Spack to be installed (i.e. `$HOME/spack`).
22
23 Now clone Spack
24 ```
25 cd $SPACK_ROOT
26 git clone https://github.com/llnl/spack.git .
27 git checkout develop
28 git reset --hard f6c16de6de54c4f3a1a3f972f2236f1b2675fb3d
29 ```
30
31 **Make sure C/C++/Fortran compilers are in path** (on Ubuntu you need to `sudo apt-get install gfortran`, on macOS you can compile `gcc` with spack, see [below](#installing-gcc), and you have **curl** (`sudo apt-get install curl`) to download packages. Then install the complete deal.II suite
32 ```
33 spack install dealii
34 ```
35 **DONE**! No extra (preliminary) configuration steps are needed on most Linux distributions. **IMPORTANT:** If you compile deal.II on a cluster, see the next section on how to use externally provided MPI implementation instead.
36
37 Before configuring your project you need to set `DEAL_II_DIR` by 
38 ```
39 export DEAL_II_DIR=$(spack location -i dealii)
40 ```
41 You may jump ahead and read [best practices using spack](#best-practices-using-spack). Also a good starting point is [Getting Started Guide](http://spack.readthedocs.io/en/latest/getting_started.html).
42
43
44 ## Installation example on a Centos7 cluster (Emmy cluster of RRZE, Erlangen, Germany)
45 In order to use Spack on a cluster, there are two options: (1) you are a sysadmin and you know hardware details and can use Spack to properly configure and build MPI providers (e.g. `openmpi`); (2) you are a user and you need to make Spack work with MPI provided on your cluster. Below we consider the latter case.
46
47 Here is a brief step-by-step instruction to install deal.II on [Emmy cluster](https://www.rrze.fau.de/dienste/arbeiten-rechnen/hpc/systeme/emmy-cluster.shtml#access) of RRZE, Erlangen, Germany:
48
49 (1) Download spack
50 ```
51 module load git
52 mkdir $WOODYHOME/spack
53 cd $WOODYHOME/spack
54 git clone https://github.com/llnl/spack.git $WOODYHOME/spack
55 git reset --hard f6c16de6de54c4f3a1a3f972f2236f1b2675fb3d
56 export PATH=$WOODYHOME/spack/bin:$PATH
57 ```
58 (2) Load `openmpi` and let Spack find GCC compiler which is also loaded as a dependency:
59 ```
60 module load openmpi/2.0.2-gcc
61 spack compiler find
62 ```
63 (3) Add `openmpi` as an external package, along with `python` and a few other self explanatory setting for `deal.ii`. That is done by adding the following to `~/.spack/linux/packages.yaml`
64 ```
65 packages:
66   all:
67     compiler: [gcc]
68     providers:
69       mpi: [openmpi]
70       blas: [openblas]
71       lapack: [openblas]
72   python:
73     version: [2.7.12]
74     paths:
75       python@2.7.12: /usr/
76     buildable: False
77   openmpi:
78     version: [2.0.2]
79     paths:
80       openmpi@2.0.2%gcc@4.8.5: /apps/OpenMPI/2.0.2-gcc/
81     buildable: False
82   dealii:
83     variants: +optflags~python
84 ```
85 Those paths are the location where external packages can be found (i.e. `<prefix>` instead of `<prefix>/bin` or `<prefix>/lib`). `providers` section essentially tells Spack which packages to use to satisfy virtual dependencies such as `MPI`, `BLAS`, `LAPACK`, `ScaLAPACK`, etc.
86
87 (4) Now install deal.II:  `spack install dealii`.
88
89 Note that we specifically build deal.II without `python` wrappers. Otherwise deal.II would be linked against system provided `python` which itself may be linked against system provided `zlib`. As a result we may have a mixture of Spack's build `zlib` and system provided `zlib`, which is certainly not what we want.
90
91
92 ## Environment Modules
93 Spack provides some integration with Environment Modules and Dotkit to make it easier to use the packages it installs. For a full description, read http://spack.readthedocs.io/en/latest/getting_started.html#environment-modules
94
95 To add the support for Environment Modules run
96 ```
97 spack install environment-modules
98 ```
99 Get the path to the prefix of `environment-modules` by:
100 ```
101 spack location --install-dir environment-modules
102 ```
103 and then add to `~/.bashrc` (or equivalent)
104 ```
105 MODULES_HOME=/path/to/environment-modules
106 source ${MODULES_HOME}/Modules/init/bash
107 . $SPACK_ROOT/share/spack/setup-env.sh
108 ```
109
110 If you install `deal.II` before setting up environment modules,
111 the module files have to be regenerated
112 ```
113 spack module refresh
114 ```
115
116 Then run
117 ```
118 spack load dealii
119 spack load cmake
120 ```
121 Now `DEAL_II_DIR` environment variable should be set appropriately and `cmake` executable will be available in path. Keep in mind that `spack load dealii` will also set `LD_LIBRARY_PATH` accordingly, this may or may not be what you need. An alternative is to use `export DEAL_II_DIR=$(spack location -i dealii)`.
122
123 ## System provided packages
124 Spack is flexible to use both self-compiled and system provided packages. 
125 In most cases this is desirable for `MPI`, which is already installed on computational clusters. To configure external packages you need to edit `~/.spack/linux/packages.yaml`. For `openmpi` this could be
126 ```
127 packages:
128   openmpi:
129     version: [1.8.8]
130     paths:
131       openmpi@1.8.8%gcc@6.2.0: /opt/openmpi-1.8.8
132     buildable: False
133 ```
134 In order to make sure that we use to build packages `1.8.8` version of `openmpi` and not the most recent one (i.e. `2.0.2`), we specified conretization preferences with `version: [1.8.8]`.
135
136 One can also specify which packages should be used to provide `mpi`, `blas/lapack` , preferred compilers and preferred variants:
137 ```
138 packages:
139   all:
140     compiler: [gcc,clang]
141     providers:
142       mpi: [openmpi]
143       blas: [openblas]
144       lapack: [openblas]
145     boost:
146       variants: +python
147 ```
148
149 For more elaborated discussion, see [Configuration Files in Spack](http://spack.readthedocs.io/en/latest/configuration.html).
150
151 ## Installing GCC
152 If your system does not provide any Fortran compiler or you want to have the most recent `gcc`,
153 you can install it by
154 ```
155 spack install gcc
156 ```
157
158 Assuming that you configured [Environment Modules](#environment-modules), load `gcc` and let Spack find the newly installed compilers:
159 ```
160 spack load gcc
161 spack compiler find
162 ```
163 Now you can install deal.II with `gcc`
164 ```
165 spack install dealii%gcc
166 ```
167
168 If you are on the mac, read the following instructions on [Mixed Toolchains](http://spack.readthedocs.io/en/latest/getting_started.html#mixed-toolchains).
169
170 On following these instructions, you will be able to install deal.II with clang+gfortran
171 ```
172 spack install dealii%clang
173 ```
174
175 ## Best practices using Spack:
176
177 Spack is complicated and flexible package manager primarily aimed at High-Performance-Computing.
178 Below are some examples of using Spack to build and develop deal.II:
179
180 ### Info:
181 If you are not sure which options a given package has, simply run
182 ```
183 spack info <package>
184 ```
185 The output will contain available versions, variants, dependencies and description:
186 ```
187 $ spack info dealii
188 CMakePackage:   dealii
189
190 Description:
191     C++ software library providing well-documented tools to build finite
192     element codes for a broad variety of PDEs.
193
194 Homepage: https://www.dealii.org
195
196 Preferred version:  
197     8.5.1      https://github.com/dealii/dealii/releases/download/v8.5.1/dealii-8.5.1.tar.gz
198
199 Safe versions:  
200     develop    [git] https://github.com/dealii/dealii.git
201     8.5.1      https://github.com/dealii/dealii/releases/download/v8.5.1/dealii-8.5.1.tar.gz
202     8.5.0      https://github.com/dealii/dealii/releases/download/v8.5.0/dealii-8.5.0.tar.gz
203     8.4.2      https://github.com/dealii/dealii/releases/download/v8.4.2/dealii-8.4.2.tar.gz
204     8.4.1      https://github.com/dealii/dealii/releases/download/v8.4.1/dealii-8.4.1.tar.gz
205     8.4.0      https://github.com/dealii/dealii/releases/download/v8.4.0/dealii-8.4.0.tar.gz
206     8.3.0      https://github.com/dealii/dealii/releases/download/v8.3.0/dealii-8.3.0.tar.gz
207     8.2.1      https://github.com/dealii/dealii/releases/download/v8.2.1/dealii-8.2.1.tar.gz
208     8.1.0      https://github.com/dealii/dealii/releases/download/v8.1.0/dealii-8.1.0.tar.gz
209
210 Variants:
211     Name [Default]               Allowed values          Description
212
213
214     adol-c [off]                 True, False             Compile with Adol-c
215     arpack [on]                  True, False             Compile with Arpack and
216                                                          PArpack (only with MPI)
217     build_type [DebugRelease]    Debug, Release,         The build type to build
218                                  DebugRelease            
219     doc [off]                    True, False             Compile with documentation
220     gsl [on]                     True, False             Compile with GSL
221     hdf5 [on]                    True, False             Compile with HDF5 (only with
222                                                          MPI)
223     int64 [off]                  True, False             Compile with 64 bit indices
224                                                          support
225     metis [on]                   True, False             Compile with Metis
226     mpi [on]                     True, False             Compile with MPI
227     nanoflann [off]              True, False             Compile with Nanoflann
228     netcdf [on]                  True, False             Compile with Netcdf (only with
229                                                          MPI)
230     oce [on]                     True, False             Compile with OCE
231     optflags [off]               True, False             Compile using additional
232                                                          optimization flags
233     p4est [on]                   True, False             Compile with P4est (only with
234                                                          MPI)
235     petsc [on]                   True, False             Compile with Petsc (only with
236                                                          MPI)
237     python [on]                  True, False             Compile with Python bindings
238     slepc [on]                   True, False             Compile with Slepc (only with
239                                                          Petsc and MPI)
240     sundials [off]               True, False             Compile with Sundials
241     trilinos [on]                True, False             Compile with Trilinos (only
242                                                          with MPI)
243
244 Installation Phases:
245     cmake    build    install
246
247 Build Dependencies:
248     adol-c     bzip2     gsl     mpi        netcdf-cxx  python        tbb
249     arpack-ng  cmake     hdf5    muparser   oce         slepc         trilinos
250     blas       doxygen   lapack  nanoflann  p4est       suite-sparse  zlib
251     boost      graphviz  metis   netcdf     petsc       sundials
252
253 Link Dependencies:
254     adol-c     bzip2     hdf5    muparser    oce     slepc         trilinos
255     arpack-ng  doxygen   lapack  nanoflann   p4est   suite-sparse  zlib
256     blas       graphviz  metis   netcdf      petsc   sundials
257     boost      gsl       mpi     netcdf-cxx  python  tbb
258
259 Run Dependencies:
260     None
261
262 Virtual Packages: 
263     None
264 ```
265
266 A lot of `spack` commands have help, for example
267 ```
268 $ spack install -h
269 usage: spack install [-h] [--only {package,dependencies}] [-j JOBS]
270                      [--keep-prefix] [--keep-stage] [--restage] [-n] [-v]
271                      [--fake] [-f] [--clean | --dirty] [--run-tests]
272                      [--log-format {junit}] [--log-file LOG_FILE]
273                      ...
274
275 build and install packages
276
277 positional arguments:
278   package               spec of the package to install
279
280 optional arguments:
281   -h, --help            show this help message and exit
282   --only {package,dependencies}
283                         select the mode of installation. the default is to
284                         install the package along with all its dependencies.
285                         alternatively one can decide to install only the
286                         package or only the dependencies
287   -j JOBS, --jobs JOBS  explicitly set number of make jobs. default is #cpus
288   --keep-prefix         don't remove the install prefix if installation fails
289   --keep-stage          don't remove the build stage if installation succeeds
290   --restage             if a partial install is detected, delete prior state
291   -n, --no-checksum     do not check packages against checksum
292   -v, --verbose         display verbose build output while installing
293   --fake                fake install. just remove prefix and create a fake
294                         file
295   -f, --file            install from file. Read specs to install from .yaml
296                         files
297   --clean               clean environment before installing package
298   --dirty               do NOT clean environment before installing
299   --run-tests           run package level tests during installation
300   --log-format {junit}  format to be used for log files
301   --log-file LOG_FILE   filename for the log file. if not passed a default
302                         will be used
303 ```
304
305 ### Extra options:
306 One can specify extra options for packages in the deal.II suite. For example if you want to have boost with `python` module, this can be done by
307 ```
308 spack install dealii@develop+mpi~python ^boost+python
309 ```
310
311 If you want to specify blas/lapack/mpi implementations, this can be done similarly
312 ```
313 spack install dealii@develop+mpi ^mpich
314 ```
315 To check which packages implement `mpi` run
316 ```
317 spack providers mpi
318 ```
319 One can also specify which Blas/Lapack implementation to use. For example to build deal.II suite with `atlas` run
320 ```
321 spack install dealii ^atlas
322 ```
323
324 ### Compiler flags
325 You can specify compiler flags on the command line as
326 ```
327 spack install dealii cppflags="-march=native -O3"
328 ```
329 Note that these flags will be inherited by dependencies such as `petsc`, `trilinos`, etc. Same can be done by declaring these flags in `~/.spack/compilers.yaml`:
330 ```
331 compilers:
332 - compiler:
333     modules: []
334     operating_system: centos6
335     paths:
336       cc: /usr/bin/gcc
337       cxx: /usr/bin/g++
338       f77: /usr/bin/gfortran
339       fc: /usr/bin/gfortran
340     flags:
341       cflags: -O3 -fPIC
342       cxxflags: -O3 -fPIC
343       cppflags: -O3 -fPIC
344     spec: gcc@4.7.2
345 ```
346
347 If you want to use flags for `dealii` only, you can first build all the dependencies without flags and then build `dealii` with custom flags:
348 ```
349 spack install --only dependencies dealii
350 spack install dealii cppflags="-march=native -O3"
351 ```
352
353 See this [google forum topic](https://groups.google.com/forum/?fromgroups#!topic/dealii/3Yjy8CBIrgU) for discussion on which flags to use. You can also use `spack install dealii+optflags` to enable extra optimization flags in release build.
354
355 ### Different versions coexisting:
356 One can easily have slightly different versions of deal.II side-by-side, e.g. to compile development version of deal.II with complex-valued PETSc and `gcc` compiler run
357 ```
358 spack install dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
359 ```
360 The good thing is that if you already have deal.ii built with real-valued petsc, then only `petsc`, `slepc` and `deal.ii` itself will be rebuild. Everything else (`trilinos`, `mumps`, `metis`, etc) will be reused.
361
362 One can use `environment-modules` (see above) to automatically set `DEAL_II_DIR` to the complex version: 
363 ```
364 spack load dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
365 ```
366
367 ### Filesystem Views:
368 If you prefer to have the whole dealii suite (and possible something else) symlinked into a single path (like `/usr/local`), one can use [Filesystem Views](http://spack.readthedocs.io/en/latest/workflows.html#filesystem-views):
369 ```
370 spack view -v symlink dealii_suite dealii@develop
371 ```
372 You can also add to this view other packages, i.e.
373 ```
374 spack view -v symlink dealii_suite the-silver-searcher
375 ```
376
377
378 ### Check before build:
379 It is often convenient to check which version of packages, compilers, variants etc will be used before actually starting installation. That can be done by examining the concretized spec via `spack spec` command, e.g. 
380 ```
381 spack spec dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
382 ```
383
384 The `spec` command has a useful flag `-I` which will show install status of dependencies in the graph.
385
386 ### Develop using Spack
387 Probably the easiest way to use Spack while contributing patches to the deal.II is the following. 
388 Install `deal.II` via Spack, go to its installation prefix and copy-paste the CMake command from `.spack/build.out`, which looks like
389 ```
390 'cmake' '/path/to/spack/var/spack/stage/dealii-develop-tkowxhk55kpi7facfh3ufipofyolt6h7/dealii' '-DCMAKE_INSTALL_PREFIX:PATH=path/to/spack/opt/spack/darwin-sierra-x86_64/clang-8.1.0-apple/dealii-develop-tkowxhk55kpi7facfh3ufipofyolt6h7' '-DCMAKE_BUILD_TYPE:STRING=DebugRelease' <more options>
391 ```
392 You would need to adjust the path to the `dea.II` source folder (first path) and should remove the `DCMAKE_INSTALL_PREFIX` as you probably don't want to accidentally override the version installed by Spack. 
393
394 Before running `cmake` from the build folder, you may want to run 
395 ```
396 spack env dealii@develop+mpi^openmpi^openblas bash
397 ```
398 to make sure your environment (paths, variables, etc) is set exactly the same way as when compiling `deal.II` from Spack
399 (adjust the spec `dealii@develop+mpi^openmpi^openblas` to be what you use when you installed `deal.II`).
400
401 An alternative is to create a [Filesystem view](#filesystem-views) for an already installed library and then compile patched version of deal.II manually by providing path to the view for each dependency. 
402
403 ### Keep the stage to run unit tests
404 By default, the build folder (aka `stage`) for each package is created in a temporary system dependent location.
405 This gets purge by system on next restart.
406 If you want to keep the stage after the installation, you need to do two things:
407 First, make spack use a custom location for stage by adding the following to your `~/.spack/config.yaml`:
408 ```
409 config:
410   build_stage:
411     - $spack/var/spack/stage
412 ```
413 Second, prescribe an extra argument to `install` command to keep the stage after successful installation:
414 ```
415 spack install --keep-stage dealii@develop
416 ```
417
418 ### MKL and Licensed software
419 Spack supports installation of [licensed software](http://spack.readthedocs.io/en/latest/packaging_guide.html#license) as well as usage of [Licensed compilers](http://spack.readthedocs.io/en/latest/getting_started.html#licensed-compilers). For example in order to install MKL on Linux:
420
421 1. add `Intel` license file as `license.lic` file to `${SPACK_ROOT}/etc/spack/licenses/intel/`.
422 2. run `spack install dealii ^intel-mkl@11.3.2.210`
423
424 In order to configure Intel compilers see [this page](http://spack.readthedocs.io/en/latest/getting_started.html#vendor-specific-compiler-configuration).
425
426
427 ### Freeze package versions
428 Currently Spack does not try to re-use already installed packages. On another hand, by default
429 the most recent version of a package will be installed. When updating deal.II build (for example to use the new version of `trilinos`), the combination of the two factors may lead to recompilation of many other packages used in the deal.II suite when one of the main build dependency like `cmake` has a new version.
430
431 To circumvent the problem, the user can specify preferred versions of packages in `~/.spack/packages.yaml`:
432 ```
433 packages:
434   cmake:
435     version: [3.6.1]
436   curl:
437     version: [7.50.3]
438   openssl:
439     version: [1.0.2j]
440   python:
441     version: [2.7.12]
442 ```
443 This settings will be taken into account during conretization process and thus will help to avoid rebuilding most of the deal.II suite when, for example, `openssl` is updated to the new version.

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.