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