Skip to content

Commit

Permalink
Merge pull request #6061 from bangerth/update-plugin-docs
Browse files Browse the repository at this point in the history
Update the documentation of plugins (part 1).
  • Loading branch information
gassmoeller authored Oct 9, 2024
2 parents 0a579e6 + 879c460 commit f168159
Show file tree
Hide file tree
Showing 4 changed files with 34 additions and 183 deletions.
62 changes: 7 additions & 55 deletions doc/sphinx/user/extending/plugin-types/geometry-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,13 @@ boundary with different *boundary indicators* for which one can then, in the
input file, select whether these boundaries should be Dirichlet-type (fixed
temperature) or Neumann-type (no heat flux) boundaries for the temperature,
and what kind of velocity conditions should hold there. In
deal.II, a boundary indicator is a number of type
deal.II, a boundary indicator is a number of (integer) type
`types::boundary_id`, but since boundaries are hard to remember and get right
in input files, geometry models also have a function that provide a map from
symbolic names that can be used to describe pieces of the boundary to the
corresponding boundary indicators. For example, the simple `box` geometry
model in 2d provides the map
`{"left"\rightarrow0, "right"\rightarrow1, "bottom"\rightarrow2,"top"\rightarrow3}`,
`{"left" -> 0, "right" -> 1, "bottom" -> 2,"top" -> 3}`,
and we have consistently used these symbolic names in the input files used in
this manual.

Expand All @@ -29,55 +29,10 @@ class and use the
implementation of the new class should be in namespace
`aspect::GeometryModel`.

Specifically, your new class needs to implement the following basic interface:

```{code-block} c++
template <int dim>
class aspect::GeometryModel::Interface
{
public:
virtual
void
create_coarse_mesh (parallel::distributed::Triangulation<dim> &coarse_grid) const = 0;
virtual
double
length_scale () const = 0;
virtual
double depth(const Point<dim> &position) const = 0;
virtual
Point<dim> representative_point(const double depth) const = 0;
virtual
double maximal_depth() const = 0;
virtual
std::set<types::boundary_id_t>
get_used_boundary_indicators () const = 0;
virtual
std::map<std::string,types::boundary_id>
get_symbolic_boundary_names_map () const;
static
void
declare_parameters (ParameterHandler &prm);
virtual
void
parse_parameters (ParameterHandler &prm);
};
```

