(cha:extending)=
# Extending and contributing to ASPECT
After you have familiarized yourself with
ASPECT using the examples of
{ref}`cha: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
{math:numref}`eq:stokes-1`–{math:numref}`eq:temperature`, and how they are solved is
arguably more involved. We will discuss this in {ref}`sec:extending: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
{ref}`sec:install:local-installation:compiling`. 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:
) 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 {ref}`sec:extending:contributing`). 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
{ref}`sec:cookbooks:prescribed_velocity`, and in
{ref}`sec:cookbooks:inner_core_convection`. We will discuss
the concept of plugins in {ref}`sec:extending:idea-of-plugins`, and how to write a plugin
in {ref}`sec:extending: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
that
describes in detail what every class, function and variable in
deal.II does.
- A collection of modules at
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
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
and
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 and
directly available at
.
- The deal.II Frequently Asked Questions at
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 also have information that may be relevant if
you dive deeper into developing code. If you have questions, the mailing
lists at are also of general help.
- A general overview of deal.II is also
provided in the paper {cite:t}`bangerth:etal:2007`.
As described in {ref}`sec:run-aspect:debug-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
contain a
section on how to debug deal.II programs.
:::{toctree}
---
maxdepth: 1
---
idea-of-plugins.md
write-a-plugin.md
write-a-cookbook/index.md
plugin-types/index.md
compatibility.md
signals.md
extending-solver.md
testing/index.md
contributing.md
future-plans.md
release-tasklist-link.md
:::