davideandClaude Sonnet 5.5
f28bddc5a2
- docs/SPEC.md sostituito da un file per argomento (indice in docs/README.md) - assunzioni A1-A24 con dove nel codice e cosa succede se false - formule in LaTeX corrette (nessuno spazio prima del dollaro di chiusura), simboli e chiavi in tabella - diagrammi Mermaid per il flusso degli algoritmi e le dipendenze dei moduli - figura dei domini sul seed 1 (docs/img/domini_esempio.png) - README ridotto a indice con avvio rapido; CLAUDE.md e docstring allineati Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
64 lines
4.4 KiB
Markdown
64 lines
4.4 KiB
Markdown
# 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.
|
||
|
||
|
||
|
||
*Figura: dati reali di `input/gen_1.csv` (serie `T_C`) 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 fratello `../gen_data` (modello e parametri: `../gen_data/docs/SPEC.md`). 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** | salto positivo di temperatura tra due campioni consecutivi, sopra `soglia_gradino_c` |
|
||
| **dominio** | tratto contiguo di campioni con un tipo: `riposo`, `riscaldamento` o `raffreddamento` |
|
||
| **riscaldamento** | la salita rapida di un gradino (2–3 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 $\mathrm{RMSE} > 1.3\,\sigma$: la forma non spiega tutto il rumore |
|
||
| **tempo del dominio** | $t' = t - t_0$, con $t_0$ il tempo del primo campione del dominio |
|
||
|
||
## Esempio (seed 1 di `gen_data`)
|
||
|
||
La figura sopra è il risultato di `fitseg analizza input/gen_1.csv` su `T_C`: sul raffreddamento finale $\tau = 16.08 \pm 0.07$ s, $c = 23.00$ °C, $A = 179.6$ °C;
|
||
i due raffreddamenti intermedi usano gli stessi $c$ e $\tau$ e stimano solo $A$ ($84.3$ e $148.3$ °C); i tre riscaldamenti sono salti di $+82.2$, $+71.1$ e $+60.8$ °C.
|
||
Il valore nominale del generatore è $\tau = 1/k = 15.9$ s (con $k$ perturbato del 2 % per seed): il fit lo recupera entro l'1 %.
|
||
|
||
## 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) |
|