add links to videos
[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 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 with deal.II.
11
12 ## Quick installation on the desktop
13
14 Add the following to `~/.bashrc` (or equivalent)
15 ```
16 export SPACK_ROOT=/path/to/spack
17 PATH="$SPACK_ROOT/bin:$PATH"
18 ```
19 `SPACK_ROOT` is the destination where you want Spack to be installed (i.e. `$HOME/spack`).
20
21 Now clone Spack
22 ```
23 cd $SPACK_ROOT
24 git clone https://github.com/llnl/spack.git .
25 git checkout develop
26 # the following commit (Sep2017) was tested on:
27 # - Ubuntu16.04 PC
28 #   [x] spack install dealii%gcc@5.4.0+mpi ^openmpi ^openblas
29 #   [x] spack install dealii%gcc@5.4.0+mpi ^mpich ^openblas
30 #   [x] spack install dealii%gcc@5.4.0+mpi ^openmpi ^intel-mkl
31 #   [x] spack install dealii%gcc@5.4.0+mpi ^openmpi ^atlas
32 #   [x] spack install dealii%gcc@5.4.0+mpi+int64 ^openmpi ^openblas
33 # - macOS Sierra 10.12.4 XCode 8.3.1 clang@8.1.0+gfortran@6.3.0
34 #   [x] spack install dealii@develop+mpi ^openmpi ^openblas 
35 # - CentOS 7 cluster with GCC 4.8.5 (see below) and external OpenMPI
36 #   [x] spack install dealii
37 git reset --hard 8db69de2583d4f8ff5b20041e3eba68780cbd05b
38 ```
39
40 **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
41 ```
42 spack install dealii
43 ```
44 **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.
45
46 Before configuring your project you need to set `DEAL_II_DIR` by 
47 ```
48 export DEAL_II_DIR=$(spack location -i dealii)
49 ```
50 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).
51
52
53 ## Installation example on a Centos7 cluster (Emmy cluster of RRZE, Erlangen, Germany)
54 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.
55
56 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:
57
58 (1) Download spack
59 ```
60 module load git
61 mkdir $WOODYHOME/spack
62 cd $WOODYHOME/spack
63 git clone https://github.com/llnl/spack.git $WOODYHOME/spack
64 git reset --hard 8db69de2583d4f8ff5b20041e3eba68780cbd05b
65 export PATH=$WOODYHOME/spack/bin:$PATH
66 ```
67 (2) Load `openmpi` and let Spack find GCC compiler which is also loaded as a dependency:
68 ```
69 module load openmpi/2.0.2-gcc
70 spack compiler find
71 ```
72 (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`
73 ```
74 packages:
75   all:
76     compiler: [gcc]
77     providers:
78       mpi: [openmpi]
79       blas: [openblas]
80       lapack: [openblas]
81   python:
82     version: [2.7.12]
83     paths:
84       python@2.7.12: /usr/
85     buildable: False
86   openmpi:
87     version: [2.0.2]
88     paths:
89       openmpi@2.0.2%gcc@4.8.5: /apps/OpenMPI/2.0.2-gcc/
90     buildable: False
91   dealii:
92     variants: +optflags~python
93 ```
94 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.
95
96 (4) Now install deal.II:  `spack install dealii`.
97
98 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.
99
100
101 ## Environment Modules
102 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
103
104 To add the support for Environment Modules run
105 ```
106 spack install environment-modules
107 ```
108 Get the path to the prefix of `environment-modules` by:
109 ```
110 spack location --install-dir environment-modules
111 ```
112 and then add to `~/.bashrc` (or equivalent)
113 ```
114 MODULES_HOME=/path/to/environment-modules
115 source ${MODULES_HOME}/Modules/init/bash
116 . $SPACK_ROOT/share/spack/setup-env.sh
117 ```
118
119 If you install `deal.II` before setting up environment modules,
120 the module files have to be regenerated
121 ```
122 spack module refresh
123 ```
124
125 Then run
126 ```
127 spack load dealii
128 spack load cmake
129 ```
130 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)`.
131
132 ## System provided packages
133 Spack is flexible to use both self-compiled and system provided packages. 
134 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
135 ```
136 packages:
137   openmpi:
138     version: [1.8.8]
139     paths:
140       openmpi@1.8.8%gcc@6.2.0: /opt/openmpi-1.8.8
141     buildable: False
142 ```
143 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]`.
144
145 One can also specify which packages should be used to provide `mpi`, `blas/lapack` , preferred compilers and preferred variants:
146 ```
147 packages:
148   all:
149     compiler: [gcc,clang]
150     providers:
151       mpi: [openmpi]
152       blas: [openblas]
153       lapack: [openblas]
154     boost:
155       variants: +python
156 ```
157
158 For more elaborated discussion, see [Configuration Files in Spack](http://spack.readthedocs.io/en/latest/configuration.html).
159
160 ## Installing GCC
161 If your system does not provide any Fortran compiler or you want to have the most recent `gcc`,
162 you can install it by
163 ```
164 spack install gcc
165 ```
166
167 Assuming that you configured [Environment Modules](#environment-modules), load `gcc` and let Spack find the newly installed compilers:
168 ```
169 spack load gcc
170 spack compiler find
171 ```
172 Now you can install deal.II with `gcc`
173 ```
174 spack install dealii%gcc
175 ```
176
177 If you are on the mac, read the following instructions on [Mixed Toolchains](http://spack.readthedocs.io/en/latest/getting_started.html#mixed-toolchains).
178
179 On following these instructions, you will be able to install deal.II with clang+gfortran
180 ```
181 spack install dealii%clang
182 ```
183
184 ## Best practices using Spack:
185
186 Spack is complicated and flexible package manager primarily aimed at High-Performance-Computing.
187 Below are some examples of using Spack to build and develop deal.II:
188
189 ### Info:
190 If you are not sure which options a given package has, simply run
191 ```
192 spack info <package>
193 ```
194 The output will contain available versions, variants, dependencies and description:
195 ```
196 $ spack info dealii
197 CMakePackage:   dealii
198
199 Description:
200     C++ software library providing well-documented tools to build finite
201     element codes for a broad variety of PDEs.
202
203 Homepage: https://www.dealii.org
204
205 Preferred version:  
206     8.5.1      https://github.com/dealii/dealii/releases/download/v8.5.1/dealii-8.5.1.tar.gz
207
208 Safe versions:  
209     develop    [git] https://github.com/dealii/dealii.git
210     8.5.1      https://github.com/dealii/dealii/releases/download/v8.5.1/dealii-8.5.1.tar.gz
211     8.5.0      https://github.com/dealii/dealii/releases/download/v8.5.0/dealii-8.5.0.tar.gz
212     8.4.2      https://github.com/dealii/dealii/releases/download/v8.4.2/dealii-8.4.2.tar.gz
213     8.4.1      https://github.com/dealii/dealii/releases/download/v8.4.1/dealii-8.4.1.tar.gz
214     8.4.0      https://github.com/dealii/dealii/releases/download/v8.4.0/dealii-8.4.0.tar.gz
215     8.3.0      https://github.com/dealii/dealii/releases/download/v8.3.0/dealii-8.3.0.tar.gz
216     8.2.1      https://github.com/dealii/dealii/releases/download/v8.2.1/dealii-8.2.1.tar.gz
217     8.1.0      https://github.com/dealii/dealii/releases/download/v8.1.0/dealii-8.1.0.tar.gz
218
219 Variants:
220     Name [Default]               Allowed values          Description
221
222
223     adol-c [off]                 True, False             Compile with Adol-c
224     arpack [on]                  True, False             Compile with Arpack and
225                                                          PArpack (only with MPI)
226     build_type [DebugRelease]    Debug, Release,         The build type to build
227                                  DebugRelease            
228     doc [off]                    True, False             Compile with documentation
229     gsl [on]                     True, False             Compile with GSL
230     hdf5 [on]                    True, False             Compile with HDF5 (only with
231                                                          MPI)
232     int64 [off]                  True, False             Compile with 64 bit indices
233                                                          support
234     metis [on]                   True, False             Compile with Metis
235     mpi [on]                     True, False             Compile with MPI
236     nanoflann [off]              True, False             Compile with Nanoflann
237     netcdf [on]                  True, False             Compile with Netcdf (only with
238                                                          MPI)
239     oce [on]                     True, False             Compile with OCE
240     optflags [off]               True, False             Compile using additional
241                                                          optimization flags
242     p4est [on]                   True, False             Compile with P4est (only with
243                                                          MPI)
244     petsc [on]                   True, False             Compile with Petsc (only with
245                                                          MPI)
246     python [on]                  True, False             Compile with Python bindings
247     slepc [on]                   True, False             Compile with Slepc (only with
248                                                          Petsc and MPI)
249     sundials [off]               True, False             Compile with Sundials
250     trilinos [on]                True, False             Compile with Trilinos (only
251                                                          with MPI)
252
253 Installation Phases:
254     cmake    build    install
255
256 Build Dependencies:
257     adol-c     bzip2     gsl     mpi        netcdf-cxx  python        tbb
258     arpack-ng  cmake     hdf5    muparser   oce         slepc         trilinos
259     blas       doxygen   lapack  nanoflann  p4est       suite-sparse  zlib
260     boost      graphviz  metis   netcdf     petsc       sundials
261
262 Link Dependencies:
263     adol-c     bzip2     hdf5    muparser    oce     slepc         trilinos
264     arpack-ng  doxygen   lapack  nanoflann   p4est   suite-sparse  zlib
265     blas       graphviz  metis   netcdf      petsc   sundials
266     boost      gsl       mpi     netcdf-cxx  python  tbb
267
268 Run Dependencies:
269     None
270
271 Virtual Packages: 
272     None
273 ```
274
275 A lot of `spack` commands have help, for example
276 ```
277 $ spack install -h
278 usage: spack install [-h] [--only {package,dependencies}] [-j JOBS]
279                      [--keep-prefix] [--keep-stage] [--restage] [-n] [-v]
280                      [--fake] [-f] [--clean | --dirty] [--run-tests]
281                      [--log-format {junit}] [--log-file LOG_FILE]
282                      ...
283
284 build and install packages
285
286 positional arguments:
287   package               spec of the package to install
288
289 optional arguments:
290   -h, --help            show this help message and exit
291   --only {package,dependencies}
292                         select the mode of installation. the default is to
293                         install the package along with all its dependencies.
294                         alternatively one can decide to install only the
295                         package or only the dependencies
296   -j JOBS, --jobs JOBS  explicitly set number of make jobs. default is #cpus
297   --keep-prefix         don't remove the install prefix if installation fails
298   --keep-stage          don't remove the build stage if installation succeeds
299   --restage             if a partial install is detected, delete prior state
300   -n, --no-checksum     do not check packages against checksum
301   -v, --verbose         display verbose build output while installing
302   --fake                fake install. just remove prefix and create a fake
303                         file
304   -f, --file            install from file. Read specs to install from .yaml
305                         files
306   --clean               clean environment before installing package
307   --dirty               do NOT clean environment before installing
308   --run-tests           run package level tests during installation
309   --log-format {junit}  format to be used for log files
310   --log-file LOG_FILE   filename for the log file. if not passed a default
311                         will be used
312 ```
313
314 ### Extra options:
315 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
316 ```
317 spack install dealii@develop+mpi~python ^boost+python
318 ```
319
320 If you want to specify blas/lapack/mpi implementations, this can be done similarly
321 ```
322 spack install dealii@develop+mpi ^mpich
323 ```
324 To check which packages implement `mpi` run
325 ```
326 spack providers mpi
327 ```
328 One can also specify which Blas/Lapack implementation to use. For example to build deal.II suite with `atlas` run
329 ```
330 spack install dealii ^atlas
331 ```
332
333 ### Compiler flags
334 You can specify compiler flags on the command line as
335 ```
336 spack install dealii cppflags="-march=native -O3"
337 ```
338 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`:
339 ```
340 compilers:
341 - compiler:
342     modules: []
343     operating_system: centos6
344     paths:
345       cc: /usr/bin/gcc
346       cxx: /usr/bin/g++
347       f77: /usr/bin/gfortran
348       fc: /usr/bin/gfortran
349     flags:
350       cflags: -O3 -fPIC
351       cxxflags: -O3 -fPIC
352       cppflags: -O3 -fPIC
353     spec: gcc@4.7.2
354 ```
355
356 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:
357 ```
358 spack install --only dependencies dealii
359 spack install dealii cppflags="-march=native -O3"
360 ```
361
362 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.
363
364 ### Different versions coexisting:
365 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
366 ```
367 spack install dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
368 ```
369 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.
370
371 One can use `environment-modules` (see above) to automatically set `DEAL_II_DIR` to the complex version: 
372 ```
373 spack load dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
374 ```
375
376 ### Filesystem Views:
377 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):
378 ```
379 spack view -v symlink dealii_suite dealii@develop
380 ```
381 You can also add to this view other packages, i.e.
382 ```
383 spack view -v symlink dealii_suite the-silver-searcher
384 ```
385
386
387 ### Check before build:
388 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. 
389 ```
390 spack spec dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
391 ```
392
393 The `spec` command has a useful flag `-I` which will show install status of dependencies in the graph.
394
395 ### Develop using Spack
396 Probably the easiest way to use Spack while contributing patches to the deal.II is the following. 
397 Install `deal.II` via Spack, go to its installation prefix and copy-paste the CMake command from `.spack/build.out`, which looks like
398 ```
399 '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>
400 ```
401 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. 
402
403 Before running `cmake` from the build folder, you may want to run 
404 ```
405 spack env dealii@develop+mpi^openmpi^openblas bash
406 ```
407 to make sure your environment (paths, variables, etc) is set exactly the same way as when compiling `deal.II` from Spack
408 (adjust the spec `dealii@develop+mpi^openmpi^openblas` to be what you use when you installed `deal.II`).
409
410 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. 
411
412 ### Keep the stage to run unit tests
413 By default, the build folder (aka `stage`) for each package is created in a temporary system dependent location.
414 This gets purge by system on next restart.
415 If you want to keep the stage after the installation, you need to do two things:
416 First, make spack use a custom location for stage by adding the following to your `~/.spack/config.yaml`:
417 ```
418 config:
419   build_stage:
420     - $spack/var/spack/stage
421 ```
422 Second, prescribe an extra argument to `install` command to keep the stage after successful installation:
423 ```
424 spack install --keep-stage dealii@develop
425 ```
426
427 ### MKL and Licensed software
428 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:
429
430 1. add `Intel` license file as `license.lic` file to `${SPACK_ROOT}/etc/spack/licenses/intel/`.
431 2. run `spack install dealii ^intel-mkl@11.3.2.210`
432
433 In order to configure Intel compilers see [this page](http://spack.readthedocs.io/en/latest/getting_started.html#vendor-specific-compiler-configuration).
434
435
436 ### Freeze package versions
437 Currently Spack does not try to re-use already installed packages. On another hand, by default
438 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.
439
440 To circumvent the problem, the user can specify preferred versions of packages in `~/.spack/packages.yaml`:
441 ```
442 packages:
443   cmake:
444     version: [3.6.1]
445   curl:
446     version: [7.50.3]
447   openssl:
448     version: [1.0.2j]
449   python:
450     version: [2.7.12]
451 ```
452 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.