---
myst:
    substitutions:
        bloc:
            python: 3-16
            cpp: 5-18
---
(calibration_classes_functions_observations_use_case)=
# Use-case for this chapter

To illustrate the methods discussed in the following sections, in more detail than the previously 
introduced dummy examples, a general use-case will be used. This use-case relies on the 
`flowrate` model introduced (along with a descriptive sketch) in [](#launcher_module) and whose 
equation is recalled below:

```{math}
y = f(x) = \frac{2 \pi T_u\left( H_u - H_l\right)}{\ln(\frac{r}{r_{\omega}})\left[ 1 + \frac{2 L
T_u}{\ln(\frac{r}{r_{\omega}}) r_{\omega}^2 K_{\omega}} + \frac{T_u}{T_l}\right]}
```

where the eight parameters are:

1. $r_{\omega} \in [0.05, 0.15]\:\:(m)$: radius of borehole;

2. $r \in [100, 50~000]\:\:(m)$: radius of influence;

3. $T_u \in [63~070, 115~600]\:\:(m^{2}/year)$: Transmissivity of the superior layer of water;

4. $T_l \in [63.1, 116]\:\:(m^{2}/year)$: Transmissivity of the inferior layer of water;

5. $H_u \in [990, 1~110]\:\:(m)$: Potentiometric "head" of the superior layer of water;

6. $H_l \in [700, 820]\:\:(m)$: Potentiometric "head" of the inferior layer of water;

7. $L \in [1~120, 1~680]\:\:(m)$: length of borehole;

8. $K_{\omega} \in [9~855, 12~045]\:\:(m)$: hydraulic conductivity of borehole.

This example has been treated by several authors in the dedicated literature, for instance in 
{cite}`worley1987deterministic`. For our purposes, the idea behind the upcoming examples 
(in this chapter, along with those in the use-case section, see 
[](#use_cases_macro_calibration)) is to consider that one has an observation sample. For this 
function, we consider that from all the inputs, only two have been varied ($r_{\omega}$ and $L$) 
and only one is actually unknown: $H_l$. The rest of the variables are set to fixed values: 
$r=25050$, $T_u=89335$, $T_l=89.55$, $H_u=1050$, $K_{\omega}=10950$. This can be written as the 
following function (using the usual C++ prototype)

```cpp
void flowrateModel(double *x, double *y) {
    double rw = x[1], r = 25050;
    double tu = 89335, tl = 89.55;
    double hu = 1050, hl = x[0];
    double l = x[2], kw = 10950;

    double num = 2.0 * TMath::Pi() * tu * (hu - hl);
    double lnronrw = TMath::Log(r / rw);
    double den = lnronrw * (1.0 + (2.0 * l * tu) / (lnronrw * rw * rw * kw) + tu / tl);

    y[0] = num / den;
}
```

As discussed previously, the function assumes that the user is aware of the input order. In 
this case, the parameter to be calibrated ($H_l$) comes first while the varying inputs 
($r_{\omega}$ and $L$) come later. The first lines of all examples should look like this

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/calibration/classes_functions_observations/" + language + "/use_case." 
    + extension + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + bloc[language] + "\n"
    + "```"
}}