Commit e99c01ea authored by Lukas Riedel's avatar Lukas Riedel 🎧
Browse files

Revamp doxygen groups and files

* Add groups.dox file for every model and respective group
* Move docs of model base class into SimulationBase class
* Move docs of transport model into Transport group
parent 09026614
// These groups should gather information of code that belong to fairly similar
// categories. In them we aim to explain the code: why is done in that specific
// way, how carful someone has to be to modify it, specific name conventions, etc.
// These descriptions are not for regular users but for future developers (maybe
// the same developer in some months/years later).
// These groups should gather information strongly related portions of the code.
// In them we aim to explain to other developers:
// - The rationale of the design
// - How careful someone has to be when modifying it
// - Specific naming or other conventions upheld in the code
/**
/**
@defgroup Common Common
@{
......@@ -14,17 +14,6 @@
@defgroup Models Models
@defgroup RichardsModel Richards
@{
@ingroup Models
@todo document richards model
@}
@defgroup TransportModel Transport
@{
@ingroup Models
@}
@defgroup LocalOperators Local operators
@{
Local operators are in many senses the heart of dorie; in them, we transform
......@@ -55,4 +44,4 @@
local operator convention.
@}
**/
\ No newline at end of file
**/
......@@ -9,109 +9,6 @@
namespace Dune{
namespace Dorie{
/**
@addtogroup Models
@{
## Base class for simulations
### Stepping:
The method `step()` must be an abstract method that always has to be
implemented by the derived class. The step must succeed always, otherwise,
it should throw a `SimulationStepException`. It means that time adaptivity
must be done internally so that the time step succeeds.
### Writing data:
The method `step()` must be able to decide whether to write data or not.
(Say that in one case one wants that transport writes that every step and in
another case one wants that it writes at the end of the Richards step. The
first case can't be covered writing data in the `run()` method of the
coupled simulation.) Then, enum class called `OutputPolicy` must decide
whether to call the method `write_data()`. This policy can be set and be
extracted by the methods `set_policy(OutputPolicy)` and `output_policy()`
respectively.
The method `write_data()` should be in charge of writing the data.
In principle, this method should be only used following the `OutputPolicy`.
Usually called at the end of each step and at the beginning of the
simulation. Since the `step()` method is in charge of it, it is assumed that
this method writes the *current* state of the model (e.g. intermediate
results of the coupled simulation for the transport state).
### Adaptivity:
For the purpose of having a generic `run()` method in this class, the sketch
of the adaptivity must be provided here. First, adaptivity must be never
done inside the method `step()`. Additionally, if the model can perform
adaptivity, it must provide the method `mark_grid()`, otherwise, it must
throw a `NotImplemented` exception. For completion, there must be a method
called `adapt_grid()` that pack all the known degrees of freedom and, the
grid function spaces and perform the adaptivity.
Similar to the idea of `OutputPolicy` there must be an `AdaptivityPolicy`
set by the methods `set_policy(AdaptivityPolicy)` and `adaptivity_policy()`
respectively which will be set by default to `AdaptivityPolicy::None`.
Having this separation between marking the grid and adaptivity of solutions
leave coupled models to decide which model will mark the grid inside its
method of `mark_grid()` and still handle the adaptivity implementing
`adapt_grid()` separately.
### Time control:
A minimal interface is only providing `begin_time()`, `end_time()` and
`current_time()`.
In order to keep solution vectors minimal at the time of adaptivity, DORiE
expect the several models synchronized in time. Therefore, a good and still
minimal interface is only suggesting the timestep to the model via
`suggest_timestep(double dt)`. Such suggestion has to be taken into account
within the model, and the model must ensure that the timestep is done in
`step()` is never bigger than the suggested one so that coupled models can
achieve synchronization. Naturally, models have to ensure that
`begin_time()` \f$=\f$ `current_time()` at when they are constructed.
### Local Operator Setup:
Since adaptivity can modify the complete setup of the simulation, and since
the method `adapt_grid()` is not necessarily called by the model.
There is a need for the method `post_adapt_grid()` which is in charge of
setup everything again to the new grid. Same argument holds for
`pre_adapt_grid()`.
### Run:
With all the definitions given before, a general algorithm to run the
program can be given by following code:
```
virtual void run()
{
if (output_policy() != OutputPolicy::None)
write_data();
while( current_time() < end_time() )
{
step();
if (adaptivity_policy() != AdaptivityPolicy::None)
if ( current_time() < end_time() )
{
mark_grid();
pre_adapt_grid();
adapt_grid();
post_adapt_grid();
}
}
}
```
@}
*/
/*-------------------------------------------------------------------------*//**
* @brief Base class for simulations.
* @details This class is used to handle simulations with a common interface.
......@@ -281,7 +178,109 @@ private:
AdaptivityPolicy _adapt_policy;
};
/**
@{
@class SimulationBase
## Base class for simulations
### Stepping:
The method `step()` must be an abstract method that always has to be
implemented by the derived class. The step must succeed always, otherwise,
it should throw a `SimulationStepException`. It means that time adaptivity
must be done internally so that the time step succeeds.
### Writing data:
The method `step()` must be able to decide whether to write data or not.
(Say that in one case one wants that transport writes that every step and in
another case one wants that it writes at the end of the Richards step. The
first case can't be covered writing data in the `run()` method of the
coupled simulation.) Then, enum class called `OutputPolicy` must decide
whether to call the method `write_data()`. This policy can be set and be
extracted by the methods `set_policy(OutputPolicy)` and `output_policy()`
respectively.
The method `write_data()` should be in charge of writing the data.
In principle, this method should be only used following the `OutputPolicy`.
Usually called at the end of each step and at the beginning of the
simulation. Since the `step()` method is in charge of it, it is assumed that
this method writes the *current* state of the model (e.g. intermediate
results of the coupled simulation for the transport state).
### Adaptivity:
For the purpose of having a generic `run()` method in this class, the sketch
of the adaptivity must be provided here. First, adaptivity must be never
done inside the method `step()`. Additionally, if the model can perform
adaptivity, it must provide the method `mark_grid()`, otherwise, it must
throw a `NotImplemented` exception. For completion, there must be a method
called `adapt_grid()` that pack all the known degrees of freedom and, the
grid function spaces and perform the adaptivity.
Similar to the idea of `OutputPolicy` there must be an `AdaptivityPolicy`
set by the methods `set_policy(AdaptivityPolicy)` and `adaptivity_policy()`
respectively which will be set by default to `AdaptivityPolicy::None`.
Having this separation between marking the grid and adaptivity of solutions
leave coupled models to decide which model will mark the grid inside its
method of `mark_grid()` and still handle the adaptivity implementing
`adapt_grid()` separately.
### Time control:
A minimal interface is only providing `begin_time()`, `end_time()` and
`current_time()`.
In order to keep solution vectors minimal at the time of adaptivity, DORiE
expect the several models synchronized in time. Therefore, a good and still
minimal interface is only suggesting the timestep to the model via
`suggest_timestep(double dt)`. Such suggestion has to be taken into account
within the model, and the model must ensure that the timestep is done in
`step()` is never bigger than the suggested one so that coupled models can
achieve synchronization. Naturally, models have to ensure that
`begin_time()` \f$=\f$ `current_time()` at when they are constructed.
### Local Operator Setup:
Since adaptivity can modify the complete setup of the simulation, and since
the method `adapt_grid()` is not necessarily called by the model.
There is a need for the method `post_adapt_grid()` which is in charge of
setup everything again to the new grid. Same argument holds for
`pre_adapt_grid()`.
### Run:
With all the definitions given before, a general algorithm to run the
program can be given by following code:
```
virtual void run()
{
if (output_policy() != OutputPolicy::None)
write_data();
while( current_time() < end_time() )
{
step();
if (adaptivity_policy() != AdaptivityPolicy::None)
if ( current_time() < end_time() )
{
mark_grid();
pre_adapt_grid();
adapt_grid();
post_adapt_grid();
}
}
}
```
@}
*/
} // namespace Dorie
} // namespace Dune
#endif // DUNE_DORIE_SIMULATION_BASE_HH
\ No newline at end of file
#endif // DUNE_DORIE_SIMULATION_BASE_HH
// These groups should gather information strongly related portions of the code.
// In them we aim to explain to other developers:
// - The rationale of the design
// - How careful someone has to be when modifying it
// - Specific naming or other conventions upheld in the code
/**
@defgroup RichardsModel Richards
@{
@ingroup Models
@todo document richards model
@}
**/
// These groups should gather information strongly related portions of the code.
// In them we aim to explain to other developers:
// - The rationale of the design
// - How careful someone has to be when modifying it
// - Specific naming or other conventions upheld in the code
/**
@defgroup TransportModel Transport
@{
@ingroup Models
The transport model implements a class that fulfill the
Dune::Dorie::SimulationBase class requirements (see @ref Models), and which
specifically solves the transport equation for unsaturated media:
@f{eqnarray*}{
\partial_t[\theta C_w] +
\nabla\cdot [\textbf{j}_w C_w] -
\nabla [\theta \mathsf{D}_{eff}\nabla C_w]=0 &\qquad \text{in }
\Omega\\
C_w = g &\qquad \text{on } \Gamma_D
\subseteq\partial\Omega\\
\nabla C_w \cdot \textbf{n} = \textbf{j}_{\scriptscriptstyle
C_w}& \qquad \text{on } \Gamma_N =\partial\Omega \backslash
\Gamma_D
@f}
It implemented with a finite volume scheme and is written so that could be run
independently of the @ref RichardsModel model (e.g. with an
stationary case), or fully coupled with a transient case with fluxes provided
by the Dune::Dorie::RichardsSimulation class.
@}
**/
......@@ -30,33 +30,6 @@
namespace Dune{
namespace Dorie{
/**
@addtogroup TransportModel
@{
The transport model implements a class that fulfill the
Dune::Dorie::SimulationBase class requirements (see @ref Models), and which
specifically solves the transport equation for unsaturated media:
@f{eqnarray*}{
\partial_t[\theta C_w] +
\nabla\cdot [\textbf{j}_w C_w] -
\nabla [\theta \mathsf{D}_{eff}\nabla C_w]=0 &\qquad \text{in }
\Omega\\
C_w = g &\qquad \text{on } \Gamma_D
\subseteq\partial\Omega\\
\nabla C_w \cdot \textbf{n} = \textbf{j}_{\scriptscriptstyle
C_w}& \qquad \text{on } \Gamma_N =\partial\Omega \backslash
\Gamma_D
@f}
It implemented with a finite volume scheme and is written so that could be run
independently of the @ref RichardsModel model (e.g. with an
stationary case), or fully coupled with a transient case with fluxes provided
by the Dune::Dorie::RichardsSimulation class.
@}
**/
/*-------------------------------------------------------------------------*//**
* @brief Traits for the class TransportSimulation.
* @details This class extends BaseTraits to be used for the
......@@ -409,4 +382,4 @@ public:
} // namespace Dorie
} // namespace Dune
#endif // DUNE_DORIE_TRANSPORT_SIMULATION_HH
\ No newline at end of file
#endif // DUNE_DORIE_TRANSPORT_SIMULATION_HH
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment