6 Extending and contributing to ASPECT

ASPECT is designed to be an extensible code. In particular, it uses both a plugin architecture and a set of signals through which it is trivial to replace or extend certain components of the program. Examples of things that are simple to extend are:

• the material description,
• the geometry,
• the gravity description,
• the initial conditions,
• the boundary conditions,
• the functions that postprocess the solution, i.e., that can compute derived quantities such as heat fluxes over part of the boundary, mean velocities, etc.,
• the functions that generate derived quantities that can be put into graphical output files for visualization such as fields that depict the strength of the friction heating term, spatially dependent actual viscosities, and so on,
• the computation of refinement indicators,
• the determination of how long a computation should run.

This list may also have grown since this section was written. We will discuss the way this is achieved in Sections 6.1 and 6.3. Changing the core functionality, i.e., the basic equations (1)–(3), and how they are solved is arguably more involved. We will discuss this in Section 6.6.

Since ASPECT is written in C++ using the deal.II library, you will have to be proficient in C++. You will also likely have to familiarize yourself with this library for which there is an extensive amount of documentation:

• The manual at https://www.dealii.org/developer/doxygen/deal.II/index.html that describes in detail what every class, function and variable in deal.II does.
• A collection of modules at https://www.dealii.org/developer/doxygen/deal.II/modules.html that give an overview of whole groups of classes and functions and how they work together to achieve their goal.
• The deal.II tutorial at https://www.dealii.org/developer/doxygen/tutorial/index.html that provides a step-by-step introduction to the library using a sequence of several dozen programs that introduce gradually more complex topics. In particular, you will learn deal.II’s way of dimension independent programming that allows you to write the program once, test it in 2d, and run the exact same code in 3d without having to debug it a second time.
• The step-31 and step-32 tutorial programs at https://www.dealii.org/developer/doxygen/deal.II/step_31.html and https://www.dealii.org/developer/doxygen/deal.II/step_32.html from which ASPECT directly descends.
• An overview of many general approaches to numerical methods, but also a discussion of deal.II and tools we use in programming, debugging and visualizing data are given in Wolfgang Bangerth’s video lectures. These are linked from the deal.II website at https://www.dealii.org/ and directly available at http://www.math.tamu.edu/~bangerth/videos.html.
• The deal.II Frequently Asked Questions at https://github.com/dealii/dealii/wiki/Frequently-_Asked-_Questions that also have extensive sections on developing code with deal.II as well as on debugging. It also answers a number of questions we frequently get about the use of C++ in deal.II.
• Several other parts of the deal.II website at https://www.dealii.org/ also have information that may be relevant if you dive deeper into developing code. If you have questions, the mailing lists at https://www.dealii.org/mail.html are also of general help.
• A general overview of deal.II is also provided in the paper [BHK07].

As a general note, by default ASPECT utilizes a deal.II feature called debug mode, see also the introduction to this topic in Section 4.3. If you develop code, you will definitely want this feature to be on, as it will capture the vast majority of bugs you will invariably introduce in your code.

When you write new functionality and run the code for the first time, you will almost invariably first have to deal with a number of these assertions that point out problems in your code. While this may be annoying at first, remember that these are actual bugs in your code that have to be fixed anyway and that are much easier to find if the program aborts than if you have to go by their more indirect results such as wrong answers. The Frequently Asked Questions at https://github.com/dealii/dealii/wiki/Frequently-_Asked-_Questions contain a section on how to debug deal.II programs.

The downside of debug mode, as mentioned before, is that it makes the program much slower. Consequently, once you are confident that your program actually does what it is intended to do – but no earlier! –, you may want to switch to optimized mode that links ASPECT with a version of the deal.II libraries that uses compiler optimizations and that does not contain the assert statements discussed above. This switch can be facilitated by editing the top of the ASPECT Makefile and recompiling the program.

In addition to these general comments, ASPECT is itself extensively documented. You can find documentation on all classes, functions and namespaces starting from the doc/doxygen/index.html page.