icarus-thermal 0.1.0__tar.gz

icarus_thermal-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Raymond Twum-Barima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

icarus_thermal-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: icarus-thermal
+Version: 0.1.0
+Summary: Icarus: data-driven heat flux prediction from infrared thermography using POD, DMD, and machine learning
+Author: Raymond Twum-Barima
+License: MIT
+Project-URL: Homepage, https://github.com/twumbarimaraymond1-coder/icarus
+Project-URL: Documentation, https://icarus.readthedocs.io
+Project-URL: Issues, https://github.com/twumbarimaraymond1-coder/icarus/issues
+Keywords: heat transfer,boiling,POD,DMD,machine learning,infrared thermography
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: optuna>=3.3
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: h5py>=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Dynamic: license-file
+
+# icarus
+
+**Data-driven heat flux prediction from infrared thermography.**
+
+`icarus` provides a full pipeline from raw IR camera data to trained
+heat flux prediction models using Proper Orthogonal Decomposition (POD),
+Dynamic Mode Decomposition (DMD), and artificial neural networks.
+
+It implements the methodology from:
+
+> *Investigating the efficacy of data-driven techniques and machine learning
+> algorithms to predict heat transfer characteristics* (Twum-Barima, 2025)
+
+The best-performing approach (Model C: POD modal mapping) achieved **R² = 0.729**
+on a 17M-sample flow boiling dataset — a 69 % improvement over the linear baseline.
+
+---
+
+## Installation
+
+```bash
+pip install icarus
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/yourusername/icarus
+cd icarus
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.9, NumPy, SciPy, scikit-learn, Optuna, Matplotlib
+
+---
+
+## Quickstart
+
+```python
+import icarus as tf
+
+# Load your dataset (.mat, .h5, .npz supported)
+data = tf.data.loader.load(
+    "experiment.mat",
+    temperature_key="T",
+    heatflux_key="qL2",
+)
+
+# Or load from numpy arrays directly
+import numpy as np
+data = tf.data.loader.from_arrays(T, q, dt=2.5e-4)
+
+# Run the full pipeline (POD modal strategy, best performance)
+pipeline = tf.Pipeline(
+    strategy="modal",   # "raw" | "gradient" | "modal"
+    n_pod_modes=5,
+    spatial_crop=5,
+    trim_frames=43,
+    optimise_hyperparams=True,
+    n_trials=30,
+)
+pipeline.fit(data)
+
+# Evaluate
+metrics = pipeline.evaluate()
+# [test]  R² = 0.7293  RMSE = 25,959 W/m²  MAE = 20,656 W/m²
+
+# Predict on new data
+q_predicted = pipeline.predict(T_new)   # shape [ny, nx, nt]
+```
+
+---
+
+## Three model strategies
+
+| Strategy | Features | Notes |
+|----------|----------|-------|
+| `"raw"` (Model A) | Temperature only | Baseline |
+| `"gradient"` (Model B) | T + dT/dt + dT/dx + dT/dy | Modest improvement |
+| `"modal"` (Model C) | POD modal contributions | **Best: R² = 0.729** |
+
+The modal strategy works by:
+1. Decomposing the temperature field into dominant POD modes
+2. Learning a mapping from temperature modal coefficients → heat flux modal coefficients
+3. Reconstructing the full heat flux field from the predicted coefficients
+
+---
+
+## Individual components
+
+You can also use the modules independently:
+
+```python
+from icarus.decomposition.pod import POD
+from icarus.data.preprocessor import Preprocessor
+
+# Preprocessing
+pre = Preprocessor()
+out = pre.fit_transform(data)
+X_c = Preprocessor.to_matrix(out["T_c"])   # [n_pix, nt]
+
+# POD
+pod = POD(n_modes=10)
+pod.fit(X_c)
+print(f"First 5 modes capture {pod.cumulative_energy_[4]:.1%} of variance")
+
+# Modal contributions
+contribs = pod.modal_contributions(X_c)    # [n_pix, nt, n_modes]
+
+# Visualisation
+from icarus.visualisation.plots import plot_pod_modes, plot_cumulative_energy
+ny, nx = out["T"].shape[:2]
+plot_cumulative_energy(pod)
+plot_pod_modes(pod, ny=ny, nx=nx, n_modes=5)
+```
+
+```python
+from icarus.decomposition.dmd import DMD
+
+# DMD forecasting
+dmd = DMD(energy_threshold=0.99, dt=2.5e-4)
+dmd.fit(X_c_train)
+X_forecast = dmd.forecast_from(X_c_train[:, -1], n_steps=1200)
+```
+
+---
+
+## Visualisation
+
+```python
+from icarus.visualisation.plots import (
+    plot_field,
+    plot_pod_modes,
+    plot_cumulative_energy,
+    plot_scatter,
+    plot_model_summary,
+)
+
+# Single field
+plot_field(q[:, :, 100], title="Heat flux at t=100")
+
+# Full model evaluation summary (6-panel figure)
+plot_model_summary(
+    q_true_field, q_pred_field,
+    y_true_flat, y_pred_flat,
+    metrics_train, metrics_test,
+    r2_t=r2_t, rmse_t=rmse_t,
+    model_name="Model C — POD Modal",
+)
+```
+
+---
+
+## Running tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## Project structure
+
+```
+icarus/
+├── data/
+│   ├── loader.py          # .mat, .h5, .npz, numpy array loading
+│   └── preprocessor.py    # cropping, mean-centering, reshaping
+├── decomposition/
+│   ├── pod.py             # POD via SVD
+│   └── dmd.py             # DMD forecasting
+├── features/
+│   └── engineer.py        # gradient and modal feature construction
+├── models/
+│   └── neural.py          # MLP with Bayesian optimisation
+├── metrics/
+│   └── evaluation.py      # R², RMSE, MAE
+├── visualisation/
+│   └── plots.py           # spatial fields, modes, diagnostics
+└── pipeline/
+    └── runner.py          # end-to-end Pipeline
+```
+
+---
+
+## Known limitations
+
+- Experimental datasets are not included in this repository.
+- The reported Model C R² = 0.729 is dataset-specific and should be revalidated on independent datasets before being cited as a general result.
+- The default ANN search space (`"medium"`) is designed for moderate-sized datasets with 5 POD modes. Larger mode counts or datasets may require `hyperparam_search_space="large"` and more Optuna trials.
+- Current models use scikit-learn MLPs. Future versions may include PyTorch models for larger-scale training and GPU acceleration.
+- DMD forecasting accuracy degrades over longer horizons — it is suited to short-horizon prediction only.
+
+## Contributing
+
+Contributions welcome — particularly additional datasets, fluid-specific
+pre-trained models, and improved DMD variants. See `CONTRIBUTING.md`.
+
+## Licence
+
+MIT

icarus_thermal-0.1.0/README.md

@@ -0,0 +1,201 @@
+# icarus
+
+**Data-driven heat flux prediction from infrared thermography.**
+
+`icarus` provides a full pipeline from raw IR camera data to trained
+heat flux prediction models using Proper Orthogonal Decomposition (POD),
+Dynamic Mode Decomposition (DMD), and artificial neural networks.
+
+It implements the methodology from:
+
+> *Investigating the efficacy of data-driven techniques and machine learning
+> algorithms to predict heat transfer characteristics* (Twum-Barima, 2025)
+
+The best-performing approach (Model C: POD modal mapping) achieved **R² = 0.729**
+on a 17M-sample flow boiling dataset — a 69 % improvement over the linear baseline.
+
+---
+
+## Installation
+
+```bash
+pip install icarus
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/yourusername/icarus
+cd icarus
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.9, NumPy, SciPy, scikit-learn, Optuna, Matplotlib
+
+---
+
+## Quickstart
+
+```python
+import icarus as tf
+
+# Load your dataset (.mat, .h5, .npz supported)
+data = tf.data.loader.load(
+    "experiment.mat",
+    temperature_key="T",
+    heatflux_key="qL2",
+)
+
+# Or load from numpy arrays directly
+import numpy as np
+data = tf.data.loader.from_arrays(T, q, dt=2.5e-4)
+
+# Run the full pipeline (POD modal strategy, best performance)
+pipeline = tf.Pipeline(
+    strategy="modal",   # "raw" | "gradient" | "modal"
+    n_pod_modes=5,
+    spatial_crop=5,
+    trim_frames=43,
+    optimise_hyperparams=True,
+    n_trials=30,
+)
+pipeline.fit(data)
+
+# Evaluate
+metrics = pipeline.evaluate()
+# [test]  R² = 0.7293  RMSE = 25,959 W/m²  MAE = 20,656 W/m²
+
+# Predict on new data
+q_predicted = pipeline.predict(T_new)   # shape [ny, nx, nt]
+```
+
+---
+
+## Three model strategies
+
+| Strategy | Features | Notes |
+|----------|----------|-------|
+| `"raw"` (Model A) | Temperature only | Baseline |
+| `"gradient"` (Model B) | T + dT/dt + dT/dx + dT/dy | Modest improvement |
+| `"modal"` (Model C) | POD modal contributions | **Best: R² = 0.729** |
+
+The modal strategy works by:
+1. Decomposing the temperature field into dominant POD modes
+2. Learning a mapping from temperature modal coefficients → heat flux modal coefficients
+3. Reconstructing the full heat flux field from the predicted coefficients
+
+---
+
+## Individual components
+
+You can also use the modules independently:
+
+```python
+from icarus.decomposition.pod import POD
+from icarus.data.preprocessor import Preprocessor
+
+# Preprocessing
+pre = Preprocessor()
+out = pre.fit_transform(data)
+X_c = Preprocessor.to_matrix(out["T_c"])   # [n_pix, nt]
+
+# POD
+pod = POD(n_modes=10)
+pod.fit(X_c)
+print(f"First 5 modes capture {pod.cumulative_energy_[4]:.1%} of variance")
+
+# Modal contributions
+contribs = pod.modal_contributions(X_c)    # [n_pix, nt, n_modes]
+
+# Visualisation
+from icarus.visualisation.plots import plot_pod_modes, plot_cumulative_energy
+ny, nx = out["T"].shape[:2]
+plot_cumulative_energy(pod)
+plot_pod_modes(pod, ny=ny, nx=nx, n_modes=5)
+```
+
+```python
+from icarus.decomposition.dmd import DMD
+
+# DMD forecasting
+dmd = DMD(energy_threshold=0.99, dt=2.5e-4)
+dmd.fit(X_c_train)
+X_forecast = dmd.forecast_from(X_c_train[:, -1], n_steps=1200)
+```
+
+---
+
+## Visualisation
+
+```python
+from icarus.visualisation.plots import (
+    plot_field,
+    plot_pod_modes,
+    plot_cumulative_energy,
+    plot_scatter,
+    plot_model_summary,
+)
+
+# Single field
+plot_field(q[:, :, 100], title="Heat flux at t=100")
+
+# Full model evaluation summary (6-panel figure)
+plot_model_summary(
+    q_true_field, q_pred_field,
+    y_true_flat, y_pred_flat,
+    metrics_train, metrics_test,
+    r2_t=r2_t, rmse_t=rmse_t,
+    model_name="Model C — POD Modal",
+)
+```
+
+---
+
+## Running tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## Project structure
+
+```
+icarus/
+├── data/
+│   ├── loader.py          # .mat, .h5, .npz, numpy array loading
+│   └── preprocessor.py    # cropping, mean-centering, reshaping
+├── decomposition/
+│   ├── pod.py             # POD via SVD
+│   └── dmd.py             # DMD forecasting
+├── features/
+│   └── engineer.py        # gradient and modal feature construction
+├── models/
+│   └── neural.py          # MLP with Bayesian optimisation
+├── metrics/
+│   └── evaluation.py      # R², RMSE, MAE
+├── visualisation/
+│   └── plots.py           # spatial fields, modes, diagnostics
+└── pipeline/
+    └── runner.py          # end-to-end Pipeline
+```
+
+---
+
+## Known limitations
+
+- Experimental datasets are not included in this repository.
+- The reported Model C R² = 0.729 is dataset-specific and should be revalidated on independent datasets before being cited as a general result.
+- The default ANN search space (`"medium"`) is designed for moderate-sized datasets with 5 POD modes. Larger mode counts or datasets may require `hyperparam_search_space="large"` and more Optuna trials.
+- Current models use scikit-learn MLPs. Future versions may include PyTorch models for larger-scale training and GPU acceleration.
+- DMD forecasting accuracy degrades over longer horizons — it is suited to short-horizon prediction only.
+
+## Contributing
+
+Contributions welcome — particularly additional datasets, fluid-specific
+pre-trained models, and improved DMD variants. See `CONTRIBUTING.md`.
+
+## Licence
+
+MIT

