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