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

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.