NREL · malihass · Jan 15, 2025 · Dec 16, 2024 · Dec 16, 2024 · Dec 16, 2024
diff --git a/.gitignore b/.gitignore
@@ -135,3 +135,4 @@ dmypy.json
 .DS_Store
 *.stl
 
+*.swp
diff --git a/bird/preprocess/inhomogeneousBC/constant/.phaseProperties.swp b/bird/preprocess/inhomogeneousBC/constant/.phaseProperties.swp
diff --git a/assets/3dsparger.png → docs/assets/3dsparger.png b/assets/3dsparger.png → docs/assets/3dsparger.png
diff --git a/assets/calibration/corner_b_calsigm.png → docs/assets/calibration/corner_b_calsigm.png b/assets/calibration/corner_b_calsigm.png → docs/assets/calibration/corner_b_calsigm.png
diff --git a/assets/calibration/corner_b_optsigm.png → docs/assets/calibration/corner_b_optsigm.png b/assets/calibration/corner_b_optsigm.png → docs/assets/calibration/corner_b_optsigm.png
diff --git a/assets/calibration/corner_bb_calsigm.png → .../assets/calibration/corner_bb_calsigm.png b/assets/calibration/corner_bb_calsigm.png → .../assets/calibration/corner_bb_calsigm.png
diff --git a/assets/calibration/corner_bb_optsigm.png → .../assets/calibration/corner_bb_optsigm.png b/assets/calibration/corner_bb_optsigm.png → .../assets/calibration/corner_bb_optsigm.png
diff --git a/...tutorial/calibration/assets/Loss_surr.png → ...assets/calibration/tutorial/Loss_surr.png b/...tutorial/calibration/assets/Loss_surr.png → ...assets/calibration/tutorial/Loss_surr.png
diff --git a/...ration/assets/Surr_cal_2.0_5.0_corner.png → ...tion/tutorial/Surr_cal_2.0_5.0_corner.png b/...ration/assets/Surr_cal_2.0_5.0_corner.png → ...tion/tutorial/Surr_cal_2.0_5.0_corner.png
diff --git a/...ibration/assets/Surr_cal_2.0_5.0_prop.png → ...ration/tutorial/Surr_cal_2.0_5.0_prop.png b/...ibration/assets/Surr_cal_2.0_5.0_prop.png → ...ration/tutorial/Surr_cal_2.0_5.0_prop.png
diff --git a/...ration/assets/Surr_cal_5.0_5.0_corner.png → ...tion/tutorial/Surr_cal_5.0_5.0_corner.png b/...ration/assets/Surr_cal_5.0_5.0_corner.png → ...tion/tutorial/Surr_cal_5.0_5.0_corner.png
diff --git a/...ibration/assets/Surr_cal_5.0_5.0_prop.png → ...ration/tutorial/Surr_cal_5.0_5.0_prop.png b/...ibration/assets/Surr_cal_5.0_5.0_prop.png → ...ration/tutorial/Surr_cal_5.0_5.0_prop.png
diff --git a/...ration/assets/Surr_opt_2.0_5.0_corner.png → ...tion/tutorial/Surr_opt_2.0_5.0_corner.png b/...ration/assets/Surr_opt_2.0_5.0_corner.png → ...tion/tutorial/Surr_opt_2.0_5.0_corner.png
diff --git a/...ibration/assets/Surr_opt_2.0_5.0_prop.png → ...ration/tutorial/Surr_opt_2.0_5.0_prop.png b/...ibration/assets/Surr_opt_2.0_5.0_prop.png → ...ration/tutorial/Surr_opt_2.0_5.0_prop.png
diff --git a/...ration/assets/Surr_opt_5.0_5.0_corner.png → ...tion/tutorial/Surr_opt_5.0_5.0_corner.png b/...ration/assets/Surr_opt_5.0_5.0_corner.png → ...tion/tutorial/Surr_opt_5.0_5.0_corner.png
diff --git a/...ibration/assets/Surr_opt_5.0_5.0_prop.png → ...ration/tutorial/Surr_opt_5.0_5.0_prop.png b/...ibration/assets/Surr_opt_5.0_5.0_prop.png → ...ration/tutorial/Surr_opt_5.0_5.0_prop.png
diff --git a/...ration/assets/True_cal_2.0_5.0_corner.png → ...tion/tutorial/True_cal_2.0_5.0_corner.png b/...ration/assets/True_cal_2.0_5.0_corner.png → ...tion/tutorial/True_cal_2.0_5.0_corner.png
diff --git a/...ibration/assets/True_cal_2.0_5.0_prop.png → ...ration/tutorial/True_cal_2.0_5.0_prop.png b/...ibration/assets/True_cal_2.0_5.0_prop.png → ...ration/tutorial/True_cal_2.0_5.0_prop.png
diff --git a/...ration/assets/True_cal_5.0_5.0_corner.png → ...tion/tutorial/True_cal_5.0_5.0_corner.png b/...ration/assets/True_cal_5.0_5.0_corner.png → ...tion/tutorial/True_cal_5.0_5.0_corner.png
diff --git a/...ibration/assets/True_cal_5.0_5.0_prop.png → ...ration/tutorial/True_cal_5.0_5.0_prop.png b/...ibration/assets/True_cal_5.0_5.0_prop.png → ...ration/tutorial/True_cal_5.0_5.0_prop.png
diff --git a/...ration/assets/True_opt_2.0_5.0_corner.png → ...tion/tutorial/True_opt_2.0_5.0_corner.png b/...ration/assets/True_opt_2.0_5.0_corner.png → ...tion/tutorial/True_opt_2.0_5.0_corner.png
diff --git a/...ibration/assets/True_opt_2.0_5.0_prop.png → ...ration/tutorial/True_opt_2.0_5.0_prop.png b/...ibration/assets/True_opt_2.0_5.0_prop.png → ...ration/tutorial/True_opt_2.0_5.0_prop.png
diff --git a/...ration/assets/True_opt_5.0_5.0_corner.png → ...tion/tutorial/True_opt_5.0_5.0_corner.png b/...ration/assets/True_opt_5.0_5.0_corner.png → ...tion/tutorial/True_opt_5.0_5.0_corner.png
diff --git a/...ibration/assets/True_opt_5.0_5.0_prop.png → ...ration/tutorial/True_opt_5.0_5.0_prop.png b/...ibration/assets/True_opt_5.0_5.0_prop.png → ...ration/tutorial/True_opt_5.0_5.0_prop.png
diff --git a/...tutorial/calibration/assets/test_surr.png → ...assets/calibration/tutorial/test_surr.png b/...tutorial/calibration/assets/test_surr.png → ...assets/calibration/tutorial/test_surr.png
diff --git a/assets/co2g_cond_mean.png → docs/assets/co2g_cond_mean.png b/assets/co2g_cond_mean.png → docs/assets/co2g_cond_mean.png
diff --git a/assets/early_det.png → docs/assets/early_det.png b/assets/early_det.png → docs/assets/early_det.png
diff --git a/assets/early_uq.png → docs/assets/early_uq.png b/assets/early_uq.png → docs/assets/early_uq.png
diff --git a/assets/gh_cond_mean.png → docs/assets/gh_cond_mean.png b/assets/gh_cond_mean.png → docs/assets/gh_cond_mean.png
diff --git a/assets/loop_react.png → docs/assets/loop_react.png b/assets/loop_react.png → docs/assets/loop_react.png
diff --git a/assets/schematic.png → docs/assets/schematic.png b/assets/schematic.png → docs/assets/schematic.png
diff --git a/assets/schematicSpargerInlet.png → docs/assets/schematicSpargerInlet.png b/assets/schematicSpargerInlet.png → docs/assets/schematicSpargerInlet.png
diff --git a/assets/schematicSpargerWalls.png → docs/assets/schematicSpargerWalls.png b/assets/schematicSpargerWalls.png → docs/assets/schematicSpargerWalls.png
diff --git a/assets/simpleOutput.png → docs/assets/simpleOutput.png b/assets/simpleOutput.png → docs/assets/simpleOutput.png
diff --git a/assets/stirred_tank.png → docs/assets/stirred_tank.png b/assets/stirred_tank.png → docs/assets/stirred_tank.png
diff --git a/assets/validation/co2.png → docs/assets/validation/co2.png b/assets/validation/co2.png → docs/assets/validation/co2.png
diff --git a/assets/validation/conv.png → docs/assets/validation/conv.png b/assets/validation/conv.png → docs/assets/validation/conv.png
diff --git a/assets/validation/gh.png → docs/assets/validation/gh.png b/assets/validation/gh.png → docs/assets/validation/gh.png
diff --git a/docs/source/bubbleColumn.rst b/docs/source/bubbleColumn.rst
@@ -0,0 +1,14 @@
+Bubble column
+=====
+
+This tutorial demonstrates how to run a bubble column reactor case
+
+Running the tutorial
+------------
+
+
+
+
+
+
+
diff --git a/docs/source/calibration.rst b/docs/source/calibration.rst
@@ -0,0 +1,242 @@
+Parameter calibration
+=====
+
+This tutorial demonstrates how to conduct the calibration with and without a surrogate forward model
+
+Running the tutorial
+------------
+We assume that bird is installed within an environment called ``bird`` (see either the :ref:`Installation section for developers<installation_dev>` or the :ref:`Installation section for users<installation_users>`)
+
+You will need to install additional dependencies
+
+.. code-block:: console
+
+   conda activate bird
+   BIRD_DIR = `python -c "import bird; print(bird.BIRD_DIR)"`
+   cd ${BIRD_DIR}/../
+   pip install .[calibration]
+
+The calibration tutorial is located at ``${BIRD_DIR}/../tutorial_cases/calibration/``
+
+Calibration Objective
+------------
+
+The PDF of a Beta(alpha,beta) distribution is observed.
+Within the context of bioreactors, one can consider this PDF to be a measured bubble size distribution (BSD)
+
+A separate dummy numerical model is available and predicts BSD as normal distributions N(mu, sigma). The input parameter of the numerical models are mu and sigma. The objective of the modeler is to find mu and sigma such that the predicted BSD matches the observed BSD
+
+We assume that the numerical model is expensive and instead of using the expensive numerical model for the forward model used in the calibration, one would like to use a cheaper surrogate model. Here the surrogate model is a neural network.
+
+
+Building the surrogate
+------------
+
+The class ``Param_NN`` available in BiRD allows to create a parametric surrogate. Here, the input of the surrogate are the parameters ``mu`` and ``sigma``, and the variable ``x`` that parameterize the PDF.
+
+Constructing such a surrogate is not computationally useful here since the forward simulation is cheap. This is only for illustrative purposes!
+
+Generate dataset and train neural net surrogate with ``python tut_surrogate.py``.
+The following plots should be generated. The first one shows the training and testing loss convergence. The second one shows examples of the surrogate accuracy on unseen data.
+
+
+.. container:: figures-surr-train
+
+   .. figure:: ../assets/calibration/tutorial/Loss_surr.png
+      :width: 30%
+      :align: center
+      :alt: Loss history
+
+   .. figure:: ../assets/calibration/tutorial/test_surr.png
+      :width: 90%
+      :align: center
+      :alt: Test samples
+
+
+Calibration with optimized likelihood uncertainty
+------------
+
+For the calibration, we can use the true function or the surrogate model. The objective PDF is assumed to be noiseless. Even though the observation is noiseless, an uncertainty is computed to account for the missing physics.
+The likelihood uncertainty that represents the missing physics is optimized to ensure an uncertainty band overlap
+
+Calibrate without a surrogate for ``alpha=5, beta=5``
+
+
+.. code-block:: console
+
+   python tut_calibration.py --alpha 5 --beta 5
+
+
+.. container:: figures-cal-True-5-5
+
+   .. figure:: ../assets/calibration/tutorial/True_opt_5.0_5.0_prop.png
+      :width: 50%
+      :align: center
+      :alt: Calibrated prediction with the true forward model
+
+   .. figure:: ../assets/calibration/tutorial/True_opt_5.0_5.0_corner.png
+      :width: 50%
+      :align: center
+      :alt: Parameter PDF obtained with the true forward model
+
+
+Calibrate with a surrogate for ``alpha=5, beta=5``
+
+.. code-block:: console
+
+   python tut_calibration.py -useNN --alpha 5 --beta 5
+
+
+
+.. container:: figures-cal-Surr-5-5
+
+   .. figure:: ../assets/calibration/tutorial/Surr_opt_5.0_5.0_prop.png
+      :width: 50%
+      :align: center
+      :alt: Calibrated prediction with the surrogate forward model
+
+   .. figure:: ../assets/calibration/tutorial/Surr_opt_5.0_5.0_corner.png
+      :width: 50%
+      :align: center
+      :alt: Parameter PDF obtained with the surrogate forward model
+
+
+Calibrate without a surrogate for ``alpha=2, beta=5``
+
+
+.. code-block:: console
+
+   python tut_calibration.py --alpha 2 --beta 5
+
+
+.. container:: figures-cal-True-2-5
+
+   .. figure:: ../assets/calibration/tutorial/True_opt_2.0_5.0_prop.png
+      :width: 50%
+      :align: center
+      :alt: Calibrated prediction with the true forward model
+
+   .. figure:: ../assets/calibration/tutorial/True_opt_2.0_5.0_corner.png
+      :width: 50%
+      :align: center
+      :alt: Parameter PDF obtained with the true forward model
+
+
+Calibrate with a surrogate for ``alpha=2, beta=5``
+
+.. code-block:: console
+
+   python tut_calibration.py -useNN --alpha 2 --beta 5
+
+
+
+.. container:: figures-cal-True-2-5
+
+   .. figure:: ../assets/calibration/tutorial/Surr_opt_2.0_5.0_prop.png
+      :width: 50%
+      :align: center
+      :alt: Calibrated prediction with the surrogate forward model
+
+   .. figure:: ../assets/calibration/tutorial/Surr_opt_2.0_5.0_corner.png
+      :width: 50%
+      :align: center
+      :alt: Parameter PDF obtained with the surrogate forward model
+
+
+Clearly, the amount of missing physics vary depending on the observations.
+
+Using surrogate gives similar predictions as when not using a surrogate. But the surrogate was constructed with 200 forward simulations. In the case where forward simulations are expensive, the surrogate modeling approach is significantly faster.
+
+Calibration with calibrated likelihood uncertainty
+------------
+
+The same suite can be done by calibrating the likelihood uncertainty in lieu of optimizing it (with a bissection search). This has the advantage of rapid calibration since only one calibration is needed. Here the uncertainty minimizes the negative log likelihood.
+
+Calibrate without a surrogate for ``alpha=5, beta=5``
+
+
+.. code-block:: console
+
+   python tut_calibration.py --alpha 5 --beta 5 -cal_err
+
+
+.. container:: figures-cal-calerr-True-5-5
+
+   .. figure:: ../assets/calibration/tutorial/True_cal_5.0_5.0_prop.png
+      :width: 50%
+      :align: center
+      :alt: Calibrated prediction with the true forward model
+
+   .. figure:: ../assets/calibration/tutorial/True_cal_5.0_5.0_corner.png
+      :width: 50%
+      :align: center
+      :alt: Parameter PDF obtained with the true forward model
+
+
+Calibrate with a surrogate for ``alpha=5, beta=5``
+
+.. code-block:: console
+
+   python tut_calibration.py -useNN --alpha 5 --beta 5 -cal_err
+
+
+
+.. container:: figures-cal-calerr-Surr-5-5
+
+   .. figure:: ../assets/calibration/tutorial/Surr_cal_5.0_5.0_prop.png
+      :width: 50%
+      :align: center
+      :alt: Calibrated prediction with the surrogate forward model
+
+   .. figure:: ../assets/calibration/tutorial/Surr_cal_5.0_5.0_corner.png
+      :width: 50%
+      :align: center
+      :alt: Parameter PDF obtained with the surrogate forward model
+
+
+Calibrate without a surrogate for ``alpha=2, beta=5``
+
+
+.. code-block:: console
+
+   python tut_calibration.py --alpha 2 --beta 5 -cal_err
+
+
+.. container:: figures-cal-calerr-True-2-5
+
+   .. figure:: ../assets/calibration/tutorial/True_cal_2.0_5.0_prop.png
+      :width: 50%
+      :align: center
+      :alt: Calibrated prediction with the true forward model
+
+   .. figure:: ../assets/calibration/tutorial/True_cal_2.0_5.0_corner.png
+      :width: 50%
+      :align: center
+      :alt: Parameter PDF obtained with the true forward model
+
+
+Calibrate with a surrogate for ``alpha=2, beta=5``
+
+.. code-block:: console
+
+   python tut_calibration.py -useNN --alpha 2 --beta 5 -cal_err
+
+
+
+.. container:: figures-cal-calerr-True-2-5
+
+   .. figure:: ../assets/calibration/tutorial/Surr_cal_2.0_5.0_prop.png
+      :width: 50%
+      :align: center
+      :alt: Calibrated prediction with the surrogate forward model
+
+   .. figure:: ../assets/calibration/tutorial/Surr_cal_2.0_5.0_corner.png
+      :width: 50%
+      :align: center
+      :alt: Parameter PDF obtained with the surrogate forward model
+
+
+
+
+
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -26,6 +26,7 @@ We also provide a solver ``birdmultiphaseEulerFoam`` that contains custom models
    meshing
    preprocess
    postprocess
