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