Installation instructions and further information on deal.II

  1. System requirements
    1. Supported platforms
    2. Additional software requirements
  2. Installation
    1. Unpacking
    2. Configuring and building the library
    3. Configuring and building the documentation
    4. Configuration options
      1. Selecting optional compilation features
      2. Selecting optional library features
      3. Optional interfaces to other software packages
      4. More information on configuring and building the library
  3. License

System requirements

Supported platforms

deal.II is mostly developed on Linux using the GCC compiler. However, it is not platform specific and we strive to keep the source code compliant with the C++ 2014 Standard (see also here for PDFs of the various C++ standards).

deal.II supports at least the following platforms:

Most other combinations of POSIX-style operating systems and C++ Standard compliant compilers should also work. If they don't, please report it as a bug.

Additional software requirements

In order to compile and use deal.II you need to have the following programs installed:

Installation

Unpacking

The whole library usually comes as a tar.gz file, which is a file archive compressed with gzip. After downloading it, unpack it using either

  gunzip deal.II-X.Y.Z.tar.gz
  tar xf deal.II-X.Y.Z.tar
    

or, if you have GNU tar with

  tar -xvf deal.II-X.Y.Z.tar.gz
    

Note: You will want to hang on to the source files of deal.II after installation as it makes developing much simpler. Consequently, you should do the steps above in a permanent directory, not on /tmp as one often does when installing software.

Configuring and building the library

deal.II uses the CMake integrated configuration and build system. Unpacking will create a subdirectory deal.II/ in the current directory. Then do the following steps to configure the build process (make sure the installation directory is not the same as the location where you unpacked deal.II/):

  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/dir ../deal.II
    
We recommend compiling deal.II in parallel if your machine has more than one processor core. This can be done by providing the --jobs=N flag to make with a numerical argument N. (The argument --jobs=N is often abbreviated as -jN.) Here we compile with four make jobs:
  make --jobs=4 install
  make test
    
One should usually use one job for each processor core on the machine.

These steps compile, link, install the deal.II library, and run a few consistency checks. The whole process should take between a few minutes and an hour, depending on your machine.

Notes:

The commands above build and install the deal.II libraries in two variants:

At this point, you have generated everything necessary to write programs based on deal.II. If you are new to deal.II, you may want to continue with the tutorial.

Configuring and building the documentation

All the documentation about the version that you downloaded and that can be found at the http://www.dealii.org/ domain can also be generated locally. To do so, invoke cmake in the build instructions above as follows:

      cmake -DDEAL_II_COMPONENT_DOCUMENTATION=ON -DCMAKE_INSTALL_PREFIX=/path/install/dir ../deal.II
      make documentation
      make install
    

As usual, you can pass -jN to make in order to use more than one processor. For this to succeed, you will need Perl 5.x, doxygen and dot (which is part of the GraphViz package) to be installed.

The documentation contains links to pictures (e.g., for the tutorial programs) that are by default stored online at the dealii.org domain. If you want to use the documentation completely offline, you can run the contrib/utilities/makeofflinedoc.sh script in an installed documentation directory to download all images.

Finally, the default for locally installed documentation is to render formulas as images. You can force formulas to be displayed via the MathJax system by adding -DDEAL_II_DOXYGEN_USE_MATHJAX=ON to the CMake call above. These formulas are then rendered natively by the browser. With -DDEAL_II_DOXYGEN_USE_ONLINE_MATHJAX=OFF CMake will try to find a local installation of MathJax scripts, otherwise the online version of the scripts will be used in the documentation.

Note: Generating this documentation can take a really long time — running doxygen through our hundreds of thousands of lines of code can take 15-20 minutes even on a fast machine during which you will not get any output from make.

Configuration options

deal.II has a large number of optional interfaces to other libraries. By default, cmake will automatically enable support for all external libraries it can find in default paths. However, this behavior can be changed using command line switches to the initial call to cmake. A detailed description can be found here: Detailed build system description.

In the following, let us summarize the most common configuration options.

Selecting optional compilation features

Selecting optional library features

Optional interfaces to other software packages

When configuring interfacing to external libraries, the cmake script by default tries to find all of these libraries in a number of standard locations on your file system. For optional interfaces, it gives up if the library is not found and deal.II will be built without support for them. However, there is one interface that we need to have: BOOST 1.59 or newer. If it is not found externally cmake will resort to the bundled boost version that is part of the deal.II tar file.

The following paragraphs describe how the interfaces to the various packages, deal.II interacts with, can be configured.

Notes:

ADOL-C

