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