The kind of information these functions need to provide is extensively
The functions you need to overload are extensively
discussed in the documentation of this interface class at
[aspect::GeometryModel::Interface](https://aspect.geodynamics.org/doc/doxygen/namespaceaspect_1_1GeometryModel.html).
The purpose of the last two functions
has been discussed in the general overview of plugins above.

The `create_coarse_mesh` function does not only create the actual mesh (i.e.,
Note that the `create_coarse_mesh()` function you need to provide does not only create the actual mesh (i.e.,
the locations of the vertices of the coarse mesh and how they connect to
cells) but it must also set the boundary indicators for all parts of the
boundary of the mesh. The deal.II glossary
Expand All @@ -100,10 +55,7 @@ describes the purpose of boundary indicators as follows:
> 42 for all faces located at $x=-1$:
>
> ```{code-block} c++
> for (typename Triangulation<dim>::active_cell_iterator
> cell = triangulation.begin_active();
> cell != triangulation.end();
> ++cell)
> for (auto &cell : triangulation.active_cell_iterators())
> for (unsigned int f=0; f<GeometryInfo<dim>::faces_per_cell; ++f)
> if (cell->face(f)->at_boundary())
> if (cell->face(f)->center(true)[0] == -1)
Expand Down Expand Up @@ -202,7 +154,7 @@ been declared as a (non-static, but possibly private) member function of the
`MyGeometry` class, then the following will work:

```{code-block} c++
#include <functional>
#include <functional>
template <int dim>
void
Expand Down Expand Up @@ -236,7 +188,7 @@ work on. Note that because the `create_coarse_mesh` function is declared as
declared `const`.

:::{note}
For reasons that have to do with the way the `parallel::distributed::Triangulation` is
For reasons that have to do with the way the `parallel::distributed::Triangulation` class is
implemented, functions that have been attached to the post-refinement signal of the triangulation
are called more than once, sometimes several times, every time the triangulation is actually refined.
:::
35 changes: 2 additions & 33 deletions doc/sphinx/user/extending/plugin-types/gravity-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,37 +7,6 @@ class and use the `ASPECT_REGISTER_GRAVITY_MODEL` macro to register your new cla
The implementation of the new class should be in namespace
`aspect::GravityModel`.

Specifically, your new class needs to implement the following basic interface:

```{code-block} c++
template <int dim>
class aspect::GravityModel::Interface
{
public:
virtual
Tensor<1,dim>
gravity_vector (const Point<dim> &position) const = 0;
virtual
void
update ();
static
void
declare_parameters (ParameterHandler &prm);
virtual
void
parse_parameters (ParameterHandler &prm);
};
```

The kind of information these functions need to provide is discussed in the
documentation of this interface class at
The functions you need to overload are extensively
discussed in the documentation of this interface class at
[aspect::GravityModel::Interface](https://aspect.geodynamics.org/doc/doxygen/namespaceaspect_1_1GravityModel.html).
The first needs to return a gravity
vector at a given position, whereas the second is called at the beginning of
each time step, for example to allow a model to update itself based on the
current time or the solution of the previous time step. The purpose of the
last two functions has been discussed in the general overview of plugins
above.
63 changes: 7 additions & 56 deletions doc/sphinx/user/extending/plugin-types/heating-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,64 +21,15 @@ To implement a new heating model, you need to overload the
class and use the `ASPECT_REGISTER_HEATING_MODEL` macro to register your new class. The
implementation of the new class should be in namespace `aspect::HeatingModel`.

Specifically, your new class needs to implement the following basic interface:

```{code-block} c++
template <int dim>
class aspect::HeatingModel::Interface
{
public:
// compute heating terms used in the energy equation
virtual
void
evaluate (const MaterialModel::MaterialModelInputs<dim> &material_model_inputs,
const MaterialModel::MaterialModelOutputs<dim> &material_model_outputs,
HeatingModel::HeatingModelOutputs &heating_model_outputs) const;
// All the following functions are optional:
virtual
void
initialize ();
virtual
void
update ();
// Functions used in dealing with run-time parameters
static
void
declare_parameters (ParameterHandler &prm);
virtual
void
parse_parameters (ParameterHandler &prm);
// Allow the heating model to attach additional material model outputs in case it needs
// them to compute the heating terms
virtual
void
create_additional_material_model_outputs(MaterialModel::MaterialModelOutputs<dim> &) const;
};
```

The functions you need to overload are extensively
discussed in the documentation of this interface class at
[aspect::HeatingModel::Interface](https://aspect.geodynamics.org/doc/doxygen/namespaceaspect_1_1HeatingModel.html).
The main properties of the material are computed in the function `evaluate()`
that takes references to `MaterialModelInputs` and `MaterialModelOutputs`
objects and is supposed to fill the `HeatingModelOutputs` structure. As in the
material model, this function is handling lookups at an arbitrary number of
positions, so for each heating term (for example the heating source terms), a
`std::vector` is returned. The following members of `HeatingModelOutputs` need
to be filled:

```{code-block} c++
struct HeatingModelOutputs
{
std::vector<double> heating_source_terms;
std::vector<double> lhs_latent_heat_terms;
// optional:
std::vector<double> rates_of_temperature_change;
}
```
`std::vector` is returned.

Heating source terms are terms on the right-hand side of the equations, such
as the adiabatic heating $\alpha T \left( \mathbf u \cdot \nabla p \right)$ in
Expand All @@ -92,11 +43,11 @@ of these terms can depend on any of the material model inputs or outputs.
Implementations of `evaluate()` may of course choose to ignore dependencies on
any of these arguments.

The remaining functions are used in postprocessing as well as handling
The remaining functions that need to be implemented are used in postprocessing as well as handling
run-time parameters. The exact meaning of these member functions is documented
in the [aspect::HeatingModel::Interface](https://aspect.geodynamics.org/doc/doxygen/namespaceaspect_1_1HeatingModel.html)
class documentation. Note that some of the
functions listed above have a default implementation, as discussed on the
class documentation. Some of the
functions listed have a default implementation, as discussed on the
documentation page just mentioned.

Just like for material models, the functions `initialize()` and `update()` can
Expand Down
57 changes: 18 additions & 39 deletions doc/sphinx/user/extending/plugin-types/initial-conditions.md
Original file line number Diff line number Diff line change
@@ -1,47 +1,26 @@
# Initial conditions
# Initial conditions for temperature and composition

The initial conditions model is responsible for describing the initial
temperature distribution throughout the domain. It essentially has to provide
a function that for each point can return the initial temperature. Note that
The initial temperature conditions plugins are responsible for describing the initial
temperature distribution throughout the domain. Corresponding classes describe the
initial values for compositional fields.
Both in essence only have to provide
a function that for each point can return the initial temperature or composition. (Note that
the model {math:numref}`eq:stokes-1`&ndash;{math:numref}`eq:temperature` does not require
initial values for the pressure or velocity. However, if coefficients are
initial values for the pressure or velocity, and so there are no corresponding
plugins for these variables. However, if coefficients are
nonlinear, one can significantly reduce the number of initial nonlinear
iterations if a good guess for them is available; consequently,
ASPECT initializes the pressure with the
adiabatically computed hydrostatic pressure, and a zero velocity. Neither of
these two has to be provided by the objects considered in this section.
adiabatically computed hydrostatic pressure, and a zero velocity.)

To implement a new initial conditions model, you need to overload the
`aspect::InitialConditions::Interface` class and use the
`ASPECT_REGISTER_INITIAL_CONDITIONS` macro to register your new class. The
To implement a new initial temperature model, you need to overload the
`aspect::InitialTemperature::Interface` class and use the
`ASPECT_REGISTER_INITIAL_TEMPERATURE_MODEL` macro to register your new class. The
implementation of the new class should be in namespace
`aspect::InitialConditions`.
`aspect::InitialTemperature`. For initial compositional values, the class and
macro names have to be adjusted correspondingly.

Specifically, your new class needs to implement the following basic interface:

```{code-block} c++
template <int dim>
class aspect::InitialConditions::Interface
{
public:
void
initialize (const GeometryModel::Interface<dim> &geometry_model,
const BoundaryTemperature::Interface<dim> &boundary_temperature,
const AdiabaticConditions<dim> &adiabatic_conditions);
virtual
double
initial_temperature (const Point<dim> &position) const = 0;
static
void
declare_parameters (ParameterHandler &prm);
virtual
void
parse_parameters (ParameterHandler &prm);
};
```

The meaning of the first class should be clear. The purpose of the last two
functions has been discussed in the general overview of plugins above.
The functions you need to overload are extensively
discussed in the documentation of this interface class at
[aspect::InitialTemperature::Interface](https://aspect.geodynamics.org/doc/doxygen/namespaceaspect_1_1InitialTemperature.html) and
[aspect::InitialComposition::Interface](https://aspect.geodynamics.org/doc/doxygen/namespaceaspect_1_1InitialComposition.html).

0 comments on commit f168159

Please sign in to comment.