deal.II is a platform-independent library written in C++, with configuration and build support provided by CMake. Until deal.II version 9.5, deal.II used the C++14 standard; subsequent versions require C++17 (see here for PDFs of the various C++ standards).
The easiest way to install deal.II is to use the many packages available for different platforms. But it can of course also be compiled from scratch. Given that C++ compilers and CMake are available on a wide variety of platforms, deal.II can be compiled on most widely used systems. In particular, we regularly test that it can be compiled using the GCC compiler (on Linux and Windows), Clang (on Linux, and both Intel- and ARM-based Apple Mac systems via Xcode), the Intel compiler (on Linux), and Microsoft Visual Studio (on Microsoft Windows), as long as these compilers are sufficiently new to support the required language standard. You may want to take a look at deal.II Wiki for instructions on specific platforms. In general, most combinations of POSIX-style operating systems and C++ Standard compliant compilers should work. If they don't, please report it as a bug.
In order to compile and use deal.II you need to have the following programs installed:
dot, which is part of the
GraphViz package
The library generates output in formats readable by GNUPLOT, GMV (general mesh viewer), Tecplot (ASCII and binary), Visualization Toolkit (Vtk), AVS Explorer, Open DX, Povray, and directly to Encapsulated Postscript.
gnuplot and a postscript viewer (for eps) should be available almost everywhere. In the last few years, most new visualization programs have moved to support
vtk/vtu format. There are a number of excellent programs that can read vtk and
vtu, such as
VisIt,
ParaView, as well as others. Povray is freely available for almost all platforms. AVS is a commercial program available for most Unix flavors. Tecplot is a commercial program available
for Windows and most Unix platforms.
In case you didn't find your favorite graphics format above, adding a new writer to deal.II is not too difficult, as only a simple intermediate format needs to be converted into output (without references to cells, nodes, types of finite elements, and the like).
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.
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:
/path/to/install/dir" in the
command above needs to be replaced by the path to the directory which deal.II should be installed into. This can be a directory in your home directory (e.g., ~/bin/deal.II) or a directory such as /usr/local if you have root privileges.
Another option is to use something like `pwd`/../installed/ (note the backticks).
make test automatically runs in parallel and no -jN flag should be supplied to it.
build/ directory after the last step.
tar unpacked the file you downloaded) since projects using deal.II should only need files that
have been installed. However, you will find it convenient to keep the source files around anyway, for one reason: When debugging you often end up with assertions for which you'd like to see the place in the library's source files that triggered
it.
CMake system can accept a significant number of configuration parameters. See the discussion below.
cmake a second time, possibly with different arguments. However, this sometimes leads to surprising results and you may not get exactly what you were hoping for. For more information, see here.
-jN
with a large N might lead to situations where
not enough memory is available for all compilers, and this
typically manifests as an "internal compiler error" or a
segmentation fault. If that happens, just
reduce N and type the make install
command again.
The commands above build and install the deal.II libraries in two variants:
Debug mode: This version of the library is compiled with compiler flags so that the library contains information that can be used by debuggers.
In addition, this library contains a great number of safety checks on most arguments of all functions you could possibly call. These assertions have proven to be an invaluable means to finding programming bugs since they will almost always abort your program if something goes wrong. In our experience, more than ninety per cent of all errors are invalid parameters (such as vectors having the wrong size, etc.) and they are usually found almost instantaneously, displaying the file name and line number of where the problem occurred.
With GCC Debug mode, by default, uses the -Og flag. It promises most of the debugging experience of -O0 but at a better performance. This is a reasonable choice for unit tests and enables numerous asserts within
the library. Sometimes, however, one needs Debug mode to use
-O0, where all compiler optimizations are avoided and code and variables are exactly as indicated in the C++ program (e.g. with -Og GCC 6.2.0 optimizes out local variables). This can be achieved by configuring
deal.II with
-DDEAL_II_HAVE_FLAG_Og=false.
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.
All the documentation about the version that you downloaded and that can be found at the
https://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.
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.
-DDEAL_II_UNITY_BUILD=ON argument to cmake. This feature is disabled by default.
Threading: By default, deal.II supports parallelism between multiple cores on the same machine using threads and a task-based model built on the
Threading Building Blocks. You can switch threading inside the library off by passing the -DDEAL_II_WITH_TBB=OFF argument to cmake.
MPI: To enable parallel computations beyond a single node using the Message
Passing Interface (MPI), pass the
-DDEAL_II_WITH_MPI=ON argument to cmake. If cmake found MPI but you specifically do not want to use it, then pass -DDEAL_II_WITH_MPI=OFF.
The minimal supported version is MPI-3.0.
64bit indices: By default, deal.II uses
unsigned int (32bit) indices for degrees of freedom,
using the types::global_dof_index type.
(The same is true for a few other index types such as the
global number of cells.) This limits the number of
cells or unknowns to approximately four billions. If
larger problem must be solved, pass the
-DDEAL_II_WITH_64BIT_INDICES=ON argument to
cmake.
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:
-dev or -devel.
After that cmake will automatically find the
library and use it.
foo can usually be done by specifying
-DFOO_DIR=/path/to/foo. Alternatively, you can set FOO_DIR as an environment variable in your
.bashrc or .cshrc file so that you do not have to enter this argument again the next time you invoke cmake in a fresh build directory. Any value passed on the command line wins over a value that may be
found in an environment variable.
foo use the argument
-DDEAL_II_WITH_FOO=ON resp.
-DDEAL_II_WITH_FOO=OFF for cmake.
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 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 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.
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 (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 this page.
CGAL
is a software project that provides easy access to
efficient and reliable geometric algorithms in the form of a C++
library. CGAL is used in various areas needing geometric
computation, such as geographic information systems, computer
aided design, molecular biology, medical imaging, computer
graphics, and robotics.
The library offers data structures and algorithms like
triangulations, Voronoi diagrams, Boolean operations on polygons
and polyhedra, point set processing, arrangements of curves,
surface and volume mesh generation, geometry processing, alpha
shapes, convex hull algorithms, shape reconstruction, AABB and
KD trees.
The CGAL Wrappers use c++17 features. In order to use CGAL, add
-DCGAL_DIR=/path/to/cgal to the deal.II CMake call,
and make sure that DEAL_II_HAVE_CXX17 is enabled.
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
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
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.
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.
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 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.
The compiler must be able to compile code for all enabled backends. In case Cuda is enabled in Kokkos and nvcc should be used as device compiler,
it is recommended to use the nvcc_wrapper script that comes with Kokkos as C++ compiler. clang++ or nvc++ (for Kokkos >= 4.0) could be used directly as C++ compiler.
Also, Kokkos must be built with support for device lambdas, e.g., Kokkos_ENABLE_CUDA_LAMBDA=ON when configuring Kokkos with Cuda. For Kokkos >= 4.0 this is the default.
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 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.
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 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 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 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 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 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.
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 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, 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, or using the version that comes bundled with
deal.II. It can be disabled explicitly by using the
-DDEAL_II_WITH_UMFPACK=OFF
argument. It will also be disabled if no version
installed on the system can be found, and if the
version that comes bundled with deal.II cannot be
compiled, for example because no version of LAPACK
can be found. 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.
The Visualization Toolkit (VTK) is an open-source,
freely available software system for 3D computer graphics, modeling, image processing, volume rendering,
scientific visualization, and 2D plotting.
It supports a wide variety of visualization algorithms and advanced modeling techniques,
and it takes advantage of both threaded and distributed memory parallel processing for speed and scalability,
respectively.
In order to use VTK, add
-DVTK_DIR=/path/to/vtk to the deal.II CMake call.
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.
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.