# Funzionalità

Elenco di ciò che il programma sa fare. Per l'uso passo per passo vedi il [README](../README.md); per il modello e i controlli di accettazione vedi [SPEC.md](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 sorteggiati**: numero, istante del primo, distanza tra gradini e ampiezze sono estratti a caso a ogni seed da intervalli (`n_gradini`, `t_primo_gradino_s`, `distanza_gradini_s`, `dT_gradino_c`). Costante di raffreddamento in `k_raffreddamento_hz`.
- **Parametri casuali per corsa**: le chiavi scritte `[min, max]` (ambiente, livelli di rumore, `k`, `tau_sensore_s`, frequenza e σ dei salti) vengono sorteggiate uniformi a ogni seed, così ogni file ha parametri davvero diversi; `[x, x]` = valore fisso.
- **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 un intervallo `[min, max]` non valido 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.

## Aiuto da riga di comando

- `-h` / `--help` su `genera.py`, `grafico.py` e `pulisci.sh`: opzioni, esempi, formato dell'output, gruppi di chiavi di `config.toml` e codici di uscita, in italiano.
- Argomenti non validi: messaggio in italiano e exit 2.

## Ambiente

- Gli script girano in un ambiente `.venv` nel progetto (creato con [uv](https://docs.astral.sh/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](SPEC.md): un solo tempo di raffreddamento, gradini istantanei, ambiente che non sale col riscaldamento, nessun glitch di campionamento, rumore tarato su un solo sensore.