diff --git a/examples/1ptracer/.doc_config b/examples/1ptracer/.doc_config
index c49b7de3e841fa84fc073ec3e365b8a0aa3dfbc4..1e19fd5213c7856fb57cd73a6cc824fde2728d2d 100644
--- a/examples/1ptracer/.doc_config
+++ b/examples/1ptracer/.doc_config
@@ -18,6 +18,7 @@
],
"doc/main.md" : [
+ "doc/mainintro.md",
"main.cc"
],
diff --git a/examples/1ptracer/doc/main.md b/examples/1ptracer/doc/main.md
index 9f9343f3c0e720e49c7f3c3bb153f5c85eb41c5d..f2005ef8a590e4ad9d19590257741b193d1dd41e 100644
--- a/examples/1ptracer/doc/main.md
+++ b/examples/1ptracer/doc/main.md
@@ -4,23 +4,27 @@
| [:arrow_left: Back to the main documentation](../README.md) | [:arrow_left: Go back to part 2](tracermodel.md) |
|---|---:|
+# Part 3: Main program flow
+We want to solve a single-phase flow problem
+to obtain a pressure distribution in the domain. Subsequently, we compute a volume fluxes field
+based on the obtained pressure distribution and pass it to the tracer problem.
+Finally, we solve a transient transport problem for a tracer using the computed volume fluxes.
+This main program flow is implemented in the `main()` function
+of the program which is defined in the file `main.cc` described below.
-# Part 3: Main program flow (`main.cc`)
+The code documentation is structured as follows:
[[_TOC_]]
-This file contains the main program flow. In this example, we solve a single-phase flow problem
-to obtain a pressure distribution in the domain. Subsequently, the distribution of volume fluxes
-is computed from that pressure distribution, which is then passed to a tracer problem to solve
-the transport of an initial contamination through the model domain.
+## The main file (`main.cc`)
<details open>
<summary><b>Click to hide/show the file documentation</b> (or inspect the [source code](../main.cc))</summary>
-## Included header files
+### Included header files
<details><summary> Click to show includes</summary>
These are DUNE helper classes related to parallel computations, time measurements and file I/O
@@ -74,7 +78,7 @@ at the documentation provided therein.
</details>
-## The main function
+### The main function
We will now discuss the main program flow implemented within the `main` function.
At the beginning of each program using Dune, an instance of `Dune::MPIHelper` has to
be created. Moreover, we parse the run-time arguments from the command line and the
@@ -104,7 +108,7 @@ and the tracer transport setups, respectively.
using TracerTypeTag = Properties::TTag::TracerTest;
```
-### Step 1: Create the grid
+#### Step 1: Create the grid
The `GridManager` class creates the grid from information given in the input file.
This can either be a grid file, or in the case of structured grids, one can specify the coordinates
of the corners of the grid and the number of cells to be used to discretize each spatial direction.
@@ -119,7 +123,7 @@ the grid is only created once using the grid type defined by the `OnePTypeTag` o
const auto& leafGridView = gridManager.grid().leafGridView();
```
-### Step 2: Solving the single-phase problem
+#### Step 2: Solving the single-phase problem
First, a finite volume grid geometry is constructed from the grid that was created above.
This builds the sub-control volumes (scv) and sub-control volume faces (scvf) for each element
of the grid partition.
@@ -203,7 +207,7 @@ problem defined in `problem_1p.hh`. Let us now write this solution to a VTK file
<< "The cumulative CPU time was " << timer.elapsed()*comm.size() << " seconds.\n";
```
-### Step 3: Computation of the volume fluxes
+#### Step 3: Computation of the volume fluxes
We use the results of the 1p problem to calculate the volume fluxes across all sub-control volume
faces of the discretization and store them in the vector `volumeFlux`. In order to do so, we iterate
over all elements of the grid, and in each element compute the volume fluxes for all sub-control volume
@@ -247,7 +251,7 @@ faces embeded in that element.
}
```
-### Step 4: Solving the tracer transport problem
+#### Step 4: Solving the tracer transport problem
First, we instantiate the tracer problem containing initial and boundary conditions,
and pass to it the previously computed volume fluxes (see the documentation of the
file `spatialparams_tracer.hh` for more details).
@@ -315,7 +319,7 @@ the solution of a time step into a corresponding vtk file.
vtkWriter.write(0.0);
```
-#### The time loop
+##### The time loop
We start the time loop and solve a new time step as long as `tEnd` is not reached. In every time step,
the problem is assembled and solved, the solution is updated, and when a checkpoint is reached the solution
is written to a new vtk file. In addition, statistics related to CPU time, the current simulation time
@@ -380,7 +384,7 @@ before the program is terminated.
}
```
-### Exception handling
+#### Exception handling
In this part of the main file we catch and print possible exceptions that could
occur during the simulation.
<details><summary> Click to show exception handler</summary>
diff --git a/examples/1ptracer/doc/mainintro.md b/examples/1ptracer/doc/mainintro.md
new file mode 100644
index 0000000000000000000000000000000000000000..99a4d831a4b5b4fed27d7be34bb15f530be5085f
--- /dev/null
+++ b/examples/1ptracer/doc/mainintro.md
@@ -0,0 +1,12 @@
+# Part 3: Main program flow
+
+We want to solve a single-phase flow problem
+to obtain a pressure distribution in the domain. Subsequently, we compute a volume fluxes field
+based on the obtained pressure distribution and pass it to the tracer problem.
+Finally, we solve a transient transport problem for a tracer using the computed volume fluxes.
+This main program flow is implemented in the `main()` function
+of the program which is defined in the file `main.cc` described below.
+
+The code documentation is structured as follows:
+
+[[_TOC_]]
diff --git a/examples/1ptracer/main.cc b/examples/1ptracer/main.cc
index 584b1639c37d8a941003e3347acce466fbfa22e3..d8406e8db8b4906d3ce42baf96f9142bb0f49582 100644
--- a/examples/1ptracer/main.cc
+++ b/examples/1ptracer/main.cc
@@ -16,18 +16,10 @@
* You should have received a copy of the GNU General Public License *
* along with this program. If not, see <http://www.gnu.org/licenses/>. *
*****************************************************************************/
-// # Part 3: Main program flow (`main.cc`)
-//
-// [[_TOC_]]
-//
-// This file contains the main program flow. In this example, we solve a single-phase flow problem
-// to obtain a pressure distribution in the domain. Subsequently, the distribution of volume fluxes
-// is computed from that pressure distribution, which is then passed to a tracer problem to solve
-// the transport of an initial contamination through the model domain.
-//
+// ## The main file (`main.cc`)
// [[content]]
//
-// ## Included header files
+// ### Included header files
// [[details]] includes
// [[exclude]]
// Some generic includes.
@@ -69,7 +61,7 @@
// [[/details]]
//
-// ## The main function
+// ### The main function
// We will now discuss the main program flow implemented within the `main` function.
// At the beginning of each program using Dune, an instance of `Dune::MPIHelper` has to
// be created. Moreover, we parse the run-time arguments from the command line and the
@@ -95,7 +87,7 @@ int main(int argc, char** argv) try
using OnePTypeTag = Properties::TTag::IncompressibleTest;
using TracerTypeTag = Properties::TTag::TracerTest;
- // ### Step 1: Create the grid
+ // #### Step 1: Create the grid
// The `GridManager` class creates the grid from information given in the input file.
// This can either be a grid file, or in the case of structured grids, one can specify the coordinates
// of the corners of the grid and the number of cells to be used to discretize each spatial direction.
@@ -109,7 +101,7 @@ int main(int argc, char** argv) try
const auto& leafGridView = gridManager.grid().leafGridView();
// [[/codeblock]]
- // ### Step 2: Solving the single-phase problem
+ // #### Step 2: Solving the single-phase problem
// First, a finite volume grid geometry is constructed from the grid that was created above.
// This builds the sub-control volumes (scv) and sub-control volume faces (scvf) for each element
// of the grid partition.
@@ -177,7 +169,7 @@ int main(int argc, char** argv) try
<< "The cumulative CPU time was " << timer.elapsed()*comm.size() << " seconds.\n";
// [[/codeblock]]
- // ### Step 3: Computation of the volume fluxes
+ // #### Step 3: Computation of the volume fluxes
// We use the results of the 1p problem to calculate the volume fluxes across all sub-control volume
// faces of the discretization and store them in the vector `volumeFlux`. In order to do so, we iterate
// over all elements of the grid, and in each element compute the volume fluxes for all sub-control volume
@@ -220,7 +212,7 @@ int main(int argc, char** argv) try
}
// [[/codeblock]]
- // ### Step 4: Solving the tracer transport problem
+ // #### Step 4: Solving the tracer transport problem
// First, we instantiate the tracer problem containing initial and boundary conditions,
// and pass to it the previously computed volume fluxes (see the documentation of the
// file `spatialparams_tracer.hh` for more details).
@@ -277,7 +269,7 @@ int main(int argc, char** argv) try
vtkWriter.write(0.0);
// [[/codeblock]]
- // #### The time loop
+ // ##### The time loop
// We start the time loop and solve a new time step as long as `tEnd` is not reached. In every time step,
// the problem is assembled and solved, the solution is updated, and when a checkpoint is reached the solution
// is written to a new vtk file. In addition, statistics related to CPU time, the current simulation time
@@ -337,7 +329,7 @@ int main(int argc, char** argv) try
return 0;
}
-// ### Exception handling
+// #### Exception handling
// In this part of the main file we catch and print possible exceptions that could
// occur during the simulation.
// [[details]] exception handler