+   tutorials
    contribute
    references
    acknowledgments
diff --git a/docs/source/meshing.rst b/docs/source/meshing.rst
@@ -29,11 +29,11 @@ Visualize mesh in Paraview
 
 .. _fig:stirredtank:
 
-.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/stirred_tank.png
+.. figure:: ../assets/stirred_tank.png
      :width: 70%
      :align: center
      :name: fig-str
-     :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/stirred_tank.png
+     :target: ../assets/stirred_tank.png
      :alt: Stirred-tank reactor
 
 Related tutorial
@@ -72,11 +72,11 @@ Visualize mesh in Paraview
 
 .. _fig:sidesparger:
 
-.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/3dsparger.png
+.. figure:: ../assets/3dsparger.png
      :width: 50%
      :align: center
      :name: fig-sidesparger
-     :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/3dsparger.png
+     :target: ../assets/3dsparger.png
      :alt: Reactor with a side sparger
 
 How to change the dimensions or mesh refinement?
@@ -92,11 +92,11 @@ How to change the arrangement of concentric cylinders?
 The block topology is controlled by the ``topology.json``
 We recomment always working with a schematic. Here is the schematic for this case
 
-.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematic.png
+.. figure:: ../assets/schematic.png
      :width: 50%
      :align: center
      :name: fig-schematic
