554 lines
22 KiB
Markdown
554 lines
22 KiB
Markdown
# Heat Equation PINN
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Soluzione dell'equazione del calore 1D con sorgente puntuale tramite **Physics-Informed Neural Network (PINN)**, validata contro un solver numerico **FDM** (Finite Difference Method).
|
||
|
||
---
|
||
|
||
## Indice
|
||
|
||
1. [Problema fisico](#1-problema-fisico)
|
||
2. [Approccio: PINN vs FDM](#2-approccio-pinn-vs-fdm)
|
||
3. [Struttura del progetto](#3-struttura-del-progetto)
|
||
4. [Installazione](#4-installazione)
|
||
5. [Utilizzo](#5-utilizzo)
|
||
6. [Architettura della rete neurale](#6-architettura-della-rete-neurale)
|
||
7. [Funzione di loss](#7-funzione-di-loss)
|
||
8. [Training](#8-training)
|
||
9. [Solver FDM di riferimento](#9-solver-fdm-di-riferimento)
|
||
10. [Visualizzazioni](#10-visualizzazioni)
|
||
11. [Parametri configurabili](#11-parametri-configurabili)
|
||
12. [Test](#12-test)
|
||
|
||
---
|
||
|
||
## 1. Problema fisico
|
||
|
||
Il progetto risolve l'equazione del calore 1D con una sorgente di calore puntuale interna che si attiva a un istante fissato:
|
||
|
||
```
|
||
∂T/∂t = α ∂²T/∂x² + (α/k) Q(t) δ(x − X_SRC)
|
||
```
|
||
|
||
dove:
|
||
- `T(x, t)` — temperatura [°C]
|
||
- `α` — diffusività termica [m²/s]
|
||
- `k` — conducibilità termica [W/m·K]
|
||
- `Q(t) = Q_VAL` se `t ≥ T_STEP`, altrimenti `0` — flusso di calore [W/m²]
|
||
- `δ(x − X_SRC)` — delta di Dirac nella posizione della sorgente
|
||
- Dominio: `x ∈ [0, L]`, `t ∈ [0, T_END]`
|
||
|
||
### Condizioni al contorno (Robin / convezione)
|
||
|
||
Entrambe le estremità della barra scambiano calore per convezione con l'ambiente:
|
||
|
||
```
|
||
x = 0: −k ∂T/∂x = h (T − T_AMB) → ∂T/∂x − (h/k)(T − T_AMB) = 0
|
||
x = L: −k ∂T/∂x = h (T − T_AMB) → ∂T/∂x + (h/k)(T − T_AMB) = 0
|
||
```
|
||
|
||
### Condizione iniziale
|
||
|
||
```
|
||
T(x, 0) = T₀ (temperatura uniforme)
|
||
```
|
||
|
||
### Parametri fisici di default
|
||
|
||
| Parametro | Valore | Unità | Significato |
|
||
|--------------|---------|----------|------------------------------------------|
|
||
| `ALPHA` | 0.01 | m²/s | Diffusività termica |
|
||
| `K` | 1.0 | W/m·K | Conducibilità termica |
|
||
| `L` | 1.0 | m | Lunghezza della barra |
|
||
| `T0` | 20.0 | °C | Temperatura iniziale uniforme |
|
||
| `X_SRC` | 0.35 | m | Posizione della sorgente di calore |
|
||
| `Q_VAL` | 150.0 | W/m² | Intensità del flusso di calore |
|
||
| `T_STEP` | 0.2 | s | Istante di attivazione della sorgente |
|
||
| `H_CONV` | 10.0 | W/m²·K | Coefficiente convettivo alle estremità |
|
||
| `T_AMB` | 20.0 | °C | Temperatura ambiente |
|
||
| `T_END` | 10.0 | s | Fine della simulazione |
|
||
|
||
---
|
||
|
||
## 2. Approccio: PINN vs FDM
|
||
|
||
### PINN (Physics-Informed Neural Network)
|
||
|
||
Una PINN è una rete neurale che impara a soddisfare un'equazione differenziale alle derivate parziali **senza dati sperimentali**. L'addestramento avviene minimizzando una funzione di loss che penalizza le violazioni della PDE, delle condizioni iniziali e delle condizioni al contorno in un insieme di **punti di collocazione** distribuiti nel dominio.
|
||
|
||
Vantaggi:
|
||
- Non richiede una griglia regolare
|
||
- Può essere addestrata su domini irregolari
|
||
- La soluzione è una funzione continua e differenziabile ovunque
|
||
|
||
In questo progetto la loss ha tre componenti:
|
||
1. **Residuo PDE** — la rete deve soddisfare l'equazione del calore
|
||
2. **Condizione iniziale** — la rete deve restituire `T₀` per `t = 0`
|
||
3. **Condizioni al contorno** — la rete deve soddisfare le Robin BC a `x=0` e `x=L`
|
||
|
||
### FDM (Finite Difference Method)
|
||
|
||
Il solver FDM (`fdm/`) implementa lo schema **FTCS** (Forward-Time Centered-Space) esplicito su una griglia regolare `NX × NT`. Non usa reti neurali: è una soluzione numerica classica che serve come **riferimento ad alta fedeltà** per validare la PINN.
|
||
|
||
La valutazione della PINN consiste nel calcolare l'errore relativo L2 tra la predizione della rete e la soluzione FDM interpolata sulla stessa griglia `100 × 100`.
|
||
|
||
---
|
||
|
||
## 3. Struttura del progetto
|
||
|
||
```
|
||
pinn/
|
||
├── config.py ← tutti i parametri fisici e numerici (modificare qui)
|
||
├── model.py ← HeatPINN (rete neurale) + heat_pinn_loss()
|
||
├── engine.py ← campionamento dati, training, valutazione vs FDM
|
||
├── visualizer.py ← grafici PINN vs FDM: heatmap, animazione, serie temporali
|
||
├── app.py ← CLI interattiva per PINN
|
||
├── requirements.txt
|
||
├── pytest.ini
|
||
├── clear.sh ← script di pulizia artefatti
|
||
├── fdm/
|
||
│ ├── solver.py ← schema FTCS esplicito con Robin BC e sorgente puntuale
|
||
│ ├── visualizer.py ← grafici FDM standalone
|
||
│ └── app.py ← CLI interattiva per FDM
|
||
└── tests/
|
||
├── conftest.py
|
||
├── test_config.py
|
||
├── test_model.py
|
||
├── test_engine_data.py
|
||
├── test_fdm_solver.py
|
||
├── test_integration_pinn.py
|
||
└── test_e2e.py
|
||
```
|
||
|
||
| File | Responsabilità |
|
||
|--------------------|-------------------------------------------------------------------------|
|
||
| `config.py` | Unica fonte di verità per tutti i parametri |
|
||
| `model.py` | Definizione della rete e calcolo della loss fisica |
|
||
| `engine.py` | Pipeline completa: campionamento → training → valutazione |
|
||
| `visualizer.py` | Plot interattivi HTML (PINN vs FDM) |
|
||
| `app.py` | Menu CLI per l'utente |
|
||
| `fdm/solver.py` | Solver numerico FTCS per la soluzione di riferimento |
|
||
| `fdm/visualizer.py`| Plot interattivi HTML (FDM standalone) |
|
||
| `fdm/app.py` | Menu CLI per il solver FDM |
|
||
|
||
---
|
||
|
||
## 4. Installazione
|
||
|
||
**Prerequisiti:** Python 3.10+, `pip`, `virtualenv` (o `venv`).
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd pinn
|
||
|
||
python -m venv .venv
|
||
source .venv/bin/activate # Linux / macOS
|
||
# .venv\Scripts\activate # Windows
|
||
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
Il progetto rileva automaticamente GPU/MPS/CPU all'avvio (vedi [engine.py — device detection](#12-dettagli-implementativi)).
|
||
|
||
---
|
||
|
||
## 5. Utilizzo
|
||
|
||
Attivare sempre il virtual environment prima di eseguire qualsiasi script:
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
### PINN (`app.py`)
|
||
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
```
|
||
1. Addestra nuovo modello
|
||
2. Valuta vs FDM (L2 error, max error)
|
||
3. Visualizza (genera 3 file HTML)
|
||
0. Esci
|
||
```
|
||
|
||
- **Opzione 1** — avvia l'addestramento (Adam + L-BFGS). Chiede il numero di epoche; premi Invio per usare il default (5000). Il modello migliore viene salvato in `models/best_heat_pinn_model.pth`. Per riaddestrare da zero: `rm models/best_heat_pinn_model.pth`.
|
||
- **Opzione 2** — carica il modello salvato, esegue il solver FDM, stampa l'errore relativo L2 e l'errore massimo assoluto.
|
||
- **Opzione 3** — genera tre file HTML interattivi in `results/pinn/<timestamp>/`.
|
||
|
||
### FDM (`fdm/app.py`)
|
||
|
||
```bash
|
||
python fdm/app.py
|
||
```
|
||
|
||
```
|
||
1. Risolvi (schema FTCS)
|
||
2. Visualizza (genera 3 file HTML)
|
||
0. Esci
|
||
```
|
||
|
||
- **Opzione 1** — esegue il solver e stampa shape della matrice e range di temperatura.
|
||
- **Opzione 2** — genera tre file HTML in `results/fdm/<timestamp>/`.
|
||
|
||
### Test
|
||
|
||
```bash
|
||
pytest tests/ -v # tutti i test (42)
|
||
pytest tests/test_model.py -v # rete e loss
|
||
pytest tests/test_engine_data.py -v # campionamento dati
|
||
pytest tests/test_fdm_solver.py -v # solver FDM
|
||
pytest tests/test_integration_pinn.py -v # integrazione PINN
|
||
pytest tests/test_e2e.py -v # workflow completo
|
||
```
|
||
|
||
### Pulizia artefatti
|
||
|
||
```bash
|
||
./clear.sh # menu interattivo per eliminare models/, results/ o entrambi
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Architettura della rete neurale
|
||
|
||
`HeatPINN` ([model.py](model.py)) è una rete fully connected a 5 layer:
|
||
|
||
```
|
||
Input (x, t)
|
||
│
|
||
[Linear 2→128, Tanh]
|
||
[Linear 128→128, Tanh] ×3
|
||
[Linear 128→1]
|
||
│
|
||
Output: T
|
||
```
|
||
|
||
La rete riceve le coordinate `(x, t)` e produce un unico scalare: la temperatura `T(x, t)`.
|
||
|
||
### Normalizzazione dell'input
|
||
|
||
Prima di entrare nella rete, le coordinate vengono normalizzate al range `[0, 1]`:
|
||
|
||
```python
|
||
x_norm = x / L # x ∈ [0, 1]
|
||
t_norm = t / T_END # t ∈ [0, 1]
|
||
```
|
||
|
||
Questo migliora il condizionamento numerico dell'ottimizzazione.
|
||
|
||
### Output scaling
|
||
|
||
La rete interna `net` non predice direttamente la temperatura: predice una **perturbazione adimensionale**. La temperatura fisica viene ricostruita con:
|
||
|
||
```python
|
||
T = T_AMB + (Q_VAL * L / K) * net(x_norm, t_norm)
|
||
```
|
||
|
||
dove `T_char = Q_VAL * L / K ≈ 150 °C` è la scala caratteristica di temperatura del problema.
|
||
|
||
**Perché questo scaling?**
|
||
- L'output della rete rimane nell'ordine di `[0, 1]`, rendendo il training più stabile.
|
||
- I gradienti `∂T/∂x` risultanti sono `O(1)` — la rete può imparare la struttura spaziale senza problemi di scala.
|
||
- Il termine di fondo `T_AMB` garantisce che la soluzione parta dalla condizione iniziale corretta anche con pesi random.
|
||
|
||
**Non rimuovere questo scaling**: senza di esso la rete deve imparare ordini di grandezza diversi tra le condizioni iniziali/al contorno e il gradiente interno, rendendo l'ottimizzazione molto più difficile.
|
||
|
||
---
|
||
|
||
## 7. Funzione di loss
|
||
|
||
`heat_pinn_loss()` ([model.py](model.py)) calcola quattro valori: `(total, L_pde, L_ic, L_bc)`.
|
||
|
||
```
|
||
total = W_PDE * L_pde + W_IC * L_ic + W_BC * L_bc
|
||
```
|
||
|
||
Ogni termine è **normalizzato automaticamente** da scale precompilate che dipendono solo dalle costanti in `config.py`. Cambiare `Q_VAL`, `K`, `H_CONV` o `L` ribilancia automaticamente la loss senza richiedere rituning manuale dei pesi.
|
||
|
||
### L_pde — Residuo PDE
|
||
|
||
Valutato su `N_F` punti di collocazione `(x_f, t_f)` distribuiti nel dominio:
|
||
|
||
```
|
||
residuo = dT/dt − α d²T/dx² − source(x, t)
|
||
```
|
||
|
||
Il termine sorgente usa un'approssimazione gaussiana al delta di Dirac (il delta non è differenziabile):
|
||
|
||
```
|
||
source(x, t) = (α/k) · Q(t) · G(x)
|
||
|
||
G(x) = exp(−0.5 · ((x − X_SRC) / σ)²) / (σ √(2π)) σ = GAUSS_SIGMA = 0.01 m
|
||
```
|
||
|
||
`Q(t)` è la funzione gradino: vale `Q_VAL` per `t ≥ T_STEP`, zero altrimenti.
|
||
|
||
I gradienti `dT/dt`, `dT/dx`, `d²T/dx²` sono calcolati con `torch.autograd.grad` — **autodifferenziazione esatta**, non differenze finite.
|
||
|
||
Normalizzazione: `_pde_scale = max((T_char/T_END)², src_peak²)` dove `src_peak` è il picco gaussiano.
|
||
|
||
### L_ic — Condizione iniziale
|
||
|
||
Valutato su `N_IC` punti `(x_ic, 0)`:
|
||
|
||
```
|
||
L_ic = mean( (T(x, 0) − T₀)² ) / T_char²
|
||
```
|
||
|
||
### L_bc — Condizioni al contorno Robin
|
||
|
||
Valutato su `N_BC` istanti temporali `t_bc`, applicato a entrambe le estremità:
|
||
|
||
```
|
||
x = 0: ∂T/∂x(0, t) − (h/k)(T(0,t) − T_AMB) = 0
|
||
x = L: ∂T/∂x(L, t) + (h/k)(T(L,t) − T_AMB) = 0
|
||
```
|
||
|
||
Normalizzazione: `_bc_scale = max(Q_VAL/K, H_CONV·T_char/K)²`
|
||
|
||
> **Nota sul segno:** la BC a sinistra (x=0) ha segno negativo davanti al termine convettivo perché il flusso uscente è orientato verso `−x`; a destra (x=L) il segno è positivo perché il flusso uscente è orientato verso `+x`.
|
||
|
||
---
|
||
|
||
## 8. Training
|
||
|
||
Il training è implementato in `train_model()` ([engine.py](engine.py)) e procede in due fasi.
|
||
|
||
### Fase 1: Adam
|
||
|
||
```
|
||
Ottimizzatore: Adam, LR = 1e-3
|
||
Scheduler: ReduceLROnPlateau (factor=0.5, patience=150, min_lr=1e-6)
|
||
Early stopping: se la loss non migliora di > 1e-7 per 500 epoche consecutive
|
||
```
|
||
|
||
Il modello con la loss più bassa viene salvato a ogni miglioramento in `models/best_heat_pinn_model.pth`.
|
||
|
||
### Fase 2: L-BFGS (fine-tuning)
|
||
|
||
Al termine dell'Adam, viene caricato il miglior modello e affinato con L-BFGS:
|
||
|
||
```
|
||
Ottimizzatore: L-BFGS, LR=0.1, max_iter=50, history_size=50, strong Wolfe
|
||
Steps: 200
|
||
```
|
||
|
||
L-BFGS è un ottimizzatore di secondo ordine (quasi-Newton) particolarmente efficace nella fase finale del training PINN perché sfrutta la curvatura della loss per convergere a minimi più precisi di quanto Adam riesca a fare.
|
||
|
||
**Meccanismo closure:** L-BFGS richiede di poter rivalutare la loss più volte per iterazione. La funzione `closure()` cattura i componenti della loss in un dizionario `_last` per poterli stampare senza ricalcolare il grafo computazionale fuori dal contesto di `backward()`.
|
||
|
||
### Campionamento dei punti di collocazione
|
||
|
||
`prepare_data()` genera i punti di collocazione con **clustering deliberato** nelle zone fisicamente più complesse:
|
||
|
||
| Zona | Proporzione | Motivazione |
|
||
|-----------------------------|-------------|------------------------------------------------|
|
||
| Uniforme `[0,L] × [0,T_END]`| 50% | Copertura generale del dominio |
|
||
| Intorno a `X_SRC ± 5% L` | 25% | Gradiente ripido in prossimità della sorgente |
|
||
| Intorno a `T_STEP ± 0.1 s` | 25% | Discontinuità temporale all'attivazione |
|
||
|
||
Il clustering aumenta la densità di punti dove la fisica è più difficile da apprendere, senza aumentare il costo computazionale totale.
|
||
|
||
---
|
||
|
||
## 9. Solver FDM di riferimento
|
||
|
||
`fdm/solver.py` implementa lo schema **FTCS** (Forward-Time Centered-Space) esplicito.
|
||
|
||
### Schema di avanzamento temporale
|
||
|
||
```
|
||
T[i, n+1] = T[i, n] + r · (T[i+1,n] − 2·T[i,n] + T[i−1,n])
|
||
|
||
r = α·dt/dx² (numero di Courant-Friedrichs-Lewy)
|
||
```
|
||
|
||
### Stabilità CFL
|
||
|
||
Condizione necessaria per la stabilità dello schema esplicito:
|
||
|
||
```
|
||
r = α·dt/dx² ≤ 0.5
|
||
```
|
||
|
||
Se la condizione è violata, il solver stampa un avvertimento ma non si blocca. Con i parametri di default (`NX=250`, `NT=15000`) la condizione è soddisfatta. Se si riducono `NX` o `NT`, verificare che `r ≤ 0.5`.
|
||
|
||
### Condizioni al contorno Robin
|
||
|
||
Le BC sono applicate a ogni passo temporale usando uno schema centrato:
|
||
|
||
```
|
||
T[0] = (T[1] + robin_coeff · T_AMB) / (1 + robin_coeff) # x = 0
|
||
T[-1] = (T[-2] + robin_coeff · T_AMB) / (1 + robin_coeff) # x = L
|
||
|
||
robin_coeff = dx · h / k
|
||
```
|
||
|
||
### Iniezione della sorgente puntuale
|
||
|
||
Dopo l'applicazione delle BC, la sorgente viene iniettata al nodo più vicino a `X_SRC`:
|
||
|
||
```
|
||
T[i_src] += Q(t) · α · dt / (k · dx)
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Visualizzazioni
|
||
|
||
Tutti i plot sono **HTML interattivi** generati con Plotly (zoom, hover, slider, play/pause).
|
||
|
||
### PINN vs FDM (`visualizer.py`)
|
||
|
||
Generati con `python app.py → opzione 3`, salvati in `results/pinn/<timestamp>/`:
|
||
|
||
| File | Contenuto |
|
||
|-------------------|------------------------------------------------------------------------|
|
||
| `heatmap.html` | Heatmap 2D affiancate PINN vs FDM, stessa scala colori |
|
||
| `animation.html` | Profilo T(x) animato nel tempo: PINN (blu continuo) vs FDM (rosso tratteggiato) |
|
||
| `comparison.html` | Serie temporali T(t) nei punti fissi `x=0`, `x=L/2`, `x=L`; linea verticale a `t=T_STEP` |
|
||
|
||
### FDM standalone (`fdm/visualizer.py`)
|
||
|
||
Generati con `python fdm/app.py → opzione 2`, salvati in `results/fdm/<timestamp>/`:
|
||
|
||
| File | Contenuto |
|
||
|-------------------|------------------------------------------------------------------------|
|
||
| `heatmap.html` | Heatmap 2D T(x,t) + striscia animata del profilo di temperatura |
|
||
| `animation.html` | Profilo T(x) animato nel tempo |
|
||
| `time_series.html`| Serie temporali in 5 punti fissi: `0`, `0.25L`, `0.5L`, `0.75L`, `L` |
|
||
|
||
---
|
||
|
||
## 11. Parametri configurabili
|
||
|
||
Tutti i parametri si trovano in `config.py`. Modificare solo questo file per cambiare il problema o il training.
|
||
|
||
### Fisica
|
||
|
||
| Parametro | Default | Unità | Descrizione |
|
||
|--------------|---------|--------|------------------------------------------|
|
||
| `ALPHA` | 0.01 | m²/s | Diffusività termica |
|
||
| `K` | 1.0 | W/m·K | Conducibilità termica |
|
||
| `L` | 1.0 | m | Lunghezza della barra |
|
||
| `T0` | 20.0 | °C | Temperatura iniziale uniforme |
|
||
| `X_SRC` | 0.35 | m | Posizione della sorgente di calore |
|
||
| `Q_VAL` | 150.0 | W/m² | Intensità del flusso di calore |
|
||
| `T_STEP` | 0.2 | s | Istante di attivazione della sorgente |
|
||
| `H_CONV` | 10.0 | W/m²·K | Coefficiente convettivo alle estremità |
|
||
| `T_AMB` | 20.0 | °C | Temperatura ambiente |
|
||
| `T_END` | 10.0 | s | Fine della simulazione |
|
||
|
||
### Griglia FDM
|
||
|
||
| Parametro | Default | Descrizione |
|
||
|--------------|---------|---------------------------------------------------------|
|
||
| `NX` | 250 | Nodi spaziali (aumentare per maggiore risoluzione) |
|
||
| `NT` | 15000 | Passi temporali (verificare `r = α·dt/dx² ≤ 0.5`) |
|
||
| `GAUSS_SIGMA`| 0.01 | Larghezza del picco gaussiano nella loss PINN [m] |
|
||
|
||
### Architettura PINN
|
||
|
||
| Parametro | Default | Descrizione |
|
||
|-------------------|---------|----------------------------------------------|
|
||
| `HIDDEN_SIZE` | 128 | Neuroni per layer nascosto |
|
||
| `N_HIDDEN_LAYERS` | 4 | Numero di layer nascosti (totale: 5 layer) |
|
||
|
||
### Campionamento
|
||
|
||
| Parametro | Default | Descrizione |
|
||
|-----------|---------|--------------------------------------------------------------------|
|
||
| `N_F` | 6000 | Punti PDE (+ 50% clustering automatico vicino a X_SRC e T_STEP) |
|
||
| `N_IC` | 400 | Punti condizione iniziale |
|
||
| `N_BC` | 400 | Punti condizioni al contorno |
|
||
|
||
### Training Adam
|
||
|
||
| Parametro | Default | Descrizione |
|
||
|-----------------|---------|-----------------------------------------------------|
|
||
| `EPOCHS` | 5000 | Epoche massime |
|
||
| `PATIENCE` | 500 | Early stopping: epoche senza miglioramento |
|
||
| `LR_ADAM` | 1e-3 | Learning rate iniziale |
|
||
| `SCHED_FACTOR` | 0.5 | Fattore di riduzione LR (ReduceLROnPlateau) |
|
||
| `SCHED_PATIENCE`| 150 | Patience per la riduzione LR |
|
||
| `SCHED_MIN_LR` | 1e-6 | Learning rate minimo |
|
||
|
||
### Fine-tuning L-BFGS
|
||
|
||
| Parametro | Default | Descrizione |
|
||
|---------------|---------|--------------------------|
|
||
| `LR_LBFGS` | 0.1 | Learning rate L-BFGS |
|
||
| `LBFGS_STEPS` | 200 | Numero di step L-BFGS |
|
||
|
||
### Pesi della loss
|
||
|
||
| Parametro | Default | Descrizione |
|
||
|-----------|---------|--------------------------------|
|
||
| `W_PDE` | 10.0 | Peso residuo PDE |
|
||
| `W_IC` | 1.0 | Peso condizione iniziale |
|
||
| `W_BC` | 5.0 | Peso condizioni al contorno |
|
||
|
||
> **Se la loss diverge:** verificare che `T_char = Q_VAL * L / K` non sia vicino a zero. Questo valore è la scala caratteristica di temperatura usata per normalizzare tutti i termini.
|
||
|
||
---
|
||
|
||
## 12. Test
|
||
|
||
La test suite è in `tests/` e conta **42 test** organizzati in tre livelli:
|
||
|
||
| File | Tipo | Cosa testa |
|
||
|------------------------------|-------------|---------------------------------------------------|
|
||
| `test_config.py` | Unit | Validità e coerenza dei parametri in `config.py` |
|
||
| `test_model.py` | Unit | Shape output, finitezza, loss components |
|
||
| `test_engine_data.py` | Unit | Campionamento e clustering dei punti |
|
||
| `test_fdm_solver.py` | Unit | Griglia, CFL, shape output del solver FDM |
|
||
| `test_integration_pinn.py` | Integration | Caricamento modello, griglia predizione, pipeline loss |
|
||
| `test_e2e.py` | End-to-end | Workflow completo: train → evaluate → visualize |
|
||
|
||
```bash
|
||
pytest tests/ -v # run tutti i test
|
||
pytest tests/ -k "model" # solo test con "model" nel nome
|
||
pytest tests/ --tb=short # traceback breve in caso di fallimento
|
||
```
|
||
|
||
---
|
||
|
||
## Dettagli implementativi
|
||
|
||
### Normalizzazione automatica della loss
|
||
|
||
Le scale sono precompilate una sola volta a import time in `model.py`:
|
||
|
||
```python
|
||
_T_char = Q_VAL * L / K # ~150 °C
|
||
_src_peak = ALPHA * Q_VAL / (K * GAUSS_SIGMA * sqrt(2π))
|
||
_pde_scale = max((_T_char / T_END)², _src_peak²) + 1e-8
|
||
_bc_scale = max(Q_VAL / K, H_CONV * _T_char / K) ** 2
|
||
```
|
||
|
||
Dividere ogni termine per la sua scala porta tutti i contributi a `O(1)`, rendendo i pesi `W_PDE`, `W_IC`, `W_BC` interpretabili come importanza relativa piuttosto che come fattori di scala assoluti.
|
||
|
||
### Rilevamento device
|
||
|
||
`engine.py` seleziona automaticamente il device più performante disponibile:
|
||
|
||
```python
|
||
CUDA → MPS (Apple Silicon) → CPU
|
||
```
|
||
|
||
Include un test di funzionamento effettivo della GPU prima di usarla, per evitare fallimenti silenziosi su driver incompleti.
|
||
|
||
### Closure L-BFGS
|
||
|
||
L-BFGS richiede una funzione `closure()` che esegue `zero_grad`, forward pass, `backward`, e restituisce la loss. I componenti della loss vengono catturati in un dizionario `_last` per permettere il logging a ogni step senza ricalcolare il grafo fuori dal contesto `backward`.
|
||
|
||
### Subsampling delle animazioni FDM
|
||
|
||
Se `NT > 200`, il visualizer FDM campiona ogni `n`-esimo frame (`n = NT // 200`) per mantenere le animazioni HTML leggere e fluide.
|