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 C++ Standard compliant.
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.
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:
mkdir build cd build cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/dir ../deal.II make install make test
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.
Note:
/path/to/install/dir is 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 sure the installation directory is not the same
as the location where you unpacked deal.II/.
make
-jN in the last step, where N is the
number of simultaneous build processes you want make
to use at any given time. Allowing make to use
more simultaneous build processes (assuming you have that many
processor cores) will greatly lower the build time.
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.
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
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
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.
Upon calling make and make install, this will
install both this readme, other installation instructions, as well as the
manual that documents
all functions and classes as well as
the tutorial
of well-documented example programs (the "steps").
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.
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 off by passing the -DDEAL_II_WITH_THREADS=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.
64bit indices: By default, deal.II use unsigned int (32bit)
indices for degrees of freedom, using
the types::global_dof_index type. This limits the number of
unknowns to approximately four
billions. If larger problem must be solved, pass the
-DDEAL_II_WITH_64BIT_INDICES=ON argument to
cmake. You will not be able to solve problems of this size on
a single machine, but only when using clusters of computers and linear
algebra packages PETSc or Trilinos.
To use this option with PETSc, PETSc must be compiled
with the option --with-64-bit-indices.
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. 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.
ARPACK is a library for computing large
scale eigenvalue problems.
ARPACK
should be readily packaged by most Linux distributions.
(Don't forget to install a development version of the library).
To use a self compiled version, specify
-DARPACK_DIR=/path/to/arpack on the command line.
For a detailed description on how to compile ARPACK and linking with deal.II, see
this page.
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.
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. (Don't forget
to install a development version of the library).
To use a self compiled version, specify
-DGSL_DIR=/path/to/gsl on the command line.
The HDF5 library
provides graphical output capabilities in HDF5/XDMF
format.
HDF5 should be
readily packaged by most Linux distributions. (Don't forget
to install a development version of the library).
To use a self compiled version, specify
-DHDF5_DIR=/path/to/hdf5 on the command line.
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, specify
-DMETIS_DIR=/path/to/metis on the command line.
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.
GridIn class.
NetCDF should be readily packaged by most
Linux distributions. (Don't forget to install a development
version of the library). To use a self compiled version, pass
-DNETCDF_DIR=/path/to/netcdf to cmake.
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. (Don't forget to install a
development version of the library). 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.
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.
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 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 distributions courtesy of its author, Timothy A. Davis.
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.
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: