docs/panoramica.md

# Panoramica

## Cosa fa

`fitseg` prende la serie temporale di un sensore IR che si scalda e si raffredda (CSV `t_ms,T_C,dT_C`) e per ogni **tratto** del segnale
trova l'equazione che lo descrive meglio. Il lavoro è in tre passi:

1. **Domini**: divide il tempo in tratti omogenei (riposo, riscaldamento, raffreddamento).
2. **Equazioni**: in ogni tratto fitta i modelli adatti con minimi quadrati non lineari e sceglie il migliore con una regola fissa.
3. **Sovrapposizione e report**: confronta i dati grezzi con le equazioni trovate e scrive un report con grafici e formule.

Tutto è deterministico: stessi dati e stessa configurazione danno gli stessi risultati. Non c'è nessun modello linguistico né nessuna
parte casuale.

## Il segnale

Il sensore parte dalla temperatura ambiente (**riposo**). Poi il campione viene scaldato a **gradini**: la temperatura sale in una frazione
di secondo (pochi campioni, **riscaldamento**) e subito dopo decade verso l'ambiente (**raffreddamento**). Con più gradini ravvicinati
(2–4 s) il decadimento di ognuno è interrotto dal successivo; dopo l'ultimo gradino il raffreddamento prosegue fino all'ambiente.

![Segnale del seed 7: i 7 domini, lo zoom sui gradini e la tabella dei risultati](img/domini_esempio.png)

*Figura: dati reali di `input/gen_7.csv` (serie `T_C`, seed 7 di `gen_data`) con i domini riconosciuti da `fitseg` e le equazioni trovate. In alto il segnale completo, al
centro lo zoom sui tre gradini, in basso la tabella che associa a ogni numero tipo, intervallo ed equazione. Il riscaldamento è rosso, il riposo grigio e
ogni raffreddamento ha un colore diverso. Con 3 gradini i domini sono $1 + 2\cdot 3 = 7$.*

Il generatore dei dati di prova è il repository `gen_data` (clonato in `extern/gen_data` con `./scarica_gen_data.sh`) (modello e parametri: `extern/gen_data/docs/SPEC.md`): a ogni seed sorteggia numero
dei gradini (1–3), costante di tempo, rumore e disturbi, quindi ogni file ha una struttura diversa. Le sue caratteristiche che contano per `fitseg` sono
elencate in [assunzioni.md](assunzioni.md), sezione «Origine dei dati di prova».

## Concetti

| Termine | Significato |
|---|---|
| **serie** | una colonna del CSV da approssimare (`T_C` temperatura, `dT_C` differenza dall'ambiente). Tutte le serie condividono gli stessi domini |
| **gradino** | salita positiva di temperatura, distribuita su 2–4 campioni, la cui salita complessiva supera `soglia_gradino_c` |
| **dominio** | tratto contiguo di campioni con un tipo: `riposo`, `riscaldamento` o `raffreddamento` |
| **riscaldamento** | la salita rapida di un gradino (2–4 campioni): troppo breve per un fit, è descritta come **salto** ($\Delta$, da → a, durata) |
| **raffreddamento** | il decadimento dopo un gradino, fino al gradino successivo o alla fine; modello esponenziale |
| **raffreddamento finale / intermedio** | il finale è l'ultimo dominio (il più lungo, parametri liberi); gli intermedi stanno tra due gradini (corti) e ricevono $c$ e $\tau$ dal finale |
| **modello** | una famiglia di equazioni (`costante`, `lineare`, `esp_decad`); vedi [algoritmi.md](algoritmi.md) §5.1 |
| **parametro fisso** | parametro tenuto costante nel fit (non conta nei gradi di libertà); marcato «(fisso)» nel report |
| **indeterminato** | nessun modello valido, oppure dominio con meno di `n_min_punti` campioni |
| **non adeguato** | modello scelto ma con $\hat\sigma_\text{res} > 1.5\,\sigma$ (scala robusta dei residui, che ignora gli scarti casuali): il modello non spiega i dati |
| **tempo del dominio** | $t' = t - t_0$, con $t_0$ il tempo del primo campione del dominio |

## Esempio (seed 7 di `gen_data`)

La figura sopra è il risultato di `fitseg analizza input/gen_7.csv` su `T_C`: sul raffreddamento finale $\tau = 12.12 \pm 0.04$ s, $c = 23.92$ °C, $A = 163.2$ °C;
i due raffreddamenti intermedi usano gli stessi $c$ e $\tau$ e stimano solo $A$ ($76.7$ e $124.5$ °C); i tre riscaldamenti sono salti di $+79.7$, $+71.4$ e $+90.2$ °C.
I valori veri del seed 7 sono $\tau = 1/k = 12.07$ s e salti di $79.6$, $71.1$ e $89.4$ °C: il fit li recupera entro lo 0.5 % ($\tau$) e l'1 % (salti).
Su 60 seed diversi l'errore su $\tau$ resta sotto il 2 % ([test.md](test.md)).

## Dove andare avanti

| Per… | Leggi |
|---|---|
| lanciare i comandi, correggere i domini a mano | [uso.md](uso.md) |
| capire cosa si dà per vero e cosa succede se non lo è | [assunzioni.md](assunzioni.md) |
| sapere come funzionano rilevamento, fit e scelta, con le formule | [algoritmi.md](algoritmi.md) |
| orientarsi nel codice (un modulo alla volta) | [moduli.md](moduli.md) |
| cambiare un valore (ogni chiave di `config.toml`) | [configurazione.md](configurazione.md) |
| leggere i file prodotti e i grafici | [output.md](output.md) |
| eseguire e capire i test | [test.md](test.md) |
| conoscere limiti noti e possibili estensioni | [limiti.md](limiti.md) |