Merge pull request #26 from Steriva/main

Code and paper update following comments from reviewer 2

Author: Steriva

README.md

@@ -17,7 +17,9 @@
 - [How to cite *pyforce*](#how-to-cite-pyforce)
   - [Selected works with *pyforce*](#selected-works-with-pyforce)
 - [Installation](#installation)
+- [Package Structure](#package-structure)
 - [Tutorials](#tutorials)
+  - [Demo results](#demo-results)
 - [Authors and contributions](#authors-and-contributions)
 - [Community Guidelines](#community-guidelines)
   - [Contribute to the Software](#contribute-to-the-software)
@@ -37,10 +39,10 @@ The techniques implemented here follow the same underlying idea expressed in the
 
 At the moment, the following techniques have been implemented:
 
-- **Proper Orthogonal Decomposition** with Projection and Interpolation for the Online Phase
-- **Generalised Empirical Interpolation Method**, either regularised with Tikhonov or not
-- **Parameterised-Background Data-Weak formulation**
-- an **Indirect Reconstruction** algorithm to reconstruct non-observable fields
+- **Proper Orthogonal Decomposition** with Projection and Interpolation for the Online Phase -> [`pyforce.offline.POD`](https://ermete-lab.github.io/ROSE-pyforce/_modules/pyforce/offline/pod.html#POD), [`pyforce.online.pod_projection`](https://ermete-lab.github.io/ROSE-pyforce/_modules/pyforce/online/pod_projection.html#PODproject), [`pyforce.online.pod_interpolation`](https://ermete-lab.github.io/ROSE-pyforce/_modules/pyforce/online/pod_interpolation.html#PODI)
+- **Generalised Empirical Interpolation Method**, either regularised with Tikhonov or not -> [`pyforce.offline.geim`](https://ermete-lab.github.io/ROSE-pyforce/_modules/pyforce/offline/geim.html#GEIM), [`pyforce.online.geim`](https://ermete-lab.github.io/ROSE-pyforce/_modules/pyforce/online/geim.html#GEIM), [`pyforce.online.tr_geim`](https://ermete-lab.github.io/ROSE-pyforce/_modules/pyforce/online/tr_geim.html#TRGEIM)
+- **Parameterised-Background Data-Weak formulation** -> [`pyforce.online.pbdw`](https://ermete-lab.github.io/ROSE-pyforce/_modules/pyforce/online/pbdw.html#PBDW)
+- an **Indirect Reconstruction** algorithm to reconstruct non-observable fields -> [`pyforce.online.indirect_recon`](https://ermete-lab.github.io/ROSE-pyforce/api/pyforce.online.html#module-pyforce.online.indirect_recon)
 
 This package is aimed to be a valuable tool for other researchers, engineers, and data scientists working in various fields, not only restricted in the Nuclear Engineering world.
 
@@ -104,12 +106,18 @@ create a conda environment using `environment.yml`
 cd ROSE-pyforce
 conda env create -f pyforce/environment.yml
 ```
-activate the environment and then install the package using `pip`
+activate the environment and then install the package using `pip` (be aware than on PyPI there exists another package named *pyforce*, so be sure to install it from the cloned repository)
 ```bash
 conda activate pyforce-env
-python -m pip install pyforce/
+cd pyforce/
+python -m pip install .
 ```
 
+## Package Structure
+The package **pyforce** comprises 3 subpackages: *offline*, *online* and *tools*. The first two collect the main functionalities, in particular the different DDROM techniques; whereas, the last includes importing and storing functions (from *dolfinx* directly or mapping from OpenFOAM), some backend classes for the snapshots and the calculation of integrals/norms. In the following, some figures are sketching how the different classes are connected to each other during the offline and online phases.
+
+More details on how the classes are connected to each other (both during the offline and online phases) can be found in the [docs](https://ermete-lab.github.io/ROSE-pyforce/theory.html#package-structure).
+
 ## Tutorials
 The *pyforce* package is tested on some tutorials available in the [docs](https://ermete-lab.github.io/ROSE-pyforce/tutorials.html), including fluid dynamics and neutronics problems.
 
@@ -121,6 +129,45 @@ The *pyforce* package is tested on some tutorials available in the [docs](https:
 
 The snapshots can be either generated by the user or be downloaded at the following link [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15705990.svg)](https://zenodo.org/records/15705990)
 
+### Demo results
+
+Two demo results are reported here for a quick overview of the package capabilities, for the POD with Interpolation and for the GEIM with Tikhonov Regularisation. More details can be found in the [docs](https://ermete-lab.github.io/ROSE-pyforce/tutorials.html).
+
+- **POD** with **Interpolation** on the Laminar Flow over Cylinder tutorial: in the following block, a code-block will be reported to show how to generate the POD basis from a set of train snapshots (offline phase) and how to perform the online phase and the state reconstruction
+```python
+# Offline Phase
+from pyforce.offline.pod import POD
+pod_off = POD(train_snaps : FunctionsList, var_name,  verbose = True)
+pod_off.compute_basis(train_snaps : FunctionsList, rank)
+
+...
+
+# Online Phase
+from pyforce.online.pod_interpolation import PODI
+podi = PODI(pod_modes: FunctionsList, coefficients_maps: list, var_name)
+reconstruction = podi.reconstruct(test_snaps: FunctionsList, test_params: list, basis_to_use: int)
+```
+<p align="center">
+  <img src="images/podi.png" alt="PODI" width="400"/>
+</p>
+
+- **GEIM** with **Tikhonov Regularisation** on the Multi-Group Neutron Diffusion tutorial: in the following block, a code-block will be reported to show how to generate the GEIM basis and sensors from a set of train snapshots (offline phase) and how to perform the online phase and the state reconstruction
+```python
+# Offline Phase
+from pyforce.offline.geim import GEIM
+geim_off = GEIM(mesh: dolfinx.mesh.Mesh, V: FunctionSpace, var_name, sensor_point_spread)
+geim_off.offline(train_snaps : FunctionsList, Max_Sensors: int, verbose = True)
+
+# Online Phase
+from pyforce.online.tr_geim import TRGEIM
+trgeim = TRGEIM(magic_functions: FunctionsList, magic_sensors: FunctionsList, mean_offline_beta_coeffs: np.ndarray, std_offline_beta_coeffs: np.ndarray, var_name)
+trgeim.reconstruct(test_snaps: FunctionsList, M_to_use, noise_value, reg_param = noise_value**2)
+```
+<p align="center">
+  <img src="images/geim_anl.png" alt="TR-GEIM" width="400"/>
+</p>
+
+
 ## Authors and contributions
 
 **pyforce** is currently developed and mantained at [Nuclear Reactors Group - ERMETE Lab](https://github.com/ERMETE-Lab) by

docs/Tutorials/02_MGDiffusion/02b_offline_GEIM.ipynb

@@ -48,13 +48,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [],
    "source": [
     "from neutronics import create_anl11a2_mesh\n",
     "\n",
-    "domain, _, _ = create_anl11a2_mesh(use_msh=True, save_mesh=False)\n",
+    "domain, _, _ = create_anl11a2_mesh(use_msh=False, save_mesh=False)\n",
     "\n",
     "fuel1_marker    = 1\n",
     "fuel2_marker    = 2\n",
@@ -67,6 +67,26 @@
     "clear_output()"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "dolfinx.mesh.Mesh"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "type(domain)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -565,7 +585,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "pyforce-old",
    "language": "python",
    "name": "python3"
   },
@@ -581,12 +601,7 @@
    "pygments_lexer": "ipython3",
    "version": "3.10.14"
   },
-  "orig_nbformat": 4,
-  "vscode": {
-   "interpreter": {
-    "hash": "e5b3af111de828d84cfea01c8e4cc990d7262e947155f31e208c22ad6b78199b"
-   }
-  }
+  "orig_nbformat": 4
  },
  "nbformat": 4,
  "nbformat_minor": 2

docs/installation.md

@@ -1,6 +1,6 @@
 # Installation notes
 
-**pyforce** has been tested on MacOS and Linux machines with **Python3.10**.
+**pyforce** has been tested on MacOS and Linux machines with **Python3.10**, using **conda** as package manager. There is no direct support for Windows machines, but it can work using WSL2.
 
 ## Dependencies
 The *pyforce* package requires the following dependencies:
@@ -43,7 +43,8 @@ conda env create -f pyforce/environment.yml
 activate the environment and then install the package using `pip`
 ```bash
 conda activate pyforce-env
-python -m pip install pyforce/
+cd pyforce/
+python -m pip install .
 ```
 
 If the previous procedure encounters any issues, you can adopt a step-by-step approach: start by creating a new conda environment
@@ -89,10 +90,10 @@ python -m pip install fluidfoam scikit-learn
 ```
 Once all the dependencies have been installed, *pyforce* can be installed using *pip*: clone the repository
 ```bash
-git clone https://github.com/ROSE-Polimi/pyforce.git
+git clone https://github.com/ERMETE-Lab/ROSE-pyforce.git
 ```
 Change directory to *ROSE-pyforce* and install using pip
 ```bash
-cd ROSE-pyforce
-python -m pip install pyforce/
+cd ROSE-pyforce/pyforce/
+python -m pip install .
 ```

docs/theory.md

@@ -1,6 +1,23 @@
 # Theory and package structure
 This section presents the main ideas behind Reduced Order Modelling (ROM) {cite:p}`Quarteroni2016, MadayChapter2020, Degen2020_conference`, focusing on data-driven paradigm of these techniques. Then, the structure of the package is presented showing how the different classes are connected to each other.
 
+The following table summarises the main acronyms used throughout the documentation.
+
+| Acronym | Full Name                                      | Brief Description |
+|--------|--------------------------------------------------|-------------------|
+| **DA**  | Data Assimilation                               | Methodology to combine model predictions with observational data to improve state estimates. |
+| **DDROM** | Data-Driven Reduced Order Model               | ROM built only from data without requiring explicit knowledge of the governing equations, including state estimation from sparse measurements. |
+| **FOM** | Full Order Model                                | High-fidelity model, typically a discretized PDE, used to generate snapshots for ROM construction. |
+| **GEIM** | Generalized Empirical Interpolation Method     | State estimation method able to reconstruct the state from measurements and place sensors in a greedy way. |
+| **IR** | Indirect Reconstruction                         | Technique to reconstruct non-observable fields from measurements of observable ones using ROM. |
+| **ODE** | Ordinary Differential Equation                   | Mathematical equations involving functions of a single variable and their derivatives. |
+| **PBDW** | Parametrized-Background Data-Weak formulation   | Data assimilation approach combining a background model with experimental measurements in a variational framework. |
+| **PDE** | Partial Differential Equation                    | Mathematical equations involving multivariable functions and their partial derivatives, governing many physical phenomena. |
+| **POD** | Proper Orthogonal Decomposition                  | Technique to extract dominant modes from data/snapshots for reduced modelling. |
+| **RB**  | Reduced Basis                                   | Set of basis functions derived from FOM snapshots to represent solutions in a low-dimensional space. |
+| **ROM** | Reduced Order Model                             | Low-dimensional surrogate model that approximates high-fidelity simulations. |
+| **SVD** | Singular Value Decomposition                    | Matrix factorization method used in POD to identify dominant spatial modes. |
+
 ## What is Reduced Order Modelling?
 In scientific literature, the expression Reduced Order Modelling is related to a set of techniques devoted to the search for an optimal coordinate system onto which some parametric solutions of Partial Differential Equations (PDEs) - typically called High-Fidelity (HF) or Full Order Model (FOM) - can be represented. These methods are very useful in multi-query and real-time scenarios, when quick and efficient solutions of models are required, e.g. optimization, uncertainty quantification and inverse problems {cite:p}`Guo_Veroy2021, Degen2022`. Recently, with the developments in data-driven modelling, a lot of interest in the combination of data and models has been raised. ROM offers new opportunities both to integrate the model with experimental data in real-time and to define methods of sensor positioning, by providing efficient tools to compress the prior knowledge about the system coming from the parametrized mathematical model into low-dimensional forms.
 
@@ -26,7 +43,7 @@ Data-Driven Reduced Order Modelling (DDROM) {cite:p}`RMP_2024, DDMOR_CFR` is a s
 
 The techniques implemented here follow the same underlying idea expressed in the Figure \ref{fig:darom}. They all share the typical offline/online paradigm of ROM techniques: the former is computationally expensive and it is performed only once, whereas the latter is cheap from the computational point of view and allows to have quick and reliable evaluations of the state of the system by merging background model knowledge and real evaluations of quantities of interest {cite:p}`MadayPBDW`.
 
-During the offline (also called training) phase, a *high-fidelity* or Full Order Model (FOM), usually parameterised partial differential equations, is solved several times to obtain a collections of snapshots $\mathbf{u}_{FOM}\in\mathbb{R}^{\mathcal{N}_h}$, given $\mathcal{N}_h$ the dimension of the spatial mesh, which are dependent on some parameters $\boldsymbol{\mu}_n$; then, these snapshots are used to generate a reduced representation through a set of basis functions $\{\psi_n(\mathbf{x})\}$ of size $N$, in this way the degrees of freedom are decreased from $\mathcal{N}_h$ to $N$, provided that $\mathcal{N}_h>>N$. This allows for an approximation of any solution of the FOM as follows
+During the offline (also called training) phase, a *high-fidelity* or Full Order Model (FOM), usually parameterised partial differential equations, is solved several times to obtain a collection of snapshots $\mathbf{u}_{FOM}\in\mathbb{R}^{\mathcal{N}_h}$, given $\mathcal{N}_h$ the dimension of the spatial mesh, which are dependent on some parameters $\boldsymbol{\mu}_n$; then, these snapshots are used to generate a reduced representation through a set of basis functions $\{\psi_n(\mathbf{x})\}$ of size $N$, in this way the degrees of freedom are decreased from $\mathcal{N}_h$ to $N$, provided that $\mathcal{N}_h>>N$. This allows for an approximation of any solution of the FOM as follows
 
 ```{math}
 u_{FOM}(\mathbf{x} ; \boldsymbol{\mu}) \simeq \sum_{n=1}^N\alpha_n(\boldsymbol{\mu})\cdot \psi_n(\mathbf{x})
@@ -41,7 +58,7 @@ The online phase aims to obtain a quick and reliable way a solution of the FOM f
 The package **pyforce** comprises 3 subpackages: *offline*, *online* and *tools*. The first two collect the main functionalities, in particular the different DDROM techniques; whereas, the last includes importing and storing functions (from *dolfinx* directly or mapping from OpenFOAM), some backend classes for the snapshots and the calculation of integrals/norms. In the following, some figures are sketching how the different classes are connected to each other during the offline and online phases.
 
 ### Offline Phase
-Once the snapshots have been generated and collected into the class `FunctionsList`, the aims of this phase consists in generating a proper reduced representation and obtain an optimal sensors configuration.
+Once the snapshots have been generated and collected into the class `FunctionsList`, the aim of this phase consists in generating a proper reduced representation and obtain an optimal sensors configuration.
 
 ![Offline Phase](images/offline_classes.svg)