icarus_thermal-0.1.0/icarus/__init__.py

@@ -0,0 +1,54 @@
+"""
+icarus
+=========
+Data-driven heat flux prediction from infrared thermography.
+
+Provides a full pipeline from raw IR data to trained heat flux prediction
+models using Proper Orthogonal Decomposition (POD), Dynamic Mode
+Decomposition (DMD), and artificial neural networks.
+
+Quickstart
+----------
+>>> import icarus as tf
+>>> import numpy as np
+>>>
+>>> # Load your IR temperature and heat flux arrays [ny, nx, nt]
+>>> T = np.load("temperature.npy")
+>>> q = np.load("heatflux.npy")
+>>>
+>>> # Run the full pipeline
+>>> pipeline = tf.Pipeline()
+>>> pipeline.fit(T, q)
+>>> q_pred = pipeline.predict(T_new)
+
+Modules
+-------
+data            : Loading and preprocessing of IR thermography datasets
+decomposition   : POD and DMD reduced-order analysis
+features        : Feature construction (gradients, modal contributions)
+models          : ANN training with Bayesian hyperparameter optimisation
+metrics         : R², RMSE, MAE evaluation utilities
+visualisation   : Spatial field, mode, and diagnostic plots
+pipeline        : End-to-end Pipeline orchestrator
+"""
+
+from icarus.pipeline.runner import Pipeline
+from icarus.decomposition.pod import POD
+from icarus.decomposition.dmd import DMD
+from icarus.data.preprocessor import Preprocessor
+from icarus.models.neural import HeatFluxNet, SEARCH_SPACES
+from icarus.metrics.evaluation import evaluate
+
+__version__ = "0.1.0"
+__author__ = "Raymond Twum-Barima"
+
+__all__ = [
+    "Pipeline",
+    "POD",
+    "DMD",
+    "Preprocessor",
+    "HeatFluxNet",
+    "SEARCH_SPACES",
+    "evaluate",
+    "__version__",
+]

icarus_thermal-0.1.0/icarus/data/__init__.py

@@ -0,0 +1 @@
+from . import *