Amandus is a simple experimentation suite built on the dealii library. It basically allows the implementation of a new equation by just providing local integrators for residuals and matrices. In addition, it has a lot of example applications. You can find more information in the documentation generated with doxygen.

Structure of Amandus

Amandus consists of two parts: first, there is a framework for implementing finite element discretizations based on the deal.II finite element library. This framework is established in the class templates AmandusApplication and AmandusUMFPACK, as well as a few files with driver functions like apps.h. The application classes contain all functions for building matrices, computing right hand sides and residuals, or writing results in various output formats. They also contain all the data needed for this except the data vectors describing solutions and residuals. These are set up in the driver functions, since they differ between different numerical algorithms like linear solvers, Newton-like schemes and time stepping methods.

The second part of Amandus is a long list of subdirectories with specific applications. These contain typically several header files with local integrators and .cc files which can be compiled to obtain an executable program. This file structure mirrors the structure of code written in Amandus. The application classes of Amandus provide the technical intermediate layer implementing a generic finite element program. What is left to the user is:

  1. Writing local integrators, which describe the action of a differential operator in weak form on cell or face level. These are inherited from AmandusIntegrator and provide functions to integrate on cells as well as boundary and interior faces. These objects incorporate the 'physics' of a problem.
  2. Writing a file which contains a main() function and sets up the environment like creating a mesh, choosing the right drivers and choosing the numerical method for solving the problem.

We recommend looking at the subdirectories laplace or stokes to get a first idea of this structure.

Installing, using, and improving Amandus

Getting started


Amandus is updated along with the development version of deal.II. Thus, first make sure to obtain a recent clone of it and build it with Arpack and UMFPACK enabled. If your system has those libraries installed, it should be as simple as

git clone dealii_src
mkdir dealii_build
cd dealii_build
make -j <number_of_cores>

Notice that neither Arpack nor UMFPACK are required to build amandus, but nevertheless UMFPACK is very useful and used by many examples of Amandus and Arpack is required for the eigenvalue examples. The deal.II website provides more information about installing Arpack.

Downloading Amandus

There are two ways of downloading Amandus: you can simply clone the Git repository on

mkdir amandus
cd amandus
git clone source

If you just want to try it, or if you just want to compute some results with minimal changes, this may be fine. But you may also want to start bigger projects at some point, implement new equations, and even help us improving Amandus. To this end, you will want to use Git to store your changes into a repository. As long as you do not plan to give back, you can upload the Amandus Git repository wherever you like. But if you consider joining our community and giving back, it is recommended, that you

  1. create your own account on
  2. fork Amandus by going to the page ( and cllicking the 'fork' button and
  3. clone it to your computer using the command
mkdir amandus
cd amandus
git clone source
cd source
git remote add upstream

Whether you opted for the first or the second option, we will provide you with improvements, since Amandus is continuously being developed. Therefore, it is important, that you perform your own developments on a branch, which you create by

cd amandus/source
git checkout -b my_branch_name

If you work on different projects, it is not a bad idea to create a branch for each of those. At least, keep your commits separated.

Update often and keep your branches up to date!

cd amandus/source
git remote update

If you see any development on upstream/master, update your fork and your branches:

git checkout master
git rebase upstream/master
git push
git checkout my_branch
git rebase master
git push -f

The last command changes history in your branch repository. Therefore, there is some danger involved here and you always want to make sure that all you clones are synchronized before doing this. Otherwise, work may get lost.

Preparing Amandus

Amandus uses cmake for configuration. It supports in and out of source builds. In-source builds are not recommended if you plan on updating or developing. Thus, a typical setup runs like this

cd amandus
mkdir build
cd build
cmake -DDEAL_II_DIR=</path/to/dealii> ../source

where <path/to/dealii> is the dealii_build directory from the previous step. There are two common workflows for using Amandus. The first one starts from one of the examples included with Amandus and gets you started quickly, the other one uses Amandus as a library for more complex projects where it might be preferable to keep the project's code seperated from Amandus' code.

Included Examples

After the steps of the previous section, your amandus_build directory will contain different folders with names of specific problems (e.g. laplace, maxwell, allen_cahn, etc...). If you are interested in one of those examples you can cd into its folder and call make to build it. Typically, this will create multiple executables as well as parameter files (ending with .prm) that are executed as ./example_name example_name.prm. If one of the examples seems to be a good starting point for your own model you can just go ahead and adapt the code in the amandus_src directory to your needs and see the results of your changes by another call to make in the example's build directory (i.e. amandus_build/example).

Using Amandus as a library

If you want to use Amandus as an external dependency for your own code, you would call make in the amandus_build directory to build the library. Optionally you can install it from the build directory with

cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/amandus/to .
make install

In order to use Amandus for your own project you can use a setup similiar to the example in template_cmake directory which would be compiled as

cmake -DAMANDUS_DIR=/path/to/amandus/build/or/install /path/to/your/project/source

Buildung a project for Eclipse with cmake

After building and installing go your project folder in the build directory (e.g. /path/to/build/allen_cahn/) and use:

cmake -"GEclipse CDT4 - Unix Makefiles" -DDEAL_II_DIR=/path/to/installed/dealii /path/to/amandus/source/project/.

Note the "." at the end. Note the spelling Eclipse flag. That command creates a .project file in the build folder that you can import into Eclipse via: "File">"Import">"Existing Projects Into Workspace">Select the project folder in the build directory > "Finish" Then you might have to add the path to the deal.II and amandus source, such that Eclipse finds everything: RKlick the project on the left side>"Properties">"C/C++ Include Path ...">"Add Folder/File" 1) /.../deal.ii/include 2) /.../amandus After adding these it might be necessary to rerun the Indexer: RKlick the project on the left side>"Index">"Rebuild

If you want to compile and run in Eclipse then you can set up everything as usual. See deal.II wiki, section Eclipse.

Note: soon future change

Currently, Amandus uses the builtin dealii::Vector and dealii::SparseMatrix objects. These will be replaced by templates soon, such that parallelization and imported solvers will be possible.

Amandus is published under the MIT License.

When you commit a pull request to the amandus repository, you publish your code together with the remaining parts of amandus under this license. By submitting such a pull request, you certify that you or the copyright owner agree to publish under this license.