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