Document model solver loop and time step adaptation schemes in user manual (#174) · Issues · dorie / dorie

Document model solver loop and time step adaptation schemes in user manual

The following discussion from !181 (merged) should be addressed:

@sospinar started a discussion: (+1 comment)

We should probably document the time step scheme algorithm(s) in the user manual.

How about using a uml diagram?

This would be a sketch of a possible diagram. @lriedel Do you know how to add a box on the way back of the while loop?

Description

We need to document the (slightly different) solver routines of the Richards and transport models in the user manual. @sospinar suggested using a UML diagram with the PlantUML extension of Sphinx.

Proposal

Add sphinxcontrib-plantuml to the requirements.txt of the user docs.
Add 'sphinxcontrib.plantuml' to the Sphinx extensions in the conf.py.
Document the time step schemes:
- Richards model: Explain allowed Newton iterations and relation to time step.
- Transport model: Explain solution check first implemented in !181 (merged).
Finalize proposal for loop visualization here

How to test the implementation?

Nothing to test.

Related issues

The following discussion from !181 should be addressed:

- [ ] @sospinar started a [discussion](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/merge_requests/181#note_40151):  (+1 comment)

> > We should probably document the time step scheme algorithm(s) in the user manual.
    > 
    > How about using a [uml diagram](https://build-me-the-docs-please.readthedocs.io/en/latest/Using_Sphinx/UsingGraphicsAndDiagramsInSphinx.html)?
    > 
    > This would be a sketch of a possible diagram. @lriedel Do you know how to add a box on the way back of the while loop?
    > ```plantuml
    >  start
    > 
    >    repeat
    >     :suggest time-step;
    >     :solve;
    > 
    >    repeat while (is solution valid?) is (not valid -> decrease timestep)
    >    :increase timpe-step;
    >    :write data;
    >  stop
    > ```

### Description
We need to document the (slightly different) solver routines of the Richards and transport models in the user manual. @sospinar suggested using a UML diagram with the [PlantUML extension](https://build-me-the-docs-please.readthedocs.io/en/latest/Using_Sphinx/UsingGraphicsAndDiagramsInSphinx.html#using-plantuml) of Sphinx.

### Proposal
* Add `sphinxcontrib-plantuml` to the `requirements.txt` of the user docs.
* Add `'sphinxcontrib.plantuml'` to the Sphinx extensions in the `conf.py`.
* Document the time step schemes:

* Richards model: Explain allowed Newton iterations and relation to time step.
   * Transport model: Explain solution check first implemented in !181.

*Finalize proposal for loop visualization here*

### How to test the implementation?
Nothing to test.

### Related issues

Edited Jan 09, 2020 by Lukas Riedel

Discussion
Designs

The one place for your designs

To enable design management, you'll need to meet the requirements. If you need help, reach out to our support team for assistance.