From a4d8fd8194c07b2a8d8b90997c005d5d5b6bfaed Mon Sep 17 00:00:00 2001
From: Anna Mareike Kostelecky <anmako96@web.de>
Date: Fri, 31 Mar 2023 16:36:57 +0000
Subject: [PATCH] [exercise][runtimeparams] minor changes to README.md
---
exercises/exercise-runtimeparams/README.md | 77 +++++++++++-----------
1 file changed, 37 insertions(+), 40 deletions(-)
diff --git a/exercises/exercise-runtimeparams/README.md b/exercises/exercise-runtimeparams/README.md
index 9d6129fc..57349c36 100644
--- a/exercises/exercise-runtimeparams/README.md
+++ b/exercises/exercise-runtimeparams/README.md
@@ -3,11 +3,11 @@
## Problem set-up
-Here we will expand on what we've covered in the basics exercise, and the problem set up will remain the same.
+Here we will expand on what we've covered in the basics exercise (see `dumux-course/exercises/exercise-basic/README.md`), and the problem set up will remain the same.
## Preparing the exercise
-* Navigate to the directory `dumux-course/exercises/exercise-runtimeparams/`
+Navigate to the directory `dumux-course/exercises/exercise-runtimeparams/`
<br><br>
### Task 1: Understanding Input Parameters
@@ -17,36 +17,32 @@ For this task we will edit the following files:
* The shared __problem file__: `problem.hh`
* And the shared __input file__: `params.input`
-Parameters can either be directly defined within your program, or specified
-via the input file. Within every main file, (`*.cc`), the following function
-is called, which will read in the input file parameters
+Parameters can either be directly defined within your program, or specified via the input file. Within every main file, (`*.cc`), the following function is called
```c++
// parse command line arguments and input file
Parameters::init(argc, argv);
```
-
-This input file should either be named the same as the executable file, with a
-trailing `*.input`, or be named `prarams.input` as is standard in our CMake system.
-Alternatively, arbitrarily named input file names can be explicitly written
-as the first shell argument after the executable file is called.
+This will read in the parameters from the input file.
+The input file should either be named the same as the executable file, with a trailing `*.input`, or be named `prarams.input` as this is the standard in our CMake system.
+Alternatively, arbitrarily named input files (e.g. `exercise1.input`) can be explicitly written as the first shell argument after the executable file (here `exercise_runtimeparams`) is called.
```bash
./exercise_runtimeparams
- (Calls the file params.input as the default input file.)
+ #(Calls the file params.input as the default input file.)
```
```bash
./exercise_runtimeparams exercise1.input
- (Calls the input file provided (exercise1.input) as the input file.)
+ #(Calls the input file provided (exercise1.input) as the input file.)
```
In the input file `params.input` you can find the following section
```ini
[SpatialParams]
PermeabilityAquitard = 1e-15 # m^2
-EntryPressureAquitard = 4.5e4 # Pa
+Aquitard.BrooksCoreyPcEntry = 4.5e4 # Pa
PermeabilityAquifer = 1e-12 # m^2
-EntryPressureAquifer = 1e4 # Pa
+Aquifer.BrooksCoreyPcEntry = 1e4 # Pa
```
When a parameter is defined directly within your program, you'll need to recompile your program every time you change the value. When a parameter is passed via the input file, this is not the case. If we decided to vary the entry pressure in our geologic units a few times via the parameters listed above, there would be no need to recompile between simulation runs.
@@ -79,11 +75,11 @@ variable_ = getParamFromGroup<TYPE>("GROUPNAME", "PARAMNAME");
```
`<TYPE>`,`<GROUPNAME>`,`<PARAMNAME>` should be appropriately defined for your variable:
- * `<TYPE>` is the type of the parameter to read
- * `<GROUPNAME>` is the group in the input file
- * `<PARAMNAME>` is the name of the parameter in the input file
+ * `<TYPE>` is the type of the parameter to read (e.g. `Scalar`)
+ * `<GROUPNAME>` is the group in the input file (e.g. `Problem`)
+ * `<PARAMNAME>` is the name of the parameter in the input file (e.g. `AquiferDepth`)
-An example of this is already performed in the problem constructor. The Injection Duration (`injectionDuration_`) is defined via the input file, and can then be used later in the problem.
+An example of this is already performed in the problem constructor. The Injection Duration (`injectionDuration_`) is defined via the input file and can then be used later in the problem header.
```c++
// depth of the aquifer, units: m
@@ -94,13 +90,13 @@ injectionDuration_ = getParamFromGroup<Scalar>("Problem","InjectionDuration");
The injection duration parameter is located in the `[Problem]` group, is named `InjectionDuration`, and has the type `Scalar`.
-This variable should then be defined as Scalar at the bottom of this problem class in the private section.
+This variable should then be defined as a `Scalar` at the bottom of this problem class in the private section.
```c++
Scalar injectionDuration_;
```
-In the input file, within the group `[Problem]`, a value is set to the Parameter name called in the class.
+In the input file, within the group `[Problem]`, a value is set to the Parameter name. This is then called in the problem class.
```ini
[Problem]
@@ -108,21 +104,21 @@ InjectionDuration = 2.628e6 # in seconds, i.e. one month
```
* > __Task 2__: The goal is to replace the value `-1e-4` in
-
-```c++
-values[Indices::conti0EqIdx + FluidSystem::N2Idx]= -1e-4/FluidSystem::molarMass(FluidSystem::N2Idx);
-```
-with a runtime variable.
-
-* (2a) Develop a new variable called `totalAreaSpecificInflow_`,
-* (2b) record a value to this variable from a path in the input file, and
-* (2c) incorporate this variable into the injection boundary condition.
-
-When your problem file and the input file are edited, compile and run the exercise.
-
-```bash
-make exercise_runtimeparams && ./exercise_runtimeparams params.input
-```
+ >
+ >```c++
+ >values[Indices::conti0EqIdx + FluidSystem::N2Idx]= -1e-4/FluidSystem::molarMass(FluidSystem::N2Idx);
+ >```
+ >with a runtime variable.
+ >
+ > * (2a) Develop a new variable called `totalAreaSpecificInflow_`,
+ > * (2b) Assign a value to this variable from a path in the input file, and
+ > * (2c) Incorporate this variable into the injection boundary condition.
+ >
+ > When your problem file and the input file are edited, compile and run the exercise.
+ >
+ >```bash
+ > make exercise_runtimeparams && ./exercise_runtimeparams params.input
+ >```
<br><br>
### Task 3: Default Values for Runtime Parameters
<hr>
@@ -134,24 +130,25 @@ loggingparametertree.hh:316:
Key Problem.TotalAreaSpecificInflow not found in the parameter tree ---> Abort!
```
-To avoid this, we can place a default value in the variable definition. Whenever the parameter is specified in the input file, this default value in your class will be overwritten, but in the case that no value is provided in the input file, this default value will be used. In order to do this, follow the following template.
+To avoid this, we can place a default value in the variable definition. Whenever the parameter is specified in the input file, this default value in your class will be overwritten. In the case that no value is provided in the input file, this default value will be used. In order to do this, follow the following template.
```c++
variable_ = getParam<TYPE>("GROUPNAME.PARAMNAME", DEFAULTVALUE);
```
+or
```c++
variable_ = getParamFromGroup<TYPE>("GROUPNAME","PARAMNAME", DEFAULTVALUE);
```
-* > __Task 3__: Set up the totalAreaSpecificInflow_ variable to record a default value of `-1e-4`, and run this with and without a provided value of `-1e-3` in the input file.
+* > __Task 3__: Set up the `totalAreaSpecificInflow_` variable to record a default value of `-1e-4` and run this with and without a provided value of `-1e-3` in the input file.
<br><br>
### Task 4: Other Runtime Parameter Functions
<hr>
-Setting default values for variables defined with runtime parameters can also lead to problems. If one runtime parameter from the input file is set to multiple different variables, each with a different Default value, changing the variable in one location can lead to unexpected changes elsewhere. On top of this, in DuMu<sup>x</sup>, there are a few base variables that are set with default values for all DuMu<sup>x</sup> simulations. These can be found in the header file `dumux/common/parameters.hh` in the function `globalDefaultParameters`.
+Setting default values for variables defined with runtime parameters can also lead to problems. If one runtime parameter from the input file is set to multiple different variables, each with a different default value, changing the variable in one location can lead to unexpected changes elsewhere. On top of this, in DuMu<sup>x</sup>, there are a few base variables that are set with default values for all DuMu<sup>x</sup> simulations. These can be found in the header file `dumux/common/parameters.hh` in the function `globalDefaultParameters`.
-One way to check this is to use either the `hasParam()` or the `hasParamInGroup()` function. These functions returning `bool`s will check to see if a parameter is read in via the input file. These functions are also both defined in the `dumux/dumux/common/parameters.hh` class, and follow a similar format to that of `getParam()` and `getParamFromGroup()`
+One way to check this is to use either the `hasParam()` or the `hasParamInGroup()` function. These functions returning `bool`s will check to see if a parameter is read in via the input file. These functions are also both defined in the `dumux/dumux/common/parameters.hh` class, and follow a similar format to that of `getParam()` and `getParamFromGroup()`.
An example of this would look like this:
@@ -171,4 +168,4 @@ else
Using these functions we can better check which parameter values are being included in our program.
-* > __Task 4__: Using one of the bool hasParam functions, place output in the problem file to alert the user to where the parameter value comes from.
+* > __Task 4__: Using one of the bool `hasParam` functions, place an output in the problem file to alert the user where the parameter value comes from.
--
GitLab