From 2df9fc5743aec186831f3aed42d8b809b0b9637e Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 8 Oct 2024 21:18:17 -0600 Subject: [PATCH 1/2] Update the documentation of plugins (part 1). --- .../extending/plugin-types/geometry-models.md | 62 +++--------------- .../extending/plugin-types/gravity-models.md | 35 +---------- .../extending/plugin-types/heating-models.md | 63 +++---------------- .../plugin-types/initial-conditions.md | 57 ++++++----------- 4 files changed, 34 insertions(+), 183 deletions(-) diff --git a/doc/sphinx/user/extending/plugin-types/geometry-models.md b/doc/sphinx/user/extending/plugin-types/geometry-models.md index cd08953772b..4e40be85968 100644 --- a/doc/sphinx/user/extending/plugin-types/geometry-models.md +++ b/doc/sphinx/user/extending/plugin-types/geometry-models.md @@ -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. @@ -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 - class aspect::GeometryModel::Interface - { - public: - virtual - void - create_coarse_mesh (parallel::distributed::Triangulation &coarse_grid) const = 0; - - virtual - double - length_scale () const = 0; - - virtual - double depth(const Point &position) const = 0; - - virtual - Point representative_point(const double depth) const = 0; - - virtual - double maximal_depth() const = 0; - - virtual - std::set - get_used_boundary_indicators () const = 0; - - virtual - std::map - 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 @@ -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::active_cell_iterator -> cell = triangulation.begin_active(); -> cell != triangulation.end(); -> ++cell) +> for (auto &cell : triangulation.active_cell_iterators()) > for (unsigned int f=0; f::faces_per_cell; ++f) > if (cell->face(f)->at_boundary()) > if (cell->face(f)->center(true)[0] == -1) @@ -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 + #include template void @@ -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. ::: diff --git a/doc/sphinx/user/extending/plugin-types/gravity-models.md b/doc/sphinx/user/extending/plugin-types/gravity-models.md index ba67943b275..1e3328bca8e 100644 --- a/doc/sphinx/user/extending/plugin-types/gravity-models.md +++ b/doc/sphinx/user/extending/plugin-types/gravity-models.md @@ -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 - class aspect::GravityModel::Interface - { - public: - virtual - Tensor<1,dim> - gravity_vector (const Point &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. diff --git a/doc/sphinx/user/extending/plugin-types/heating-models.md b/doc/sphinx/user/extending/plugin-types/heating-models.md index fce8292c93f..1535027e0c1 100644 --- a/doc/sphinx/user/extending/plugin-types/heating-models.md +++ b/doc/sphinx/user/extending/plugin-types/heating-models.md @@ -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 - class aspect::HeatingModel::Interface - { - public: - // compute heating terms used in the energy equation - virtual - void - evaluate (const MaterialModel::MaterialModelInputs &material_model_inputs, - const MaterialModel::MaterialModelOutputs &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 &) 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 heating_source_terms; - std::vector lhs_latent_heat_terms; - - // optional: - std::vector 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 @@ -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 diff --git a/doc/sphinx/user/extending/plugin-types/initial-conditions.md b/doc/sphinx/user/extending/plugin-types/initial-conditions.md index 8b1ada546f1..a79eff2842a 100644 --- a/doc/sphinx/user/extending/plugin-types/initial-conditions.md +++ b/doc/sphinx/user/extending/plugin-types/initial-conditions.md @@ -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`–{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 - class aspect::InitialConditions::Interface - { - public: - void - initialize (const GeometryModel::Interface &geometry_model, - const BoundaryTemperature::Interface &boundary_temperature, - const AdiabaticConditions &adiabatic_conditions); - - virtual - double - initial_temperature (const Point &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). From 879c4609f7c2056ba1e5e37d209070af2facdb05 Mon Sep 17 00:00:00 2001 From: Rene Gassmoeller Date: Wed, 9 Oct 2024 02:53:10 -0700 Subject: [PATCH 2/2] Fix typo --- doc/sphinx/user/extending/plugin-types/heating-models.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/user/extending/plugin-types/heating-models.md b/doc/sphinx/user/extending/plugin-types/heating-models.md index 1535027e0c1..4f3513dee60 100644 --- a/doc/sphinx/user/extending/plugin-types/heating-models.md +++ b/doc/sphinx/user/extending/plugin-types/heating-models.md @@ -46,7 +46,7 @@ any of these arguments. 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. SOme of the +class documentation. Some of the functions listed have a default implementation, as discussed on the documentation page just mentioned.