28cfa51c403f9494af14cf3c0f99270028f16ae7
[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 master
19 ```
20 **Make sure C/C++/Fortran compilers are in path** (if that's not the case or you use macOS, see [below](#install-gcc)),
21 and install the complete deal.II suite
22 ```
23 spack install dealii
24 ```
25 **DONE**! No extra (preliminary) configuration steps are needed on most Linux distributions. Before configuring your project you need to set `DEAL_II_DIR` by 
26 ```
27 export DEAL_II_DIR=$(spack location -i dealii)
28 ```
29 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).
30
31
32 ## Installation example on a cluster (Emmy cluster of RRZE, Erlangen, Germany)
33 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:
34
35 (1) Download spack
36 ```
37 module load git
38 mkdir $WOODYHOME/spack
39 git clone https://github.com/llnl/spack.git $WOODYHOME/spack
40 export PATH=$WOODYHOME/spack/bin:$PATH
41 ```
42 (2) Load `openmpi` and let Spack find GCC compiler which is also loaded as a dependency:
43 ```
44 module load openmpi/2.0.1-gcc
45 spack compiler find
46 ```
47 (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`
48 ```
49 packages:
50   all:
51     compiler: [gcc]
52     providers:
53       mpi: [openmpi]
54       blas: [openblas]
55       lapack: [openblas]
56   python:
57     version: [2.7.12]
58     paths:
59       python@2.7.12: /usr/
60     buildable: False
61   openmpi:
62     version: [2.0.1]
63     paths:
64       openmpi@2.0.1%gcc@4.8.5: /apps/OpenMPI/2.0.1-gcc/
65     buildable: False
66   dealii:
67     version: [develop]
68     variants: ~oce~python
69 ```
70 (4) Now install deal.II:  `spack install dealii`.
71
72
73 ## Environment Modules
74 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
75
76 To add the support for Environment Modules run
77 ```
78 spack install environment-modules
79 ```
80 and then add to `~/.bash_profile` (or equivalent)
81 ```
82 MODULES_HOME=`spack location -i environment-modules`
83 source ${MODULES_HOME}/Modules/init/bash
84 . $SPACK_ROOT/share/spack/setup-env.sh
85 ```
86
87 If you install `deal.II` before setting up environment modules,
88 the module files have to be regenerated
89 ```
90 spack module refresh
91 ```
92
93 Then run
94 ```
95 spack load dealii
96 spack load cmake
97 ```
98 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)`.
99
100 ## System provided packages
101 Spack is flexible to use both self-compiled and system provided packages. 
102 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
103 ```
104 packages:
105   openmpi:
106     version: [1.8.8]
107     paths:
108       openmpi@1.8.8%gcc@6.2.0: /opt/openmpi-1.8.8
109     buildable: False
110 ```
111 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]`.
112
113 One can also specify which packages should be used to provide `mpi`, `blas/lapack` , preferred compilers and preferred variants:
114 ```
115 packages:
116   all:
117     compiler: [gcc,clang]
118     providers:
119       mpi: [openmpi]
120       blas: [openblas]
121       lapack: [openblas]
122     boost:
123       variants: +python
124 ```
125
126 For more elaborated discussion, see [Configuration Files in Spack](http://spack.readthedocs.io/en/latest/configuration.html).
127
128 ## Installing GCC
129 If your system does not provide any Fortran compiler or you want to have the most recent `gcc`,
130 you can install it by
131 ```
132 spack install gcc
133 ```
134
135 Assuming that you configured [Environment Modules](#environment-modules), load `gcc` and let Spack find the newly installed compilers:
136 ```
137 spack load gcc
138 spack compiler find
139 ```
140 Now you can install deal.II with `gcc`
141 ```
142 spack install dealii%gcc
143 ```
144
145 If you are on the mac, read the following instructions on [Mixed Toolchains](http://spack.readthedocs.io/en/latest/getting_started.html#mixed-toolchains).
146
147 On following these instructions, you will be able to install deal.II with clang+gfortran
148 ```
149 spack install dealii%clang
150 ```
151
152 ## Best practices using Spack:
153
154 Spack is complicated and flexible package manager primarily aimed at High-Performance-Computing.
155 Below are some examples of using Spack to build and develop deal.II:
156
157 ### Info:
158 If you are not sure which options a given package has, simply run
159 ```
160 spack info <package>
161 ```
162 The output will contain available versions, variants, dependencies and description:
163 ```
164 $ spack info dealii
165 Package:    dealii
166 Homepage:   https://www.dealii.org
167
168 Safe versions:
169     develop    [git] https://github.com/dealii/dealii.git
170     8.4.1      https://github.com/dealii/dealii/releases/download/v8.4.1/dealii-8.4.1.tar.gz
171     8.4.0      https://github.com/dealii/dealii/releases/download/v8.4.0/dealii-8.4.0.tar.gz
172     8.3.0      https://github.com/dealii/dealii/releases/download/v8.3.0/dealii-8.3.0.tar.gz
173     8.2.1      https://github.com/dealii/dealii/releases/download/v8.2.1/dealii-8.2.1.tar.gz
174     8.1.0      https://github.com/dealii/dealii/releases/download/v8.1.0/dealii-8.1.0.tar.gz
175
176 Variants:
177     Name        Default   Description
178
179     arpack      on        Compile with Arpack and PArpack (only with MPI)
180     doc         off       Compile with documentation
181     gsl         on        Compile with GSL
182     hdf5        on        Compile with HDF5 (only with MPI)
183     metis       on        Compile with Metis
184     mpi         on        Compile with MPI
185     netcdf      on        Compile with Netcdf (only with MPI)
186     oce         on        Compile with OCE
187     p4est       on        Compile with P4est (only with MPI)
188     petsc       on        Compile with Petsc (only with MPI)
189     slepc       on        Compile with Slepc (only with Petsc and MPI)
190     trilinos    on        Compile with Trilinos (only with MPI)
191
192 Build Dependencies:
193     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
194
195 Link Dependencies:
196     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
197
198 Run Dependencies:
199     None
200
201 Virtual packages:
202     None
203
204 Description:
205     C++ software library providing well-documented tools to build finite
206     element codes for a broad variety of PDEs.
207 ```
208
209 ### Extra options:
210 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
211 ```
212 spack install dealii@develop+mpi ^boost+python
213 ```
214
215 If you want to specify blas/lapack/mpi implementations, this can be done similarly
216 ```
217 spack install dealii@develop+mpi ^mpich
218 ```
219 To check which packages implement `mpi` run
220 ```
221 spack providers mpi
222 ```
223 One can also specify which Blas/Lapack implementation to use. For example to build deal.II suite with `atlas` run
224 ```
225 spack install dealii ^atlas
226 ```
227
228 ### Different versions coexisting:
229 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
230 ```
231 spack install dealii@develop+mpi+petsc%gcc ^petsc+complex~hypre
232 ```
233 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.
234
235 One can use `environment-modules` (see above) to automatically set `DEAL_II_DIR` to the complex version: 
236 ```
237 spack load dealii%gcc^petsc+complex
238 ```
239
240 ### Filesystem Views:
241 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):
242 ```
243 spack view -v symlink dealii_suite dealii@develop
244 ```
245 You can also add to this view other packages, i.e.
246 ```
247 spack view -v symlink dealii_suite the_silver_searcher
248 ```
249
250
251 ### Check before build:
252 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. 
253 ```
254 spack spec dealii@develop+mpi+petsc%gcc ^petsc+complex~hypre
255 ```
256
257 ### Develop using Spack
258 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`:
259 ```
260 export DEAL_II_VIEW=/Users/davydden/spack/_dealii_suite
261 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 ../
262 ```
263 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.
264
265 ### MKL and Licensed software
266 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:
267
268 1. add the `license.lic` file to `${SPACK_ROOT}/etc/spack/licenses/intel/`.
269 2. manually download Intel MKL archive `l_mkl_11.3.2.181.tgz`
270 3. `cd` to the folder with archive and run `spack install mkl@11.3.2.181`.
271
272 One can then run `spack install dealii ^mkl@11.3.2.181`.
273
274
275 ### Freeze package versions
276 Currently Spack does not try to re-use already installed packages. On another hand, by default
277 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.
278
279 To circumvent the problem, the user can specify preferred versions of packages in `~/.spack/packages.yaml`:
280 ```
281 packages:
282   cmake:
283     version: [3.6.1]
284   curl:
285     version: [7.50.3]
286   openssl:
287     version: [1.0.2j]
288   python:
289     version: [2.7.12]
290 ```
291 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.