Updated deal.II in Spack (markdown)
[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 `~/.bash_profile` (or equivalent)
8 ```
9 SPACK_ROOT=/path/to/spack
10 export PATH=$SPACK_ROOT/bin:$PATH
11 ```
12 `SPACK_ROOT` is the destination where you want Spack to be installed (i.e. `/Users/john/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 ```
20 `master` branch contains stable releases, whereas `develop` is the current development branch.
21
22 **Make sure C/C++/Fortran compilers are in path** (if that's not the case or you use macOS, see [below](#install-gcc)),
23 and 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 and then add to `~/.bash_profile` (or equivalent)
83 ```
84 MODULES_HOME=`spack location -i environment-modules`
85 source ${MODULES_HOME}/Modules/init/bash
86 . $SPACK_ROOT/share/spack/setup-env.sh
87 ```
88
89 If you install `deal.II` before setting up environment modules,
90 the module files have to be regenerated
91 ```
92 spack module refresh
93 ```
94
95 Then run
96 ```
97 spack load dealii
98 spack load cmake
99 ```
100 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)`.
101
102 ## System provided packages
103 Spack is flexible to use both self-compiled and system provided packages. 
104 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
105 ```
106 packages:
107   openmpi:
108     version: [1.8.8]
109     paths:
110       openmpi@1.8.8%gcc@6.2.0: /opt/openmpi-1.8.8
111     buildable: False
112 ```
113 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]`.
114
115 One can also specify which packages should be used to provide `mpi`, `blas/lapack` , preferred compilers and preferred variants:
116 ```
117 packages:
118   all:
119     compiler: [gcc,clang]
120     providers:
121       mpi: [openmpi]
122       blas: [openblas]
123       lapack: [openblas]
124     boost:
125       variants: +python
126 ```
127
128 For more elaborated discussion, see [Configuration Files in Spack](http://spack.readthedocs.io/en/latest/configuration.html).
129
130 ## Installing GCC
131 If your system does not provide any Fortran compiler or you want to have the most recent `gcc`,
132 you can install it by
133 ```
134 spack install gcc
135 ```
136
137 Assuming that you configured [Environment Modules](#environment-modules), load `gcc` and let Spack find the newly installed compilers:
138 ```
139 spack load gcc
140 spack compiler find
141 ```
142 Now you can install deal.II with `gcc`
143 ```
144 spack install dealii%gcc
145 ```
146
147 If you are on the mac, read the following instructions on [Mixed Toolchains](http://spack.readthedocs.io/en/latest/getting_started.html#mixed-toolchains).
148
149 On following these instructions, you will be able to install deal.II with clang+gfortran
150 ```
151 spack install dealii%clang
152 ```
153
154 ## Best practices using Spack:
155
156 Spack is complicated and flexible package manager primarily aimed at High-Performance-Computing.
157 Below are some examples of using Spack to build and develop deal.II:
158
159 ### Info:
160 If you are not sure which options a given package has, simply run
161 ```
162 spack info <package>
163 ```
164 The output will contain available versions, variants, dependencies and description:
165 ```
166 $ spack info dealii
167 Package:    dealii
168 Homepage:   https://www.dealii.org
169
170 Safe versions:
171     develop    [git] https://github.com/dealii/dealii.git
172     8.4.1      https://github.com/dealii/dealii/releases/download/v8.4.1/dealii-8.4.1.tar.gz
173     8.4.0      https://github.com/dealii/dealii/releases/download/v8.4.0/dealii-8.4.0.tar.gz
174     8.3.0      https://github.com/dealii/dealii/releases/download/v8.3.0/dealii-8.3.0.tar.gz
175     8.2.1      https://github.com/dealii/dealii/releases/download/v8.2.1/dealii-8.2.1.tar.gz
176     8.1.0      https://github.com/dealii/dealii/releases/download/v8.1.0/dealii-8.1.0.tar.gz
177
178 Variants:
179     Name        Default   Description
180
181     arpack      on        Compile with Arpack and PArpack (only with MPI)
182     doc         off       Compile with documentation
183     gsl         on        Compile with GSL
184     hdf5        on        Compile with HDF5 (only with MPI)
185     metis       on        Compile with Metis
186     mpi         on        Compile with MPI
187     netcdf      on        Compile with Netcdf (only with MPI)
188     oce         on        Compile with OCE
189     p4est       on        Compile with P4est (only with MPI)
190     petsc       on        Compile with Petsc (only with MPI)
191     slepc       on        Compile with Slepc (only with Petsc and MPI)
192     trilinos    on        Compile with Trilinos (only with MPI)
193
194 Build Dependencies:
195     zlib  blas  graphviz  netcdf  arpack-ng  bzip2  cmake  lapack  oce  astyle  boost  trilinos  muparser  p4est  mpi  suite-sparse  tbb  doxygen  hdf5  slepc  numdiff  metis  petsc  netcdf-cxx  gsl
196
197 Link Dependencies:
198     zlib  blas  graphviz  netcdf  arpack-ng  bzip2  lapack  oce  astyle  boost  trilinos  muparser  p4est  mpi  suite-sparse  tbb  doxygen  hdf5  slepc  numdiff  metis  petsc  netcdf-cxx  gsl
199
200 Run Dependencies:
201     None
202
203 Virtual packages:
204     None
205
206 Description:
207     C++ software library providing well-documented tools to build finite
208     element codes for a broad variety of PDEs.
209 ```
210
211 ### Extra options:
212 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
213 ```
214 spack install dealii@develop+mpi ^boost+python
215 ```
216
217 If you want to specify blas/lapack/mpi implementations, this can be done similarly
218 ```
219 spack install dealii@develop+mpi ^mpich
220 ```
221 To check which packages implement `mpi` run
222 ```
223 spack providers mpi
224 ```
225 One can also specify which Blas/Lapack implementation to use. For example to build deal.II suite with `atlas` run
226 ```
227 spack install dealii ^atlas
228 ```
229
230 ### Different versions coexisting:
231 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
232 ```
233 spack install dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
234 ```
235 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.
236
237 One can use `environment-modules` (see above) to automatically set `DEAL_II_DIR` to the complex version: 
238 ```
239 spack load dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
240 ```
241
242 ### Filesystem Views:
243 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):
244 ```
245 spack view -v symlink dealii_suite dealii@develop
246 ```
247 You can also add to this view other packages, i.e.
248 ```
249 spack view -v symlink dealii_suite the_silver_searcher
250 ```
251
252
253 ### Check before build:
254 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. 
255 ```
256 spack spec dealii@develop+mpi+petsc~int64%gcc ^petsc+complex~hypre
257 ```
258
259 ### Develop using Spack
260 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`:
261 ```
262 export DEAL_II_VIEW=/Users/davydden/spack/_dealii_suite
263 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 ../
264 ```
265 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.
266
267 ### Keep the stage to run unit tests
268 By default, the build folder (aka `stage`) for each package is created in a temporary system dependent location.
269 This gets purge by system on next restart.
270 If you want to keep the stage after the installation, you need to do two things:
271 First, make spack use a custom location for stage by adding the following to your `~/.spack/config.yaml`:
272 ```
273 config:
274   build_stage:
275     - $spack/var/spack/stage
276 ```
277 Second, prescribe an extra argument to `install` command to keep the stage after successful installation:
278 ```
279 spack install --keep-stage dealii@develop
280 ```
281
282 ### MKL and Licensed software
283 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:
284
285 1. add the `license.lic` file to `${SPACK_ROOT}/etc/spack/licenses/intel/`.
286 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`).
287 3. `cd` to the folder with archive and run `spack install intel-mkl@11.3.2.181`.
288
289 One can then run `spack install dealii ^intel-mkl@11.3.2.181`.
290
291
292 ### Freeze package versions
293 Currently Spack does not try to re-use already installed packages. On another hand, by default
294 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.
295
296 To circumvent the problem, the user can specify preferred versions of packages in `~/.spack/packages.yaml`:
297 ```
298 packages:
299   cmake:
300     version: [3.6.1]
301   curl:
302     version: [7.50.3]
303   openssl:
304     version: [1.0.2j]
305   python:
306     version: [2.7.12]
307 ```
308 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.