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.
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.
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.
mesh_converter: If you wish to compile and install the
mesh_converter tool discussed in the documentation
of the GridIn class, specify
-DDEAL_II_COMPONENT_MESH_CONVERTER=ON. (This is in fact
the default.)
parameter_gui: If you wish to compile and install the
parameter_gui tool discussed in the documentation
of the ParameterHandler class, specify
-DDEAL_II_COMPONENT_PARAMETER_GUI=ON. Beware of the
fact that parameter_gui needs development packages for Qt.
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, PESTc must be compiled
with the option --with-64-bit-indices. To use this option
with Trilinos, Trilinos 11.2 or later is needed (there is a bug in
Trilinos 11.0 that prevents the use of 64bit 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.
FunctionParser
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.
The function parser library has its own license; if you want to use
it with deal.II, please read it and make sure that you agree with it.
You can find it
here. We
include FunctionParser in the deal.II distributions courtesy of its author,
Juha Nieminen.
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.
MUMPS
(MUltifrontal Massively Parallel sparse direct Solver)
is a sparse direct solver that can factorize matrices within or
across nodes of a cluster.
MUMPS
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, provide the
-DMUMPS_DIR=/path/to/mumps argument to cmake.
For a detailed description on how to compile MUMPS (and
some dependencies) and linking with deal.II, see
this page.
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 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.
UMFPACK 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 UMFPACK here. 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.
Some information beyond what is covered in the documentation of the library may be found on the deal.II homepage, or in the Frequently Asked Questions section. If you don't find what you're looking for, feel free to ask on our mailing list.
We are interested in any feedback, whether positive or negative, in order to determine the directions of future work on the library. We are also very much interested in incorporating any work and bug fixes by third parties into the library. Of course, you will be credited for this on the authors page.
Our institutes are evaluated at regular intervals. Consequently, we are interested in documenting the use of the programs and libraries we create. To this end, we collect publications with results obtained using deal.II. Please let us know if you have publications that we can add to this page.
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: