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