Extending and contributing to ASPECT
Extending and contributing to ASPECT#
After you have familiarized yourself with ASPECT using the examples of Cookbooks you will invariably want to set up your own models. During this process you might experience that not all of your ideas are already possible with existing functionality, and you will need to make changes to the source code.
ASPECT is designed to be an extensible code. In particular, it uses a plugin architecture and a set of signals through which it is relatively easy to replace or extend certain components of the program. Examples of things that are simple to extend are the material description, the model geometry, the gravity field, the initial conditions, the boundary conditions, the functions that postprocess the solution, and the behavior of the adaptive mesh refinement. This list may also have grown since this section was written. 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 Extending the basic solver.
There are several ways to add new functionality in plugins, and we want to highlight advantages and disadvantages of each of them:
Modify existing files: The simplest way to start modifying ASPECT is to modify one of the existing source files and then recompile the program as described in Compiling ASPECT and generating documentation. This process does not require any additional setup, and is therefore ideal for learning how to make simple modifications. However, it comes with several severe disadvantages. If you modify files the history of your local copy of ASPECT diverges from the official development version. You will therefore run into conflicts if you want to update your version later, for example, because there are new features or bug fixes available in the development version. Also these modifications make your results less reproducible. If you used your results in a publication, you could no longer say which version of ASPECT was used to produce these results, because you modified it yourself. Therefore, we discourage this form of modification for productive use (it can still be helpful for teaching).
Create a feature branch: If you are familiar with the version control system
gitthat we use to organize the development of ASPECT (an excellent tutorial is available at: http://swcarpentry.github.io/git-novice/) you might think of creating a separate branch inside your ASPECT repository and making your changes in this branch. This way you keep the history of your local modifications separate from the changes made to the main version. You can also uniquely describe the ASPECT version you used for a set of models, and you can upload your branch to make your changes reproducible. This approach is also the ideal starting point if you intend to contribute your changes back, as it already is the first step of our guide to contributing back (see also How to contribute). However, for projects with functionality that is not intended to be merged into the main version (e.g. because it is too specific to be of general use), we have found that this approach is not ideal, as you will still run into conflicts when you want to update your ASPECT version, and you need to merge the main version into your branch, or rebase the branch every time you want to update. Thus, while ideal for contributing to ASPECT, we do not recommend this approach for keeping model-specific functionality around.
Create a shared library that contains your changes: The main benefit of the plugin architecture described in the paragraph above is that if you want to extend ASPECT for your own purposes, you can do this in a separate set of files that describe your situation, rather than by modifying the ASPECT source files themselves. This is advantageous, because (i) it makes it possible for you to update ASPECT itself to a newer version without losing the functionality you added (because you did not make any changes to the ASPECT files themselves), (ii) because it makes it possible to keep unrelated changes separate in your own set of files, in a place where they are simple to find, and (iii) because it makes it much easier for you to share your modifications and additions with others, you can for example include them as supplementary material in your publications. Of course you can (and should) also use version control on your separate set of files to keep track of which version of files was used for a given set of models. Two examples for keeping a separate shared library for model specific changes are discussed in Prescribed internal velocity constraints, and in Inner core convection. We will discuss the concept of plugins in The idea of plugins and the SimulatorAccess and Introspection classes, and how to write a plugin in How to write a plugin.
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://dealii.org/developer/doxygen/deal.II/Tutorial.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.colostate.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 <span 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 Bangerth et al. .
As described in Debug or optimized mode you should always compile and run ASPECT in debug mode when you are making changes to the source code, as it will capture the vast majority of bugs everyone invariably introduces in the 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 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.