This document contains the following sections:
deal.II uses only very few features of an operating system. It should therefore be rather simple to port it to other systems, at least with the compilers stated above. If your system is not on this list, take a look at the page that describes porting the library to new systems.
A fairly complete C++ compiler. Various working compilers are listed above. We do not support gcc versions older than 3.2 any more at this time. Note that we are interested in writing portable C++, so if you find something that does not work with your compiler, we are likely to accept patches.
Perl: Any Perl 5.x version should work.
Make: We use GNU make, version 3.78 or later which also
has rather good support for parallel builds, so you may
want to consider this version if you have a multiprocessor
system. GNU make 3.77 had a serious flaw in the
$(wildcard ...) function which prevented us
from compiling some parts of the library (most of our
Makefiles use a workaround, though). Older GNU make
versions are likely to work, but since they are hardly
installed on systems today, we don't regularly test
this. Other make programs (i.e. non-GNU) will usually fail
to work and are not supported.
For debugging programs, we have found that the GNU debugger gdb is a valuable tool. Other options are DDD and kdbg, both of which have graphical user interfaces. Most integrated development environments like kdevelop or Eclipse have built in debuggers as well.
In case you want to generate the documentation locally on your
machine from the header deal.II files, you need a
copy of doxygen
on your machine. If not, you can still work with the library and
use the documentation provided on our homepage for reference. Note
that in order to generate inheritance graphs for classes, doxygen
can use the dot program, which is part of the GraphViz
package. If this program is not available, then doxygen attempts to
generate text-mode graphs; these are much less nice, though.
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).
gunzip deal.II-X.Y.Z.tar.gz
tar xf deal.II-X.Y.Z.tar
or, if you have GNU tar with
tar xzf deal.II-X.Y.Z.tar.gz
Unpacking will create a subdirectory deal.II with
the whole library wherever you do it. Since deal.II does not have
a make install which would copy the libraries to a final position,
this subdirectory is where the built library will reside.
cd deal.II
./configure
to set some paths and find out your system parameters. configure
supports several flags which are discussed
further down below.
./configure creates the
file deal.II/common/Make.global_options,
which remembers paths and configuration options. Please note that it is not
possible to move the library directory after configuration. Neither will
the library compile, nor will your application programs be able to use it.
You can
use deal.II/common/Make.global_options in the
Makefiles
of your own projects to set relevant paths and parameters correctly.
========================================================================
= Global Makefile for the deal.II libraries =
========================================================================
= =
= The following targets exist: =
= all : debug and optimized libraries =
= debug : the debug version of the deal.II library =
= optimized : the optimized version of the deal.II library =
= =
= contrib : additional libraries in contrib, if there are any =
= =
= online-doc : generate the documentation in HTML format =
= TODO : create a "TODO" file from the source files =
= TAGS : create a TAGS file from include and source files =
= =
= clean : removes all object files in subdirs =
= distclean : removes all object files, libraries, etc in subdirs =
========================================================================
To execute one of the commands, type for example make
all. Building all libraries takes somewhere between 4 minutes
and several hours, depending on the number of processors your machine
has, and requires about 2 GB of free disk space. If you have a
multi-processor machine, you can call make -j16 target-name
to let make call multiple instances of the compiler
(in this case sixteen). This speeds up compilation by about
the factor given after -j, at least if you have as many
processors.
The deal.II libraries come in two versions corresponding to their respective targets:
lib/libdeal_II.g: This is the
debug version of the library. It is compiled with compiler flags so
that the library contains information that can be used by debuggers. (The
infix .g was historically chosen because gcc uses the
flag -g to request debugging information).
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.
lib/libdeal_II: This is the
optimized version of the library. You will want to link with it
once you know that your program is working as expected. This
version of the library does not contain the safety checks any more
and is compiled with aggressive compiler optimizations. The
resulting executables are smaller and will run between 2 and 10
times faster than the debug executables.
.a. For shared
libraries, it is .so (for most Unix-like and Linux
systems), .dylib (for Mac OS X), or .dll
(for Cygwin/Windows).
Apart from the libraries, you can generate the full set of
documentation files, by typing make online-doc; this takes
some minutes but you will
have (almost) all the documentation locally on your computer. You
will then be able to access it through this page.
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.
configure to use a particular compiler, there are two
options: first, you can prepend your search path by the directory
of the desired compiler. Alternatively, if your full compiler paths are
mycc and myc++ (for example) for your C and C++ compilers,
respectively, type into your csh:
setenv CC mycc
setenv CXX myc++
./configure
or into your bash
export CC=mycc
export CXX=myc++
./configure
The paths to these compilers are stored in the
common/Make.global_options files, so the compilers
are always used when compiling the library even if the environment
variables are not set later on any more (for example if you are working
within another window, or have unset the variables for other
purposes).
If all you want to do is pass different compiler flags to the
compiler, set the standard environment variables CXXFLAGS,
CFLAGS, LDFLAGS before calling
./configure. For example, to produce
gprof output, do:
setenv CXXFLAGS -pg
setenv LDFLAGS -pg
./configure <configure-options>
The flags so set are used for both optimized and debug mode. If you want to
set flags for only one of these two cases, you should
set CXXFLAGSO or CXXFLAGSG, respectively.
--enable-shared: Compile the files of deal.II into
shared libraries, rather than statically linked
libraries. Enabling this option saves disk space, link time and
start-up time, so this is the default. Some systems
might not support shared libraries, in which case you should
call ./configure with the parameter
--disable-shared.
--enable-threads: This flag indicates that those
parts of the library that support this compute in parallel,
using multiple threads, making programs significantly faster on
machines with multiple cores or processors. The default is to
use multiple threads since most machines today have several
processor cores. If this is not desired,
use --disable-threads.
--enable-mpi: If given this
flag, ./configure chooses mpiCC
and mpicc as the C++ and C compilers, respectively,
unless the $CXX and $CC environment
variables have specifically been set to something else. If these
compilers exist and indeed support MPI, then this also switches
on support for MPI in the library.
--with-cpu=...: Enable specific optimization
flags for a particular processor. Programs compiled with these options
might not execute on another system, but may be faster on the
particular CPU selected.
For a complete list of supported values of this switch, you may
take a look at the file aclocal.m4 in the top-level
directory. However, the most commonly used value
is --with-cpu=native, indicating that the compiler
should determine the CPU we are running on by itself and
optimize for it.
--with-doxygen=...: Select the specified executable
of doxygen over the one automatically found by
./configure. May also be used if no
doxygen can be found automatically.
./configure stores the paths to some
programs, such as the compilers or the Perl interpreter. The
compiler which will be used when compiling the library (or your
own application) is therefore selected at the time of
configuration and independent of the setting of your $PATH
environment value at the time when you run make. If
you want to change the compiler used, you will therefore have
to re-run ./configure.
It is in general a good idea to run make clean
before re-configuring.
deal.II comes with built-in support for a number of external software packages. These packages are sometimes detected automatically, sometimes they must be enabled explicitly during configuration by adding the option --with-package. Supported software packages are (the following list contains trademarks belonging to their owners):
If you want to use an external installation of UMFPACK, but UMFPACK was
installed as
part of /usr or /opt, instead of local
directories in a home directory for example, you can use configure
switches --with-umfpack-include, --with-umfpack-libs.
Note that UMFPACK 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 the license of UMFPACK here. We include UMFPACK in the deal.II distributions courtesy of its author, Timothy A. Davis.
deal.II can interface to
the PETSc library. The simplest way to do so is to
set the PETSC_DIR and PETSC_ARCH
environment variables. More information and configuration
options can be found by issuing ./configure --help
at the command line, or, here.
deal.II can also interface to
the SLEPc library. The way to do it is to set
the SLEPC_DIR environment variable by
passing --with-slepc=/path/to/slepc
to deal.II's ./configure script.
The use of SLEPc is optional, however, for the interface with
SLEPc to work at all, deal.II's interface to
PETSc must also be configured correctly (see the notes above on
how to do this).
deal.II can also interface to Trilinos. The
simplest way to use these interfaces is to
pass --with-trilinos=/path/to/trilinos
to deal.II's ./configure script. More
configuration options can be found here.
In order to generate partitionings of triangulations, we have functions that call METIS library. METIS is a library that provides various methods to partition graphs, which we use to define which cell belongs to which part of a triangulation. The main point in using METIS is to generate partitions so that the interfaces between cell blocks are as small as possible. This data can, in turn, be used to distribute degrees of freedom onto different processors when using PETSc and/or SLEPc in parallel mode.
As with PETSc and SLEPc, the use of METIS is optional. If you
wish to use it, you can do so by having a METIS installation
around at the time of calling
./configure by either
setting the METIS_DIR environment
variable denoting the path to the METIS library, or using the
--with-metis flag. If METIS was installed as part
of /usr or /opt, instead of local directories
in a home directory for example, you can use configure
switches --with-metis-include, --with-metis-libs.
On some systems, when using shared libraries for deal.II, you may get
warnings of the kind libmetis.a(pmetis.o): relocation R_X86_64_32
against `a local symbol' can not be used when making a shared
object; recompile with -fPIC when linking. This can be
avoided by recompiling METIS with -fPIC as a compiler
flag.
METIS is not needed when using p4est to parallelize
programs, see below.
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 configure deal.II with p4est, you will
need to use the --with-path=/path/to/path
switch to the ./configure script.
If --with-blas=blasname and/or
--with-lapack=lapackname is given, provide wrappers
around some of the BLAS and LAPACK functions, and link with the
respective libraries. It will make sure that we link with the
required FORTRAN libraries. If no argument is given to
--with-blas, then a BLAS library
libblas.a or libblas.so is searched for
in the default locations of your system, and similarly for LAPACK.
If your BLAS or LAPACK libraries are not in the standard search
path of your linker, you have to tell the linker where to find them.
The path is not given as an argument to
--with-blas. Rather, you set the variable
LDFLAGS accordingly or make sure that the path is in
your LD_LIBRARY_PATH or similar. For details, please
look up the documentation of your linker. An example configuration
for Linux is:
./configure --with-blas=myblas LDFLAGS=-L/my/lib/
This example will search for a library
libmyblas.a or libmyblas.so in the
directory /my/lib and elsewhere in the system library
paths.
Some versions of BLAS and LAPACK need additional libraries
to be linked with. Such an example is the
automatically tuned
linear algebra software (ATLAS). The BLAS version of this
package also needs declarations from libatlas.a,
so it must be included. Using the standard library names of
atlas, the include for BLAS reads
./configure --with-blas='f77blas -latlas'
assuming that the library files libf77blas.a and
libatlas.a or the respective shared libraries
*.so are in libraries included in
LD_LIBRARY_PATH. LAPACK generated by ATLAS is
included in a similar fashion.
/usr or /opt, instead of local
directories in a home directory for example, you can use configure
switches --with-netcdf-include, --with-netcdf-libs.
Some information beyond what is covered in the documentation of the library may be found on the homepage of deal.II, 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.
For specific problems, send email to either Wolfgang.Bangerth, Guido.Kanschat, or simply authors at dealii.org.
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 our home 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.
We have placed deal.II under an Open Source license, which allows you to use the library free of charge. You are guaranteed full access to the source code and are encouraged to help in the further development of the library. Follow this link to read the full text of the license,
The basics of the license are in short:
deal.II can interface with a number of other packages that you have to install yourself. They are, of course, covered by their own licenses. In addition, deal.II comes with copies of UMFPACK and FunctionParser, courtesy of their authors. UMFPACK and FunctionParser are covered by their own licenses; please refer to their webpages to read them.