ADOL-C is a package that facilitates the evaluation of first and higher derivatives of vector functions. In particular, it can be used for automatic differentiation. For using ADOL-C with deal.II, version 2.6.4 or newer is required. To use a self compiled version, pass -DADOLC_DIR=/path/to/adolc to the deal.II CMake call.

ArborX

ArborX is an open-source library designed to provide performance portable algorithms for geometric search, similarly to nanoflann and Boost Geometry. To use a self compiled version, pass -DARBORX_DIR=/path/to/arborx to the deal.II CMake call. To use ArborX, deal.II needs to be configured with Kokkos support.

ARPACK

ARPACK is a library for computing large scale eigenvalue problems. ARPACK should be readily packaged by most Linux distributions. To use a self compiled version, pass -DARPACK_DIR=/path/to/arpack to the deal.II CMake call. For a detailed description on how to compile ARPACK and linking with deal.II, see this page.

Assimp

is a portable Open Source library to import various well-known 3D model formats in a uniform manner. A subset of these formats can be read from within deal.II to generate two-dimensional meshes, possibly embedded in a three-dimensional space. Assimp should be readily packaged by most Linux distributions. To use a self compiled version, pass -DASSIMP_DIR=/path/to/assimp to the deal.II CMake call.

BLAS, LAPACK

BLAS (the Basic Linear Algebra Subroutines) and LAPACK ( Linear Algebra Package) are two packages that support low-level linear algebra operations on vectors and dense matrices. Both libraries should be packaged by almost all Linux distributions and found automatically whenever available. (You might have to install development versions of the libraries for deal.II being able to use them). For details on how to set up deal.II with a non standard BLAS/LAPACK implementation, see the advanced setup section in the CMake ReadME.

CUDA

CUDA is a parallel computing platform and API model created by Nvidia. It allows software developers and software engineers to use CUDA-enabled GPU for general purpose processing. Details about compatibility and configuration can be found here.

Ginkgo

Ginkgo is a numerical linear algebra library with highly optimized kernels for many core architectures with a focus on fine level parallelism. It allows for easy switching of the executing paradigm (CUDA, OpenMP, etc.) while providing a multitude of linear solvers and preconditioners and extension to other linear operators with minimal changes required in the code. To enable Ginkgo, pass -DGINKGO_DIR=/path/to/ginkgo to CMake when configuring deal.II. For more detailed instructions, one can refer to this page.

Gmsh

Gmsh is a 3D mesh generator. The executable can be used to create meshes from within deal.II by specifying the relevant input data. Gmsh should be readily packaged by most Linux distributions. To use a self compiled version, pass -DGMSH_DIR=/path/to/gmsh to the deal.II CMake call. Note that netgen, tetgen and blas support has to be enabled in Gmsh.

GSL

The GNU Scientific Library provides a wide range of mathematical routines such as random number generators, special functions and least-squares fitting. GSL should be readily packaged by most Linux distributions. To use a self compiled version, pass -DGSL_DIR=/path/to/gsl to the deal.II CMake call.

HDF5

The HDF5 library provides graphical output capabilities in HDF5/XDMF format. HDF5 should be readily packaged by most Linux distributions. To use a self compiled version, pass -DHDF5_DIR=/path/to/hdf5 to the deal.II CMake call.

Kokkos

Kokkos implements a programming model in C++ for writing performance portable applications targeting all major HPC platforms. To use a self compiled version, pass -DKOKKOS_DIR=/path/to/kokkos to the deal.II CMake call.

METIS

METIS is a library that provides various methods to partition graphs. deal.II uses it in programs like the step-17 tutorial to partition a mesh for parallel computing. To use a self compiled version, pass -DMETIS_DIR=/path/to/metis to the deal.II CMake call. deal.II supports METIS 5 and later.

Note: A more modern way to support parallel computations is shown in the step-40 tutorial program and is based on the p4est library instead of METIS. See below on installing p4est.

muparser

muparser is a library that allows to enter functions in text form and have them interpreted at run time. This is particularly useful in input parameter files. cmake will usually find the version of this library that comes bundled with deal.II, but you can specify -DMUPARSER_DIR=/path/to/muparser if desired.

