Ctrl+K
CIG Logo

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:

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

  2. Create a feature branch: If you are familiar with the version control system git that 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 Contributing to ASPECT). 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.

  3. 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:

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 dealii/dealii contain a section on how to debug deal.II programs.