Installation instructions and further information on deal.II

This document contains the following sections:

System requirements

At present, deal.II has been developed and tested on the following platforms:

Newer versions of the compilers listed above are also likely to work, as are other brands of Unix (for example Sun Solaris, FreeBSD, or Linux on chips like SPARC, PA-RISC, PowerPC, etc) using gcc as compiler, but we do not regularly test them. Furthermore, for the following list of systems, we have collected our experiences on separate pages:

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:

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.

Installation

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
    
in the top-level directory, which sets some paths and finds out what compiler you use. ./configure supports several flags which are discussed further down below.

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

Each library file will have a suffix that depends on the system. If static libraries were requested during configuration, then the suffix is .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:

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.

Configuration options

Changing the compiler or compiler flags

If 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>
    

Selecting optional behavior

You can give several flags to ./configure:

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.

Optional interfaces to other software packages

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):

TECPLOT
Autodetected if one of the variables $TECHOME, $TEC80HOME or $TEC90HOME points to a valid installation of the tecio library. If enabled, allows data output in TECPLOT format.
UMFPACK
Enabled by --with-umfpack. If no argument is given, use the version of UMFPACK that comes bundled with deal.II. If you want a different version of UMFPACK, provide the path to that version as an argument. Enabling UMFPACK adds the class SparseDirectUMFPACK to the library. The default is to not use UMFPACK.

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.

Petsc

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.

Slepc

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).

Trilinos

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.

Metis

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.

BLAS, LAPACK

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.

NetCDF
Autodetected if the NETCDF_DIR environment variable points to a valid installation of the NetCDF library. Can also be enabled by --with-netcdf=/path/to/netcdf which overrides the path in $NETCDF_DIR. If enabled, deal.II allows grid input in NetCDF format (GridIn::read_netcdf). If NetCDF was installed as part of /usr or /opt, instead of local directories in a home directory for example, you can use configure switches --with-netcdf-include, --with-netcdf-libs.
Harwell Subroutine Library (HSL)
It is possible to use some subroutines from the Harwell Subroutine Library (HSL) to make use of some sparse direct solvers. For a description of how to include these functions, see this page.
MUltifrontal Massively Parallel sparse direct Solver (MUMPS)
It is possible to make use some subroutines that make use of the MUltifrontal Massively Parallel sparse direct Solver (MUMPS). For a detailed description of how to compile MUMPS (and some dependencies) and linking with deal.II, see this page.
FunctionParser
There is a wrapper for the FunctionParser library, which 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 FunctionParser here. We include FunctionParser in the deal.II distributions courtesy of its author, Juha Nieminen.

Problems, questions, mailing lists

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.

License

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:

Note that since our institutes are evaluated at regular intervals, we are interested in documenting the use of the programs and libraries we create. We are therefore interested in collecting publications with results obtained with the aid of these libraries and would therefore like to ask you to drop us a note about every such publication. Your publication will then be listed on the project homepage.

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.


The deal.II mailing list $Date: 2010-06-12 18:47:01 -0500 (Sat, 12 Jun 2010) $