---
myst:
    substitutions:
        macro:
            python: 1-5,17-62,69-86,88-94,96-116,118-124
            cpp: 6-8,15-57,66-83,86-92,95-115,118-124
        bloc1:
            python: "30"
            cpp: "25"
        bloc2:
            python: 45-62,69-79
            cpp: 40-57,66-76
        bloc3:
            python: 81-86,88-94,96-116,118-124
            cpp: 78-83,86-92,95-115,118-124
        console:
            python: 2-51,54-61
            cpp: 6-55,58-65
---
(use_cases_macro_calibration_mcmc)=
# Macro "**calibrationMCMCFlowrate1D.{{extension}}**"

## Objective

The goal here is to calibrate the parameter $H_l$ within the `flowrate` model, while varying only two 
inputs ($r_{\omega}$ and $L$). The remaining variables are fixed to the following values: $r=25050$, 
$T_u=89335$, $T_l=89.55$, $H_u=1050$, $K_{\omega}=10950$. The context of this example has already been 
presented in [](#calibration_classes_functions_observations_use_case), including the model (implemented 
here as a C++ function) and the initial lines defining the {{tds}} objects. This macro demonstrates how 
to apply the Markov chain Monte Carlo approach and more precisely the component-wise Metropolis-Hastings algorithm using a **Relauncher**-based architecture.

## Macro {{uranie}}

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/calibration/use_cases/" + language + "/calibrationMCMCFlowrate1D."
    + extension
    + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + macro[language] + "\n"
    + "```"
}}

Much of this code has already been covered in the previous section 
[](#use_cases_macro_calibration_minimisation) (up to the sequential run). The main difference here 
is that the input parameter is now defined as a `TStochasticDistribution`, representing the *a priori* 
chosen distribution.

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/calibration/use_cases/" + language + "/calibrationMCMCFlowrate1D."
    + extension
    + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + bloc1[language] + "\n"
    + "```"
}}

The model is defined (from a `TCIntEval` instance with the three input variables discussed above, 
in the **correct order**) along with the computation distribution method (sequential). 

The calibration object is 
then created by specifying both the number of iterations of the algorithm (set to 2000). The 
likelihood function is defined as Gaussian, with the reference dataserver, the input and output 
variables, and the standard deviation of the experimental data provided as arguments. Several 
additional options are configured: the component-wise algorithm is selected, the acceptance 
range is set, the interval between two console displays is specified, the number of chains to 
initialise is defined, the starting points of each chain are assigned (one by one), and the 
standard deviation of the initial proposal distribution is set (for all chains at once). For 
further details on these options, see [](#calibration_markov_chain_mcmc_properties). Finally, 
the estimation process is performed, using the chosen MCMC algorithm (component-wise Metropolis-Hastings).

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/calibration/use_cases/" + language + "/calibrationMCMCFlowrate1D."
    + extension
    + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + bloc2[language] + "\n"
    + "```"
}}

The final part demonstrates how to display and analyse the results. The first elements to examine 
are the trace plot ({numref}`usecases_calibrationMCMCFlowrate1D_Tr`) and the acceptance ratio plot 
({numref}`usecases_calibrationMCMCFlowrate1D_Acc`). On these plots, you should check that the number 
of accepted iterations is sufficiently high (at least several hundred if the chains stabilise quickly 
— in our case, around 500), and that the converged acceptance ratio falls within a reasonable range 
(20–50% — here, it is close to 25%). When inspecting the trace, the chains should have converged 
around the same region (as they do here), and they should evolve rapidly, which indicates efficient 
exploration and low autocorrelation (also observed in our case). Finally, these plots help verify 
whether all chains behave stably and from which iteration they can be considered stable. This provides 
a first indication of a suitable burn-in value. In this example, the chains appear to have converged, 
and a burn-in value of 50 seems appropriate.

The burn-in size can then be defined and its consistency verified using the Gelman–Rubin statistic. In 
our case, a value of 1.00137 is reported in [](#use_cases_macro_calibration_mcmc_console) which is 
very close to 1 and confirms excellent convergence of the chains. Otherwise, a different burn-in value 
might have been more appropriate, the calculation could have been extended, or the MCMC algorithm 
settings adjusted.

The next step is to check for sample autocorrelation within the chains. The Effective Sample Size 
(ESS) provides a good indication of the lag to be used. In our case, the chains contain a reasonable 
number of independent samples (at least 257 each), and a lag of 1 is sufficient (see 
[](#use_cases_macro_calibration_mcmc_console)). Otherwise, the calculation could have been extended, 
or the MCMC algorithm settings adjusted (especially the standard deviation of the proposal 
distribution).

Two additional pieces of *a posteriori*
information are presented as plots: the residuals 
({numref}`usecases_calibrationMCMCFlowrate1D_Res`), which show the expected normal distribution 
behavior, as discussed in {{metho}} and the posterior distribution 
({numref}`usecases_calibrationMCMCFlowrate1D_Par`).

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/calibration/use_cases/" + language + "/calibrationMCMCFlowrate1D."
    + extension
    + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + bloc3[language] + "\n"
    + "```"
}}

(use_cases_macro_calibration_mcmc_console)=
## Console

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/build/uranie/doc/calibration/use_cases/" + language 
    + "/calibrationMCMCFlowrate1D_clean.log"
    + "\n"
    + ":name: usecases_calibrationMCMCFlowrate1D_Console\n"
    + ":language: none\n"
    + ":lines: " + console[language] + "\n"
    + "```"
}}

## Graphs

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/calibration/use_cases/" + language 
        + "/mcmc/calibrationMCMCFlowrate1D_Tr.png\n"
    ":align: center\n"
    ":name: usecases_calibrationMCMCFlowrate1D_Tr\n"
    + figure_scale + "\n"
    "\n"
    "Trace graph of the macro **\"calibrationMCMCFlowrate1D." + extension + "\"**\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/calibration/use_cases/" + language 
        + "/mcmc/calibrationMCMCFlowrate1D_Acc.png\n"
    ":align: center\n"
    ":name: usecases_calibrationMCMCFlowrate1D_Acc\n"
    + figure_scale + "\n"
    "\n"
    "Acceptation ratio graph of the macro  **\"calibrationMCMCFlowrate1D." + extension + "\"**\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/calibration/use_cases/" + language 
        + "/mcmc/calibrationMCMCFlowrate1D_Res.png\n"
    ":align: center\n"
    ":name: usecases_calibrationMCMCFlowrate1D_Res\n"
    + figure_scale + "\n"
    "\n"
    "Residuals graph of the macro **\"calibrationMCMCFlowrate1D." + extension + "\"**\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/calibration/use_cases/" + language 
        + "/mcmc/calibrationMCMCFlowrate1D_Par.png\n"
    ":align: center\n"
    ":name: usecases_calibrationMCMCFlowrate1D_Par\n"
    + figure_scale + "\n"
    "\n"
    "Parameter graph of the macro **\"calibrationMCMCFlowrate1D." + extension + "\"**\n"
    "```"
}}