-     :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematic.png
+     :target: ../assets/schematic.png
      :alt: Side sparger schematic
 
 
@@ -126,11 +126,11 @@ Boundaries are defined with three types, ``top``, ``bottom`` and ``lateral``
 
 In the case of sparger walls shown below with the red lines
 
-.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerWalls.png
+.. figure:: ../assets/schematicSpargerWalls.png
      :width: 50%
      :align: center
      :name: fig-schematicwalls
-     :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerWalls.png
+     :target: ../assets/schematicSpargerWalls.png
      :alt: Wall side sparger schematic
 
 
@@ -148,11 +148,11 @@ the boundary is defined in the ``topology.json`` as
 
 For the side sparger, the inlet is shown below with the red line
 
-.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerInlet.png
+.. figure:: ../assets/schematicSpargerInlet.png
      :width: 50%
      :align: center
      :name: fig-schematicinlet
-     :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerInlet.png
+     :target: ../assets/schematicSpargerInlet.png
      :alt: Inlet side sparger schematic
 
 the boundary is defined in the ``topology.json`` as
@@ -198,11 +198,11 @@ Visualize mesh in Paraview
 
 .. _fig:loop_reactor:
 
-.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/loop_react.png
+.. figure:: ../assets/loop_react.png
      :width: 80%
      :align: center
      :name: fig-loopreactor
