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