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
AmandusUMFPACK, as well as a few files with driver functions like
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:
- Writing local integrators, which describe the action of a differential operator
in weak form on cell or face level. These are inherited from
AmandusIntegratorand provide functions to integrate on cells as well as boundary and interior faces. These objects incorporate the 'physics' of a problem.
- 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
stokes to get a first idea
of this structure.
Installing, using, and improving Amandus
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 https://github.com/dealii/dealii.git dealii_src mkdir dealii_build cd dealii_build cmake -DDEAL_II_WITH_ARPACK=ON -DDEAL_II_WITH_UMFPACK=ON ../dealii_src 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.
There are two ways of downloading Amandus: you can simply clone the Git repository on bitbucket.org:
mkdir amandus cd amandus git clone https://email@example.com/guidokanschat/amandus.git 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
- create your own account on bitbucket.org
- fork Amandus by going to the page (https://bitbucket.org/guidokanschat/amandus) and cllicking the 'fork' button and
- clone it to your computer using the command
mkdir amandus cd amandus git clone firstname.lastname@example.org:your_account_name/amandus.git source cd source git remote add upstream https://email@example.com/guidokanschat/amandus.git
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.
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
<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.
After the steps of the previous section, your
amandus_build directory will
contain different folders with names of specific problems (e.g.
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
.prm) that are executed as
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
the example's build directory (i.e.
Using Amandus as a library
If you want to use Amandus as an external dependency for your own code, you
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 make
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::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.