OpenCASCADE
Open CASCADE Technology is a software development kit for applications dealing with 3D CAD data, freely available in open source. Our internal interface works with the legacy version of OpenCASCADE, which you can download and install from the official website, as well as with the OpenCASCADE Community Edition (OCE, available at https://github.com/tpaviot/oce), which offers a cmake interface for its compilation. Alternatively, you can install one of the many external applications that ship with OpenCASCADE internally (for example SALOME, or FreeCAD). Further installation instructions can be found here.
p4est

p4est is a library that deal.II uses to distribute very large meshes across multiple processors (think meshes with a billion cells on 10,000 processors). Using and installing p4est is discussed here. To use a self compiled version, pass the argument -DP4EST_DIR=/path/to/p4est to the cmake command.

PETSc

PETSc is a library that supports parallel linear algebra and many other things. PETSc is already packaged by some Linux distributions and should be found automatically if present. To use a self compiled version of PETSc, add -DPETSC_DIR=/path/to/petsc -DPETSC_ARCH=architecture to the argument list for cmake. The values for these arguments must be the same as those specified when building PETSc.

To disable the PETSc interfaces in cases where cmake automatically finds it, use -DDEAL_II_WITH_PETSC=OFF. More information on configuring and building PETSc can be found here.

ScaLAPACK

scalapack is a library of high-performance linear algebra routines for parallel distributed memory machines. ScaLAPACK solves dense and banded linear systems, least squares problems, eigenvalue problems, and singular value problems. In order to enable this feature, add -DSCALAPACK_DIR=/path/to/scalapack to the argument list for cmake. If ScaLAPACK does not have embedded BLACS, you might need to pass -DBLACS_DIR=/path/to/blacs as well.

SLEPc

SLEPc is a library for eigenvalue computations that builds on PETSc. Its configuration works just like that for PETSc, except that the variable to set is SLEPC_DIR. For the interface with SLEPc to work, deal.II's PETSc interface must also be configured correctly (see above).

To disable the SLEPc interfaces in cases where cmake automatically finds it, use -DDEAL_II_WITH_PETSC=OFF. More information on configuring and building SLEPc can be found here.

SUNDIALS

SUNDIALS is a collection of solvers for nonlinear and differential/algebraic equations. SUNDIALS should be readily packaged by most Linux distributions. To use a self compiled version, specify -DSUNDIALS_DIR=/path/to/sundials to the deal.II CMake call.

SymEngine

SymEngine is a symbolic manipulation package, implementing the building blocks of a computer algebra system (CAS) similar to SymPy. In particular, it can be used for symbolic differentiation. For using SymEngine with deal.II, version 0.4 or newer is required. To use a self compiled version, pass -DSYMENGINE_DIR=/path/to/symengine to the deal.II CMake call.

Threading Building Blocks (TBB)

The Threading Building Blocks (TBB) is a library that provides advanced services for using multiple processor cores on a single machine and is used in deal.II to parallelize many operations. If not found in a system-wide location, cmake will resort to the version bundled as part of the deal.II download. It is always enabled unless threads are explicitly disabled, see above.

Trilinos

Trilinos is a library for parallel linear algebra and all sorts of other things as well. To interface with a self compiled version of Trilinos add -DTRILINOS_DIR=/path/to/trilinos to the argument list for cmake. Alternatively, you can also set an environment variable TRILINOS_DIR and cmake will pick up this path.

To disable the Trilinos interfaces in cases where cmake automatically finds it, use -DDEAL_II_WITH_TRILINOS=OFF. More details about compatibility and configuration can be found here.

UMFPACK

UMFPACK, which is part of SuiteSparse, is a sparse direct solver that we often use in prototype codes where the goal is to simply get a linear system solved robustly. The interface will be enabled by default, either using a version installed on your system of using a version that comes bundled with deal.II. It can be disabled explicitly by using the -DDEAL_II_WITH_UMFPACK=OFF argument. To use a self compiled version, pass the argument -DUMFPACK_DIR=/path/to/umfpack to the cmake command.

SuiteSparse has its own license. To use it with deal.II, please read it and make sure that you agree with it. You can find the license of SuiteSparse inside the SuiteSparse download at the link given above. We include UMFPACK in the deal.II repository courtesy of its author, Timothy A. Davis.

zlib

zlib is a software library used for lossless data-compression. It is used in deal.II whenever compressed data is to be written. zlib should be readily packaged by most Linux distributions. To use a self compiled version, pass -DZLIB_DIR=/path/to/zlib to the deal.II CMake call.

More information on configuring and building the library

The deal.II cmake system allows far greater control over what exactly is configured or built than just the outline above. If you want to learn more about this, take a look here. You might also be interested in CMake for user projects or build system internals.

License

The deal.II library is free software; you can use it, redistribute it, and/or modify it under the terms of the GNU Lesser General Public License (LGPL) as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This allows you to use the library free of charge for private, academic, or commercial use (under the terms of the LGPL v2.1 or later). You are guaranteed full access to the source code and are encouraged to help in the further development of the library. Follow this link for detailed information.

Please note:


Valid HTML 4.01! Valid CSS!