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