gen_data/README.md

# Generatore CSV `T` e `ΔT`

Genera un CSV con la temperatura `T` di un sensore IR e la differenza `ΔT = T − T_amb`, con rumore, quantizzazione e jitter dei tempi simili a un sensore reale. `T` parte dalla temperatura ambiente, sale con i gradini di riscaldamento e ridiscende fino a `T_amb`.

## Requisiti e ambiente

Python ≥ 3.11 con `numpy` e `matplotlib` (quest'ultimo solo per il grafico), in un ambiente virtuale `.venv` nella cartella del progetto. Lo si crea con [uv](https://docs.astral.sh/uv/), più veloce di `venv` + `pip`:

```bash
uv venv .venv
uv pip install numpy matplotlib
source .venv/bin/activate        # poi si usa `python ...`; senza attivare: `.venv/bin/python ...`
```

`.venv/` è ignorato da git. Con `venv` classico: `python -m venv .venv && .venv/bin/pip install numpy matplotlib`.

### Installare uv

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh          # Linux e macOS
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
pip install uv                                           # alternativa, se hai già Python
```

Apri un nuovo terminale e verifica con `uv --version`. Altre opzioni (Homebrew, WinGet, ecc.) sono nella [guida ufficiale](https://docs.astral.sh/uv/getting-started/installation/).

## Uso

Con l'ambiente `.venv` attivo (altrimenti sostituisci `python` con `.venv/bin/python`):

```bash
python genera.py config.toml                      # scrive output/gen_<seed>.csv, seed casuale
python genera.py config.toml --seed 42            # riproducibile: output/gen_42.csv
python genera.py config.toml -o dati/prova.csv    # percorso a scelta (cartelle create se mancano)
python genera.py config.toml -o - > out.csv       # su stdout
```

| Opzione | Descrizione |
|---|---|
| `config` | file di configurazione TOML (obbligatorio) |
| `-o`, `--output` | file di uscita; default `output/gen_<seed>.csv`; `-` = stdout |
| `--seed` | seme del generatore; se omesso è casuale e viene stampato su stderr |

Stesso seed e stessa configurazione danno sempre lo stesso file. La cartella `output/` è ignorata da git.

## Grafico

```bash
python grafico.py                          # apre il grafico dell'ultimo CSV in output/
python grafico.py output/gen_42.csv        # un CSV preciso
python grafico.py -o grafico.png           # salva l'immagine (png, pdf, svg) invece di aprire la finestra
```

Mostra `T` e `ΔT` in funzione del tempo. `grafico.py` ha le sue dipendenze (`numpy`, `matplotlib`), vedi sopra; senza schermo usa `-o`.

## Pulizia

```bash
./pulisci.sh                               # svuota la cartella output/
```

## Aiuto

Ogni comando ha un aiuto completo (opzioni, esempi, formato, chiavi della configurazione, codici di uscita):

```bash
python genera.py --help      # oppure -h
python grafico.py --help
./pulisci.sh --help
```

## Output

```
t_ms,T_C,dT_C
151,22.90,0.20
301,22.63,0.03
```

`t_ms` è intero; `T_C` e `dT_C` hanno due decimali. `ΔT` è calcolato dopo rumore e quantizzazione di entrambi i canali.

## Configurazione

Tutti i valori numerici sono in [config.toml](config.toml) (nessuno è scritto nello script). Le unità sono nei suffissi delle chiavi: `_s` secondi, `_ms` millisecondi, `_c` gradi C, `_hz` 1/s. Una chiave mancante è un errore (exit 1, messaggio in italiano), così come un intervallo `[min, max]` non valido (non una coppia di numeri, o min > max).

Le chiavi scritte come intervallo `[min, max]` vengono sorteggiate a ogni corsa (`[x, x]` = valore fisso). Per cambiare il profilo di riscaldamento si modificano `n_gradini`, `t_primo_gradino_s`, `distanza_gradini_s`, `dT_gradino_c` e `k_raffreddamento_hz`. `durata_s` deve essere abbastanza lunga perché `T` torni a `T_amb`.

## Documentazione

Elenco completo delle funzionalità in [docs/FUNZIONALITA.md](docs/FUNZIONALITA.md). Modello, passi di calcolo, controlli di accettazione e limiti sono in [docs/SPEC.md](docs/SPEC.md).