update tested hash for CentOS cluster instructions
[dealii.wiki.git] / deal.II-in-Spack.md
1 # Using deal.II on Mac OS X and Linux via Spack
2
3 The deal.II suite is also available on Spack (https://github.com/LLNL/spack) -- a flexible package manager developed with High-Performance-Computing in mind. It is intended to let you build for many combinations of compiler, architectures, dependency libraries, and build configurations, all with a friendly, intuitive user interface.
4
5 For a quick overview of Spack's features, we recommend this short presentation https://tgamblin.github.io/files/Gamblin-Spack-SC15-Talk.pdf
6
7 ## Quick installation on the desktop
8
9 Add the following to `~/.bashrc` (or equivalent)
10 ```
11 export SPACK_ROOT=/path/to/spack
12 PATH="$SPACK_ROOT/bin:$PATH"
13 ```
14 `SPACK_ROOT` is the destination where you want Spack to be installed (i.e. `$HOME/spack`).
15
16 Now clone Spack
17 ```
18 cd $SPACK_ROOT
19 git clone https://github.com/llnl/spack.git .
20 git checkout develop
21 # the following commit was tested on:
22 # - Ubuntu16.04+gcc5.4.0 PC
23 #   spack install dealii+mpi ^openmpi ^openblas
24 git reset --hard 1124bdc99ee84c26201c40536d9b04dac74d7f6a
25 ```
26
27 **Make sure C/C++/Fortran compilers are in path** (on Ubuntu you need to `sudo apt-get install gfortran`, on macOS you can compile `gcc` with spack, see [below](#install-gcc)), and you have **curl** (`sudo apt-get install curl`) to download packages. Then install the complete deal.II suite
28 ```
29 spack install dealii
30 ```
31 **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.
32
33 Before configuring your project you need to set `DEAL_II_DIR` by 
34 ```
35 export DEAL_II_DIR=$(spack location -i dealii)
36 ```
37 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).
38
39
40 ## Installation example on a Centos7 cluster (Emmy cluster of RRZE, Erlangen, Germany)
41 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.
42
43 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:
44
45 (1) Download spack
46 ```
47 module load git
48 mkdir $WOODYHOME/spack
49 cd $WOODYHOME/spack
50 git clone https://github.com/llnl/spack.git $WOODYHOME/spack
51 git reset --hard 715ac8b7e67b094c094ec290729c5257cd565a0c
52 export PATH=$WOODYHOME/spack/bin:$PATH
53 ```
54 (2) Load `openmpi` and let Spack find GCC compiler which is also loaded as a dependency:
55 ```
56 module load openmpi/2.0.2-gcc
57 spack compiler find
58 ```
59 (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`
60 ```
61 packages:
62   all:
63     compiler: [gcc]
64     providers:
65       mpi: [openmpi]
66       blas: [openblas]
67       lapack: [openblas]
68   python:
69     version: [2.7.12]
70     paths:
71       python@2.7.12: /usr/
72     buildable: False
73   openmpi:
74     version: [2.0.2]
75     paths:
76       openmpi@2.0.2%gcc@4.8.5: /apps/OpenMPI/2.0.2-gcc/
77     buildable: False
78   dealii:
79     version: [develop]
80     variants: +optflags~python
81 ```
82 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.
83
84 (4) Now install deal.II:  `spack install dealii`.
85
86 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.
87
88
89 ## Environment Modules
90 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
91
92 To add the support for Environment Modules run
93 ```
94 spack install environment-modules
95 ```
96 Get the path to the prefix of `environment-modules` by:
97 ```
98 spack location --install-dir environment-modules
99 ```
100 and then add to `~/.bashrc` (or equivalent)
101 ```
102 MODULES_HOME=/path/to/environment-modules
103 source ${MODULES_HOME}/Modules/init/bash
104 . $SPACK_ROOT/share/spack/setup-env.sh
105 ```
106
107 If you install `deal.II` before setting up environment modules,
108 the module files have to be regenerated
109 ```
110 spack module refresh
111 ```
112
113 Then run
114 ```
115 spack load dealii
116 spack load cmake
117 ```
118 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)`.
119
120 ## System provided packages
121 Spack is flexible to use both self-compiled and system provided packages. 
122 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
123 ```
124 packages:
125   openmpi:
126     version: [1.8.8]
127     paths:
128       openmpi@1.8.8%gcc@6.2.0: /opt/openmpi-1.8.8
129     buildable: False
130 ```
131 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]`.
132
133 One can also specify which packages should be used to provide `mpi`, `blas/lapack` , preferred compilers and preferred variants:
134 ```
135 packages:
136   all:
137     compiler: [gcc,clang]
138     providers:
139       mpi: [openmpi]
140       blas: [openblas]
141       lapack: [openblas]
142     boost:
143       variants: +python
144 ```
145
146 For more elaborated discussion, see [Configuration Files in Spack](http://spack.readthedocs.io/en/latest/configuration.html).
147
148 ## Installing GCC
149 If your system does not provide any Fortran compiler or you want to have the most recent `gcc`,
150 you can install it by
151 ```
152 spack install gcc
153 ```
154
155 Assuming that you configured [Environment Modules](#environment-modules), load `gcc` and let Spack find the newly installed compilers:
156 ```
157 spack load gcc
158 spack compiler find
159 ```
160 Now you can install deal.II with `gcc`
161 ```
162 spack install dealii%gcc
163 ```
164
165 If you are on the mac, read the following instructions on [Mixed Toolchains](http://spack.readthedocs.io/en/latest/getting_started.html#mixed-toolchains).
166
167 On following these instructions, you will be able to install deal.II with clang+gfortran
168 ```
169 spack install dealii%clang
170 ```
171
172 ## Best practices using Spack:
173
174 Spack is complicated and flexible package manager primarily aimed at High-Performance-Computing.
175 Below are some examples of using Spack to build and develop deal.II:
176
177 ### Info:
178 If you are not sure which options a given package has, simply run
179 ```
180 spack info <package>
181 ```
182 The output will contain available versions, variants, dependencies and description:
183 ```
184 $ spack info dealii
185 CMakePackage:    dealii
186 Homepage:        https://www.dealii.org
187
188 Safe versions:
189     develop    [git] https://github.com/dealii/dealii.git
190     8.4.2      https://github.com/dealii/dealii/releases/download/v8.4.2/dealii-8.4.2.tar.gz
191     8.4.1      https://github.com/dealii/dealii/releases/download/v8.4.1/dealii-8.4.1.tar.gz
192     8.4.0      https://github.com/dealii/dealii/releases/download/v8.4.0/dealii-8.4.0.tar.gz
193     8.3.0      https://github.com/dealii/dealii/releases/download/v8.3.0/dealii-8.3.0.tar.gz
194     8.2.1      https://github.com/dealii/dealii/releases/download/v8.2.1/dealii-8.2.1.tar.gz
195     8.1.0      https://github.com/dealii/dealii/releases/download/v8.1.0/dealii-8.1.0.tar.gz
196
197 Variants:
198     Name        Default   Description
199
200     arpack      on        Compile with Arpack and PArpack (only with MPI)
201     doc         off       Compile with documentation
202     gsl         on        Compile with GSL
203     hdf5        on        Compile with HDF5 (only with MPI)
204     int64       off       Compile with 64 bit indices support
205     metis       on        Compile with Metis
206     mpi         on        Compile with MPI
207     netcdf      on        Compile with Netcdf (only with MPI)
208     oce         on        Compile with OCE
209     p4est       on        Compile with P4est (only with MPI)
210     petsc       on        Compile with Petsc (only with MPI)
211     python      on        Compile with Python bindings
212     slepc       on        Compile with Slepc (only with Petsc and MPI)
213     trilinos    on        Compile with Trilinos (only with MPI)
214
215 Installation Phases:
216     cmake    build    install
217
218 Build Dependencies:
219     arpack-ng  blas  boost  bzip2  cmake  doxygen  graphviz  gsl  hdf5  lapack  metis  mpi  muparser  netcdf  netcdf-cxx  oce  p4est  petsc  python  slepc  suite-sparse  tbb  trilinos  zlib
220
221 Link Dependencies:
222     arpack-ng  blas  boost  bzip2  doxygen  graphviz  gsl  hdf5  lapack  metis  mpi  muparser  netcdf  netcdf-cxx  oce  p4est  petsc  python  slepc  suite-sparse  tbb  trilinos  zlib
223
224 Run Dependencies:
225     None
226
227 Virtual Packages:
228     None
229
230 Description:
231     C++ software library providing well-documented tools to build finite
232     element codes for a broad variety of PDEs.
233 ```
234
235 A lot of `spack` commands have help, for example
236 ```
237 $spack install -h
238 usage: spack install [-h] [--only {package,dependencies}] [-j JOBS]
239                      [--keep-prefix] [--keep-stage] [-n] [-v] [--fake]
240                      [--clean | --dirty] [--run-tests] [--log-format {junit}]
241                      [--log-file LOG_FILE]
242                      ...
243
244 positional arguments:
245   package               spec of the package to install
246
247 optional arguments:
248   -h, --help            show this help message and exit
249   --only {package,dependencies}
250                         select the mode of installation. the default is to
251                         install the package along with all its dependencies.
252                         alternatively one can decide to install only the
253                         package or only the dependencies
254   -j JOBS, --jobs JOBS  explicitly set number of make jobs. default is #cpus
255   --keep-prefix         don't remove the install prefix if installation fails
256   --keep-stage          don't remove the build stage if installation succeeds
257   -n, --no-checksum     do not check packages against checksum
258   -v, --verbose         display verbose build output while installing
259   --fake                fake install. just remove prefix and create a fake
260                         file
261   --clean               clean environment before installing package
262   --dirty               do NOT clean environment before installing
263   --run-tests           run package level tests during installation
264   --log-format {junit}  format to be used for log files
265   --log-file LOG_FILE   filename for the log file. if not passed a default
266                         will be used
267 ```
268
269 ### Extra options:
270 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
271 ```
272 spack install dealii@develop+mpi~python ^boost+python
273 ```
274
275 If you want to specify blas/lapack/mpi implementations, this can be done similarly
276 ```
277 spack install dealii@develop+mpi ^mpich
278 ```
279 To check which packages implement `mpi` run
280 ```
281 spack providers mpi
282 ```
283 One can also specify which Blas/Lapack implementation to use. For example to build deal.II suite with `atlas` run
284 ```
285 spack install dealii ^atlas
286 ```
287
288 ### Compiler flags
289 You can specify compiler flags on the command line as
290 ```
291 spack install dealii cppflags="-march=native -O3"
292 ```
293 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`:
294 ```
295 compilers:
296 - compiler:
297     modules: []
298     operating_system: centos6
299     paths:
300       cc: /usr/bin/gcc
301       cxx: /usr/bin/g++
302       f77: /usr/bin/gfortran
303       fc: /usr/bin/gfortran
304     flags:
305       cflags: -O3 -fPIC
306       cxxflags: -O3 -fPIC
307       cppflags: -O3 -fPIC
308     spec: gcc@4.7.2
309 ```
310
311 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:
312 ```
313 spack install --only dependencies dealii
314 spack install dealii cppflags="-march=native -O3"
315 ```
316
317 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.
318
319 ### Different versions coexisting:
320 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
321 ```
322 spack install dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
323 ```
324 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.
325
326 One can use `environment-modules` (see above) to automatically set `DEAL_II_DIR` to the complex version: 
327 ```
328 spack load dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
329 ```
330
331 ### Filesystem Views:
332 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):
333 ```
334 spack view -v symlink dealii_suite dealii@develop
335 ```
336 You can also add to this view other packages, i.e.
337 ```
338 spack view -v symlink dealii_suite the-silver-searcher
339 ```
340
341
342 ### Check before build:
343 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. 
344 ```
345 spack spec dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
346 ```
347
348 ### Develop using Spack
349 There are several ways to use Spack while contributing patches to the deal.II. The simplest 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. For example on macOS with `openblas`:
350 ```
351 export DEAL_II_VIEW=/Users/davydden/spack/_dealii_suite
352 cmake -DCMAKE_FIND_FRAMEWORK=LAST -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=FALSE -DCMAKE_INSTALL_RPATH=${DEAL_II_VIEW} -DCMAKE_BUILD_TYPE=DebugRelease -DDEAL_II_COMPONENT_EXAMPLES=ON -DDEAL_II_WITH_THREADS:BOOL=ON -DBOOST_DIR=${DEAL_II_VIEW} -DBZIP2_DIR=${DEAL_II_VIEW} -DLAPACK_FOUND=true -DLAPACK_INCLUDE_DIRS=${DEAL_II_VIEW}/include -DLAPACK_LIBRARIES=${DEAL_II_VIEW}/lib/libopenblas.dylib -DMUPARSER_DIR=${DEAL_II_VIEW} -DUMFPACK_DIR=${DEAL_II_VIEW} -DTBB_DIR=${DEAL_II_VIEW} -DZLIB_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_MPI:BOOL=ON -DCMAKE_C_COMPILER=${DEAL_II_VIEW}/bin/mpicc -DCMAKE_CXX_COMPILER=${DEAL_II_VIEW}/bin/mpic++ -DCMAKE_Fortran_COMPILER=${DEAL_II_VIEW}/bin/mpif90 -DGSL_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_GSL:BOOL=ON -DHDF5_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_HDF5:BOOL=ON -DP4EST_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_P4EST:BOOL=ON -DPETSC_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_PETSC:BOOL=ON -DSLEPC_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_SLEPC:BOOL=ON -DTRILINOS_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_TRILINOS:BOOL=ON -DMETIS_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_METIS:BOOL=ON -DDEAL_II_COMPONENT_DOCUMENTATION=OFF -DARPACK_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_ARPACK=ON -DDEAL_II_ARPACK_WITH_PARPACK=ON -DNETCDF_DIR=${DEAL_II_VIEW} -DOPENCASCADE_DIR=${DEAL_II_VIEW} -DDEAL_II_WITH_OPENCASCADE=ON ../
353 ```
354 Here we specify locations of libraries in `${DEAL_II_VIEW}` and also point to `mpi` compilers by `${DEAL_II_VIEW}/bin/mpicc` and alike. Keep in mind that the autodetection of `LAPACK` is turned off and therefore we specified full path to libs as `${DEAL_II_VIEW}/lib/libopenblas.dylib`. You would need to adjust the suffix if you are on Linux.
355
356 ### Keep the stage to run unit tests
357 By default, the build folder (aka `stage`) for each package is created in a temporary system dependent location.
358 This gets purge by system on next restart.
359 If you want to keep the stage after the installation, you need to do two things:
360 First, make spack use a custom location for stage by adding the following to your `~/.spack/config.yaml`:
361 ```
362 config:
363   build_stage:
364     - $spack/var/spack/stage
365 ```
366 Second, prescribe an extra argument to `install` command to keep the stage after successful installation:
367 ```
368 spack install --keep-stage dealii@develop
369 ```
370
371 ### MKL and Licensed software
372 Spack supports installation of [licensed software](http://spack.readthedocs.io/en/latest/packaging_guide.html#license). For example in order to install MKL on Linux:
373
374 1. add the `license.lic` file to `${SPACK_ROOT}/etc/spack/licenses/intel/`.
375 2. manually download Intel MKL archive `l_mkl_11.3.2.181.tgz` (Spack can not do it for you due to the license of `intel-mkl`).
376 3. `cd` to the folder with archive and run `spack install intel-mkl@11.3.2.181`.
377
378 One can then run `spack install dealii ^intel-mkl@11.3.2.181`.
379
380
381 ### Freeze package versions
382 Currently Spack does not try to re-use already installed packages. On another hand, by default
383 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.
384
385 To circumvent the problem, the user can specify preferred versions of packages in `~/.spack/packages.yaml`:
386 ```
387 packages:
388   cmake:
389     version: [3.6.1]
390   curl:
391     version: [7.50.3]
392   openssl:
393     version: [1.0.2j]
394   python:
395     version: [2.7.12]
396 ```
397 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.