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