report-temperatura/README.md

# Analisi Termica Forno — Cevolani

Script Python per l'analisi del profilo termico di una scatola che attraversa un forno industriale, con acquisizione tramite sensori IR.

## Setup (Windows)

```bat
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```

## Avvio rapido

Tutto il progetto è accessibile tramite un menu interattivo:

```bat
python main.py
```

Il menu si ripete dopo ogni operazione finché non si preme `0` per uscire.
Le voci del menu vengono costruite automaticamente in base alle cartelle presenti nel progetto: aggiungere una nuova cartella `induttoreX/` con un `appX.py` la fa apparire automaticamente.

---

## Struttura del progetto

```text
temperatura/
├── data.csv                  # dati acquisiti (input)
├── main.py                   # menu interattivo
├── report_completo.py        # generatore report PDF + LaTeX
├── algoritmo.md              # descrizione dell'algoritmo di regressione
├── clear.sh                  # elimina tutti i file generati
├── requirements.txt
├── start/
│   ├── calcola_t_amb.py      # calcola T∞ media ponderata
│   └── plot_temperatura.py   # visualizza i dati raw
└── induttoreX/               # una cartella per ogni induttore
    ├── appX.py               # script di fit (parametri hardcoded)
    ├── induttoreX.png        # grafico generato
    └── reportX.md            # report generato
```

---

## Voci del menu

### Calcola T ambiente

**Script:** `start/calcola_t_amb.py`

Calcola la temperatura ambiente media ponderata sul tempo (regola dei trapezi) usando la colonna `temp_amb IR [C]` dell'intera acquisizione. Stampa i risultati a console e genera `start/report.md`.

> Il valore ottenuto viene usato come costante `T∞` in tutti i fit.

---

### Plot dati raw

**Script:** `start/plot_temperatura.py`

Visualizza il profilo grezzo di entrambe le serie (`temp_obj IR` e `temp_amb IR`) nell'intervallo definito dalle variabili `T0` e `T_END` in cima al file. Salva il grafico in `start/plot_temperatura.png`.

---

### Induttore X — appX.py

**Script:** `induttoreX/appX.py`

Esegue la regressione non lineare sul tratto di acquisizione definito dalle variabili `T0` e `T_END` in cima allo script (modificabili manualmente). Produce:

- `induttoreX/induttoreX.png` — grafico con dati raw e curva di fit sovrapposti
- `induttoreX/reportX.md` — equazione trovata, parametri stimati con incertezze (1σ) e R²

Per aggiungere un nuovo induttore: copiare uno script esistente, aggiornare `T0`, `T_END` (e `W0_START`/`W0_END` se serve escludere un intervallo), e salvarlo in una nuova cartella `induttoreX/`.

---

### Algoritmo di regressione

**File:** `algoritmo.md`

Spiega l'algoritmo usato per tutti i fit: minimi quadrati non lineari, metodo Trust Region Reflective (TRF), gestione dei pesi, stima iniziale dei parametri e metriche di qualità (R², incertezze dalla matrice di covarianza).

---

### Report completo (PDF + LaTeX)

**Script:** `report_completo.py`

Legge automaticamente tutti i `reportX.md` presenti nelle cartelle `induttore*/` e genera:

- `report_completo.tex` — sorgente LaTeX compilabile con MikTeX o TeX Live
- `report_completo.pdf` — PDF professionale con cover page, scheda documento, header/footer e tabella riepilogativa finale

Il PDF viene generato direttamente da Python tramite `reportlab` (nessuna dipendenza esterna richiesta).

---

### Pulizia file generati

**Script:** `clear.sh`

Elimina tutti i file prodotti dagli script (`*.md` e `*.png` in `start/` e `induttore*/`, più `report_completo.tex` e `report_completo.pdf`). I sorgenti e `data.csv` non vengono toccati.

```bash
bash clear.sh
```

---

## Requisiti di data.csv

### Formato

| Proprietà | Valore richiesto |
| --- | --- |
| Formato | CSV |
| Separatore | `,` (virgola) |
| Encoding | UTF-8 |
| Prima riga | intestazione (header) |

### Colonne obbligatorie

I nomi delle colonne devono corrispondere **esattamente** (spazi e maiuscole inclusi):

| Colonna | Unità | Descrizione |
| --- | --- | --- |
| `time since start [ms]` | ms | Tempo dall'inizio acquisizione — convertito in secondi (`/ 1000`) da tutti gli script |
| `temp_obj IR [C]` | °C | Temperatura dell'oggetto misurato (target del fit) |
| `temp_amb IR [C]` | °C | Temperatura ambiente (usata per calcolare T∞) |

Le colonne aggiuntive presenti nel file vengono ignorate.

### Copertura temporale

Il file deve contenere campioni nei range temporali usati da ciascuno script. I parametri `T0` e `T_END` in ogni `appX.py` devono ricadere all'interno dei valori di `time since start [ms]` presenti nel CSV (convertiti in secondi).

## Modello di fitting

Tutti i fit usano il modello di raffreddamento di Newton:

```text
T(t) = T∞ + A · exp( -(t - t₀) / τ )
```

con `T∞` fissa (calcolata da `calcola_t_amb.py`) e parametri `A`, `τ` liberi, stimati con regressione non lineare (metodo TRF di `scipy.optimize.curve_fit`).