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

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.