-     :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/loop_react.png
+     :target: ../assets/loop_react.png
      :alt: Loop reactor
 
 

diff --git a/docs/source/postprocess.rst b/docs/source/postprocess.rst
@@ -17,12 +17,12 @@ Generates
 
 .. container:: figures-early-pred
 
-   .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/early_det.png
+   .. figure:: ../assets/early_det.png
       :width: 70%
       :align: center
       :alt: Determinisitc early prediction
 
-   .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/early_uq.png
+   .. figure:: ../assets/early_uq.png
       :width: 70%
       :align: center
       :alt: Uncertainty-aware early prediction     
@@ -39,12 +39,12 @@ Generates (among others)
 
 .. container:: figures-cond-mean
 
-   .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/gh_cond_mean.png
+   .. figure:: ../assets/gh_cond_mean.png
       :width: 70%
       :align: center
       :alt: Height-conditional gas holdup
 
-   .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/co2g_cond_mean.png
+   .. figure:: ../assets/co2g_cond_mean.png
       :width: 70%
       :align: center
       :alt: Height-conditional CO2 gas fraction

diff --git a/docs/source/preprocess.rst b/docs/source/preprocess.rst
@@ -18,11 +18,11 @@ The verbose flag (``-v``) generates a plot of the stl mesh
 
 .. _fig:stl_patch:
 
-.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/simpleOutput.png
+.. figure:: ../assets/simpleOutput.png
      :width: 70%
      :align: center
      :name: fig-stl-patch
-     :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/simpleOutput.png
+     :target: ../assets/simpleOutput.png
      :alt: STL patch
 
 How to change the set of shapes in the boundary patch?