From f0c7799524637b0a5098656e4bcda1e58bf75340 Mon Sep 17 00:00:00 2001
From: Timo Koch <timokoch@math.uio.no>
Date: Mon, 3 Apr 2023 01:13:22 +0200
Subject: [PATCH] [slides] Improve grid and runtime
---
slides/grid.md | 92 +++++++++++++++++
slides/params.md | 186 ++++++++++++++++++++++++++++++++++
slides/problem.md | 6 +-
slides/runtimeparams-grids.md | 146 --------------------------
4 files changed, 281 insertions(+), 149 deletions(-)
create mode 100644 slides/grid.md
create mode 100644 slides/params.md
delete mode 100644 slides/runtimeparams-grids.md
diff --git a/slides/grid.md b/slides/grid.md
new file mode 100644
index 00000000..d6635a5b
--- /dev/null
+++ b/slides/grid.md
@@ -0,0 +1,92 @@
+---
+title: Grids
+---
+
+# Grids
+
+## Grid implementations I
+
+Implementations of the Dune grid interface
+
+* **YASPGrid** (structured, n-dim, parallel tensorproduct grid)
+* **UGGrid** (2D/3D, unstructured, parallel, multi-geometry)
+* **ALUGrid** (2D/3D, unstructured, parallel, simplex/cube)
+* **FOAMGrid** (1D-2D, Dynamic, Multi-dimension/Network Problems)
+
+## Grid implementations II
+
+Implementations of the Dune grid interface
+
+* **OPMGrid** (Cornerpoint grids)
+* **OneDGrid** (1D adaptive grid)
+* **SPGrid** (structured, n-dim, parallel tensorproduct grid)
+* **SubGrid** (meta-grid, turn subdomain into grid)
+* **GeometryGrid** (meta-grid, grid by coordinate transformation)
+
+## Create grid
+
+* Set grid types via properties specialization:
+ ```cpp
+ #include <dune/grid/yaspgrid.hh>
+ ...
+ template<class TypeTag>
+ struct Grid<TypeTag, TTag::Injection2p>{
+ using type = Dune::YaspGrid<2>;
+ };
+ ```
+
+* Include the matching grid manager header files in main file and create the grid via a grid manager instance
+ ```cpp
+ #include <dumux/io/grid/gridmanager_yasp.hh>
+ ...
+ using Grid = GetPropType<TypeTag, Properties::Grid>;
+ GridManager<Grid> gridManager;
+ gridManager.init();
+ ```
+
+## Create grid
+
+The grid manager looks for grid information in the runtime parameter tree
+
+## Structured Grid
+
+* Grid from basic parameters
+ ```ini
+ [Grid]
+ LowerLeft = 0 0 # x, y entry (3 entries for 3D)
+ UpperRight = 1 1
+ Cells = 10 5
+ ```
+
+<img src=img/params_grid.png width="200">
+
+## Grid from file
+
+* Read in grid from file (specified in input-file) using a relative or absolute path to the grid file
+ ```ini
+ [Grid]
+ File = ./grids/heterogeneousSmall.dgf
+ ```
+
+* Supported grid file formats
+ * DGF (Dune Grid Format)
+ * Gmsh (MSH format version 2)
+ * Cornerpoint grid format (`*.grdecl` file, via opm-grid)
+
+## Constructing grid without grid manager
+
+Consult the documentation of the grid implementation, e.g.
+constructing a `Dune::YaspGrid`:
+
+```cpp
+constexpr int dim = 2;
+std::array<int, dim> cells; cells.fill(30);
+Dune::FieldVector<double, dim> lowerLeft(1.0), upperRight(2.0);
+using Yasp = Dune::YaspGrid<dim, Dune::EquidistantOffsetCoordinates<double, dim>>;
+Yasp yasp(lowerLeft, upperRight, cells);
+```
+
+# Excercise
+## Exercise
+
+* Go to [Grid excercise](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/tree/master/exercises/exercise-grids#exercise-grids-dumux-course)
diff --git a/slides/params.md b/slides/params.md
new file mode 100644
index 00000000..d8dd8a4c
--- /dev/null
+++ b/slides/params.md
@@ -0,0 +1,186 @@
+---
+title: Runtime Parameters
+---
+
+# Runtime Parameters
+
+## Runtime Parameters
+
+* Configuration at runtime (avoid recompiling)
+* We will look at:
+ - Parameters in input files
+ - Command line parameters
+ - Default parameters
+
+## Initialize Parameter Tree
+
+* Parameters are initialized by `Parameters::init(...)`
+* `Parameters::init(...)` constructs a parameter tree [singleton](https://en.wikipedia.org/wiki/Singleton_pattern) from which parameters can be obtained
+* The parameter tree stores strings (key-value) and parameter trees (subtrees, groups)
+
+## Initialize Parameter Tree
+
+```cpp
+#include <dumux/common/parameters.hh>
+int main(int argc, char** argv)
+{
+ Dumux::Parameters::init(argc, argv);
+ return 0;
+}
+```
+
+## Initialize Parameter Tree
+
+Expliticly specify parameter file (default: `params.input`)
+```cpp
+#include <dumux/common/parameters.hh>
+int main(int argc, char** argv)
+{
+ Dumux::Parameters::init(argc, argv, "params.input");
+ return 0;
+}
+```
+
+## Initialize Parameter Tree
+
+Explciticly specify default parameters
+```cpp
+#include <dune/common/parametertree.hh>
+#include <dumux/common/parameters.hh>
+int main(int argc, char** argv)
+{
+ Dumux::Parameters::init(argc, argv, [](Dune::ParameterTree& p){
+ p["key"] = "value";
+ p["group.key"] = "value2";
+ ...
+ });
+ return 0;
+}
+```
+
+## Initialize Parameter Tree
+
+Without reading command-line arguments
+```cpp
+#include <dumux/common/parameters.hh>
+int main(int argc, char** argv)
+{
+ Dumux::Parameters::init("params.input");
+ return 0;
+}
+```
+
+## Reading Runtime Parameters
+
+* Read parameters from the parameter tree with `getParam` (converts `std::string` to requested type)
+ ```cpp
+ paramname_ = getParam<TYPE>("GROUPNAME.PARAMNAME", default);
+ ```
+* Examples:
+ ```cpp
+ bool enableGravity = getParam<bool>("Problem.EnableGravity", true);
+ ```
+ ```cpp
+ auto upperRight
+ = getParam<Dune::FieldVector<double, 3>>("FreeFlow.Grid.UpperRight");
+ ```
+* Signature without default: throws `ParameterException` if parameter doesn't exist.
+
+## Reading Runtime Parameters
+
+* `getParamFromGroup` variant traverses the parameter tree
+ ```cpp
+ paramname_ = getParamFromGroup<TYPE>("GROUPNAME", "PARAMNAME", default);
+ ```
+* Example
+ ```cpp
+ bool enableGravity = getParamFromGroup<bool>("FreeFlow", "Problem.Gravity");
+ ```
+ - first looks for `FreeFlow.Problem.Gravity`
+ - then looks for `Problem.Gravity`
+* Useful when configuring multiple simulation components or multi-domain problem
+via the single parameter tree
+
+
+## Reading Runtime Parameters
+
+* Remark: Reading parameters is a slow operation
+* Read parameters in constructors of high-level classes
+* Never read parameters in functions called for all elements
+
+## Checking for Runtime Parameters
+
+* Check: Does parameter exist in the parameter tree?
+ ```cpp
+ if (hasParam("GROUPNAME.PARAMNAME"))
+ // do something with parameter
+ ```
+* With group prefix lookup
+ ```cpp
+ if (hasParamInGroup("GROUPNAME","PARAMNAME"))
+ ```
+
+## Parameter tree logs usage
+
+```cpp
+#include <dumux/common/parameters.hh>
+int main(int argc, char** argv)
+{
+ Dumux::Parameters::init(argc, argv);
+ ...
+ Dumux::Parameters::print(); // print report
+ return 0;
+}
+```
+Reports unused parameters. Great for detecting typos in
+configuration file.
+
+## Parameter input file
+
+Dune INI syntax (`[Group]` and `Key = Value` pairs)
+
+`params.input`
+
+```cpp
+[Grid]
+LowerLeft = 0 0
+UpperRight = 60 40
+Cells = 24 16
+
+[Problem]
+Name = test
+
+[FreeFlow.Problem]
+Name = test_ff
+```
+
+## Command-line arguments
+
+```sh
+./executable params.input -Key Value -Key2 Value2 -Key3 "a b c"
+```
+
+Examples:
+```sh
+./executable -Grid.Refinement 2
+./executable params_alt.input -Grid.Refinement 2
+./executable -Grid.Refinement 2 -Grid.Cells "10 10"
+```
+
+## Parameter precedence
+
+1. Command-line arguments overwrite
+2. Input file arguments overwrite
+3. User-default arguments overwrite
+4. Global defaults
+
+## Parameter list
+
+An overview of all available parameters can be found in the [doxygen documentation](https://dumux.org/docs/doxygen/releases/3.6/a00008.html).
+
+<img src=img/parameterlist.png>
+
+# Excercise
+## Exercise
+
+* Go to [Runtime parameter exercise](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/tree/master/exercises/exercise-runtimeparams#exercise-runtime-parameters-dumux-course)
diff --git a/slides/problem.md b/slides/problem.md
index dcc696e8..6e495120 100644
--- a/slides/problem.md
+++ b/slides/problem.md
@@ -356,7 +356,7 @@ Cells = 24 16
Name = test
```
-See [slides on runtime parameters](./runtimeparams-grids.html) for details.
+See [Part I: Runtime parameters](./params.html) for details.
# Main program and main function
@@ -387,7 +387,7 @@ Parse runtime parameters:
Dumux::Parameters::init(argc, argv);
```
-See [slides on runtime parameters](./runtimeparams-grids.html) for details.
+See [Part I: Runtime parameters](./params.html) for details.
##
@@ -415,7 +415,7 @@ const auto& grid = gridManager.grid();
const auto& leafGridView = grid.leafGridView();
```
-More details on the grid in [Part I: Parameters and grids](./runtimeparams-grids.html).
+More details on the grid in [Part I: Grid](./grid.html).
##
diff --git a/slides/runtimeparams-grids.md b/slides/runtimeparams-grids.md
deleted file mode 100644
index 88f92372..00000000
--- a/slides/runtimeparams-grids.md
+++ /dev/null
@@ -1,146 +0,0 @@
----
-title: Runtime Parameters and Grids
-subtitle: Introduction to DuMu$^\mathsf{X}$
----
-
-# Runtime Parameters
-
-## Runtime Parameters
-
-* Avoid recompiling
-* The same executable can be used to test different sets of parameters via shell script.
-
-<p style="text-align: left;">Practical concern:</p>
-
-* If the parameter can be set at compile time, it is often cleaner and faster to do so. Only use parameters, when it is needed.
-
-## Input-file contents
-
-* Input file syntax:
- ```ini
- [MyGroup]
- MyParameter = 2
- ```
-* Examples:
-
- | Groups | Parameters | | |
- |-----------|---------------|---------------|------------|
- | Component | GasDensity | LiquidDensity | MolarMass |
- | Problem | EnableGravity | Name | |
- | Grid | Cells | LowerLeft | UpperRight |
-
-## Reading Runtime Parameters
-
-* Use runtime parameters in any file in DuMu$^\mathsf{X}$
- ```cpp
- paramname_ = getParam<TYPE>(“GROUPNAME.PARAMNAMEâ€);
- ```
- or
- ```cpp
- paramname_ = getParamFromGroup<TYPE>("GROUPNAME", "PARAMNAME");
- ```
-* You can also set a default value when calling a runtime parameter. In case that no parameter is set at runtime, the default value will be used. Be careful! Many parameters already have a default value.
- ```cpp
- paramname_ = getParam<TYPE>(“GROUPNAME.PARAMNAMEâ€, default);
- ```
-
-## Reading Runtime Parameters
-
-* Remark: If you need to read in a parameter multiple times in for one problem, use `static const` to reduce runtime. E.g.
- ```cpp
- static const bool enableGravity = getParam<bool>("Problem.EnableGravity");
- ```
-
-## Functions hasParam and hasParamInGroup
-
-* Check: Parameter in input file?
- ```cpp
- if (hasParam("GROUPNAME.PARAMNAME"))
- std::cout << "GROUPNAME.PARAMNAME is read from the input file." << std::endl;
- else
- std::cout << "Using the default value for GROUPNAME.PARAMNAME." << std::endl;
- ```
-* Another way of writing the upper
- ```cpp
- if (hasParamInGroup("GROUPNAME","PARAMNAME"))
- ```
- instead of
- ```cpp
- if (hasParam("GROUPNAME.PARAMNAME"))
- ```
-
-## Parameter list
-
-An overview of all available parameters can be found in the [doxygen documentation](https://dumux.org/docs/doxygen/releases/3.6/a00008.html).
-
-<img src=img/parameterlist.png>
-
-# Grids
-
-## Grid types
-
-* **YASPGrid** (structured, n-dimensional, parallel tensorproduct grid)
-* **UGGrid** (2D/3D, unstructured, parallel, multi-geometry)
-* **ALUGrid** (2D/3D, unstructured, parallel, simplex/cube)
-* **FOAMGrid** (1D-2D, Dynamic, Multi-dimension/Network Problems)
-* **OPMGrid** (Cornerpoint grids)
-
-## Create grid
-
-* Set grid types in properties file:
- ```cpp
- // Set the grid type
- template<class TypeTag>
- struct Grid<TypeTag, TTag::Injection2p>{
- using type = Dune::YaspGrid<2>;
- };
- ```
-
-* Include the matching grid manager header files in main file.
- ```cpp
- // grid manager for yasp grid
- #include <dumux/io/grid/gridmanager_yasp.hh>
- ```
-
-* Create grid in the main file
- ```cpp
- // try to create a grid (from a grid file or the input file)
- GridManager<GetPropType<TypeTag, Properties::Grid>> gridManager;
- gridManager.init();
- ```
-
-## Grid from file
-
-* Read in grid from file (specified in input-file)
- ```ini
- [Grid]
- File = ./grids/heterogeneousSmall.dgf
- # relative path to the grid file
- ```
-
-* Supported grid file formats
- * DGF (Dune grid format)
- * Gmsh (gmsh.info)
- * Cornerpoint grid format (.grdecl file, see opm)
-
-
-## Grid from input
-* Develop grid from basic spatial descriptions (specified in input-file)
- ```ini
- [Grid]
- LowerLeft = 0 0 # x, y entry (3 entries for 3D)
- UpperRight = 1 1
- Cells = 10 5
- ```
-
-<img src=img/params_grid.png width="300">
-
-# Excercises
-## Exercises
-<p style="text-align: left;">Exercise about runtime parameters:</p>
-
-* Go to [https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/tree/master/exercises/exercise-runtimeparams](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/tree/master/exercises/exercise-runtimeparams) and check out the README
-
-<p style="text-align: left;">Exercise about grids:</p>
-
-* Go to [https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/tree/master/exercises/exercise-grids](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/tree/master/exercises/exercise-grids) and check out the README
--
GitLab