Skip to content

Add high-level documentation on the main concepts in Dumux

I propose a new structure for the High-Level-Design Document (HLDD). HLD_Proposal.md

After reviewing more sources, I think we mixed here High-Level and Architecture and general Documentation. This could lower the pain of potential double documentation. One could take the old HLD Branches/MR and:

  1. Filter for HLDD
  2. Take architectural parts such as interfaces and use this for Architectural Documentation
  3. If something is now left behind and interesting think about adding it to the normal Documentation

It was decided to use the diagram added in !3755 as a starting point. Each class here gets two to three sentences. Not more.

From here on the old Issue.

On Dumux Day, 25th of May, we said that it could be good to have such high-level docu somewhere (e.g. in the handbook?). This could describe generic concepts like grid geometry (is actually nicely described in the last Dumux paper), grid variables, etc...

Current status of this issue is related to !3406

If you want to work on the high_level_documentation:
For each file you are working on:

  • Create a branch from !3406
  • Create a MR to !3406
  • When you are happy with the description of the class merge that branch in !3406 and tick of the box here. Afterwards tag yourself.Also include the MR number.

Thank you in advance!
Main problem that needs to be resolved:
Doxygen move everything that is included in a group to that group. One needs to find a way to have high-level docu in the groups while still having a monolithic one source high-level docu.

General approach to tackle this:

1st Describe entities that are modular

  • In easy words, possible usage and interface to other entities
  • Is this entity necessary to run a simulation

2nd Describe non modular entities

  • In easy words, possible usage and interface to other entities
  • Is this entity necessary to run a simulation
  • Highlight dependencies and why they are necessary

3rd Find out and show how they are interconnected

  • Highlight if this entity is necessary (i.e., green vs. red)

The following entities should be modular:

The following entities are not modular:

General remarks and details about accessing data

General remarks on property system

Edited by Leon Keim