gen_data/docs/FUNZIONALITA.md

Funzionalità

Elenco di ciò che il programma sa fare. Per l'uso passo per passo vedi il README; per il modello e i controlli di accettazione vedi SPEC.md.

Generazione dei dati — genera.py

• Profilo di temperatura: T parte dalla temperatura ambiente, sale con uno o più gradini di riscaldamento e ridiscende con raffreddamento esponenziale fino a T_amb.
• Gradini configurabili: numero, istanti e ampiezze (t_impulsi_s, dT_impulsi_c); lista vuota = nessun riscaldamento. Costante di raffreddamento in k_raffreddamento_hz.
• Variabilità tra corse: istanti, ampiezze e costante di raffreddamento dei gradini sono perturbati a caso a ogni seed (impulsi_jitter_*, k_jitter_rel; 0 = disattivata).
• Salti stocastici: scarti casuali con rientro esponenziale, sia durante il riscaldamento (salti_risc_*, nei due versi) sia durante il raffreddamento (salti_*, solo con T molto sopra l'ambiente), come i gradini irregolari di un sensore reale.
• Ambiente realistico: T_amb assestata con andamento esponenziale, con rumore e quantizzazione propri (amb_*). Non compare nel CSV, serve per ΔT e come baseline di T.
• Tempi con jitter: intervallo medio dt_ms con variazione uniforme ±jitter_ms, fino a durata_s.
• Risposta del sensore: filtro del primo ordine (tau_sensore_s) calcolato su griglia fine da 5 ms e interpolato ai tempi di campionamento.
• Rumore di T: componente bianca gaussiana, più forte quando T è molto sopra l'ambiente (sigma_c → sigma_caldo_c), più una deriva lenta di tipo Ornstein-Uhlenbeck (wander_*).
• Quantizzazione: T e ΔT a passo_T_c, ambiente a amb_passo_c. ΔT è calcolato dopo rumore e quantizzazione di entrambi i canali.
• Riproducibilità: --seed fissa il risultato (stesso seed e stessa configurazione ⇒ file identico); senza seed ne viene scelto uno casuale e stampato su stderr.
• Uscita flessibile: per default output/gen_<seed>.csv (cartella creata se manca); -o percorso per un file a scelta; -o - per stdout.
• Configurazione senza valori nascosti: tutti i valori stanno in un TOML; una chiave mancante, un TOML non valido o gradini di lunghezza diversa terminano con exit 1 e un messaggio in italiano. Lo stesso avviene se il file di uscita non è scrivibile.

Formato dell'uscita: t_ms,T_C,dT_C (t_ms intero, gli altri a due decimali).

Visualizzazione — grafico.py

• Disegna T e ΔT in funzione del tempo in due pannelli con asse comune.
• Senza argomenti usa l'ultimo CSV modificato in output/; oppure si indica il file.
• Apre una finestra, oppure con -o salva l'immagine (png, pdf, svg) e funziona anche senza schermo.
• Errore chiaro (exit 1) se non ci sono CSV, se il file non si legge o se il formato non è t_ms,T_C,dT_C.

Pulizia — pulisci.sh

• Svuota la cartella output/ (la cartella resta). Non tocca altro.
• Se output/ non esiste lo segnala senza errore.

Ambiente

• Gli script girano in un ambiente .venv nel progetto (creato con uv: numpy, più matplotlib per il grafico). Le dipendenze sono dichiarate anche nello script (PEP 723), quindi uv run funziona comunque.
• La cartella output/ è ignorata da git.

Limiti noti

Elencati in SPEC.md §6: un solo tempo di raffreddamento, gradini istantanei, ambiente che non sale col riscaldamento, nessun glitch di campionamento, rumore tarato su un solo sensore.