This document contains the following sections:
At present, deal.II has been developed and tested on the following platforms:
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.
In order to compile and use the deal.II libraries you need to have the following programs installed:
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.
In case you want to generate the documentation from the
header files, you need a copy of doxygen on your machine. Versions 1.4.6
and later are known to work. If you
have this program, you can generate all the documentation on
your local 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.
Doxygen also generates printable API documentation. It is located
in the directories doc/doxygen/LaTeX and
subdirectories. To generate printable versions, you need a latex
installation. However, the present size of this API information is
about 4000 pages, so you may not want to print it, and rather rely
on the online version. The more interesting part of the
documentation to print would probably be the example programs, but
we don't presently have a way to do that apart from printing it
directly from the browser or by using the html2ps
program.
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 format, so there are a number of excellent programs that can read VTK, such as Visit, ParaView, as well as many others. GMV and Open DX are freely available for most Unix platforms. 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. HiVision is available for free after registration.
In case you didn't find your favorite graphics format above it might be of interest that it is quite simple to add it to the list of supported ones (take a look at base/include/base/data_out_base.h and base/source/data_out_base.cc to see how output formats are implemented), as only a simple intermediate format needs to be converted into a graphics format, without references to cells, nodes, types of finite elements, and the like. Since your preferred output format is likely to be similar to one for which we already have a backend, adaptation is usually simple. In case you write such a function, we would be happy to integrate it into the library.
The whole library usually comes as a .tar.gz file, that is a tarred file archive which is compressed with gzip. After unpacking it with gunzip and tar (or tar xzf if you use GNU tar), you will find several subdirectories. First run the script
./configure
The most important result of ./configure is the
creation of the files common/Make.global_options and
base/include/base/config.h. The first
file contains compiler options, paths, etc which you may want to
use in the Makefiles
of your own projects. It is definitely a good
idea to include it into your Makefile, to allow using the same
flags for compilation between library files and the files of your
project, and to access the paths of the library files. To find
out about the supported flags, take a look at the file. Also,
information about Makefiles can be found in the section on
development.
The second generated file contains a number of preprocessor definitions, that are mostly used to indicate the features and bugs of the compiler in use.
After configuring, type `make', to obtain the following help (this output may change slightly over time, just try it):
========================================================================
= Global Makefile for the deal.II libraries =
========================================================================
= =
= The following targets exist: =
= baseg lacg : debug libraries "base" and "lac" =
= base lac : debug and optimized libraries "base" and "lac" =
= 1dg 2dg 3dg: deal.II debug version for specified dimension =
= 1d 2d 3d : deal.II debug and optimized for specified dimension =
= =
= contrib : additional libraries in contrib, if there are any =
= =
= all : base, lac, 1d, 2d and 3d, contrib =
= debug : baseg, lacg, 1dg, 2dg and 3dg, contrib =
= optimized : base, lac, 1d, 2d, and 3d optimized libraries only =
= =
= 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, libraries, etc in subdirs =
========================================================================
To execute one of the commands, type for example `make all'. Building all libraries takes somewhere between 10 minutes and 1 hour, depending on your machine and requires about 1.1 GB of free disk space. If you have a multi-processor machine, you can call `make -j4 target-name' to let `make' call multiple instances of the compiler (in this case four). This speeds up compilation by about the factor given after `-j', at least if you have as many processors.
After `make' has finished, you will have two sets of libraries. The first consists of the files
lib/libbase: The library containing the
code of the classes in the /base directory. These
are mostly helper classes (such as output of various data in
different data formats), and classes of general numerical
interest (functions, tensors, etc.).
lib/liblac: lac is the
acronym for Linear Algebra Classes. This
library contains classes representing vectors, matrices, sparse
matrices, linear solvers, and the like.
lib/libdeal_II_2d: This is the
library containing all the classes representing finite element
methods, grid handling, different finite elements,
etc. There will also be libraries
for one and three spatial dimensions.
.a. For shared
libraries, it is .so (for most Unix-like and Linux
systems), .dylib (for Mac OS X), or .dll
(for Cygwin/Windows).
For each library, there will also be another one with an
infix .g between library name and suffix. The
difference between the two sets of libraries is the following:
The .g versions contain debugging
information (the infix .g was historically chosen
because gcc uses the flag -g to request
debugging information).
In addition, the .g libraries
contain a large number of assertions (presently
about 5000) checking the validity of parameters to functions and
internal states. 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.
You will want to link your programs against the
.g.a versions of the libraries while developing
your programs.
The libraries without the .g infix do not contain
neither debugging information nor assertions. They are therefore much
smaller and your program will run significantly faster (the
performance penalty of the .g libraries is
between a factor of two and ten, depending on which parts of
the libraries you use). Furthermore, these libraries are
compiled with optimization options of the compiler.
You will want to link your programs against these libraries when they run stable and are used in production mode.
Apart from the libraries, you should 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 can access all documentation 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 uses a wrong 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 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 no more set later (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>
--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.
--with-cpu=...: Enable specific optimization
flags for a particular processor. Programs compiled with these options
might not execute on an other system, but will be faster by up to
30 percent on the 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.
Optimizations currently only work in conjunction with gcc. Without the
option --with-cpu=xxx, no cpu specific optimization is applied.
Furthermore, CPU specific optimization is switched on only for the compilation
of the optimized library versions.
--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.
Please note that running ./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 with the new compiler being in the $PATH
environment variable.
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.
These supported software packages comprise (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.
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 anything there, feel free to ask if you have any problems with deal.II. If a question is of general interest, you may want to use our mailing list, which can be reached at dealii (at) dealii.org and of which previous mails are also archived online. Before writing to the list, you will have to subscribe to it.
You can subscribe to this list by writing email to list-server (at) dealii.org with the text (not in the subject!)
subscribe deal
The list server also understands the command help given
on a line by itself.
For specific problems, send email to either Wolfgang.Bangerth, Ralf.Hartmann, 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.
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 a copy of UMFPACK and one of FunctionParser, courtesy of their authors. UMFPACK and FunctionParser are covered by their own licenses; please refer to their webpages to read them.