gen_data/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Generatore di CSV `t_ms,T_C,dT_C` (temperatura di un sensore IR che si scalda e si raffredda, con rumore realistico). [docs/SPEC.md](docs/SPEC.md) è l'unica fonte di verità su output, modello, CLI, errori e controlli di accettazione: leggila per intero prima di cambiare il comportamento. Documentazione, commenti e messaggi di errore sono in italiano.

## Comandi

Ambiente `.venv` nel progetto (numpy per `genera.py`, in più matplotlib per `grafico.py`):

```bash
uv venv .venv && uv pip install numpy matplotlib
.venv/bin/python genera.py config.toml --seed 42    # scrive output/gen_42.csv
.venv/bin/python grafico.py -o g.png                # grafico dell'ultimo CSV in output/
./pulisci.sh                                        # svuota output/
```

`--help` di ogni script (testo in `DESCRIZIONE`/`EPILOGO` per `genera.py`) elenca le chiavi di `config.toml` per gruppo: va aggiornato insieme a `CHIAVI`.

Non ci sono test automatici: la verifica è sui controlli di §5 di SPEC.md, su più seed (vedi gotcha).

## Mappa del codice

- [genera.py](genera.py), script unico: `leggi_config` (valida `CHIAVI`) → `genera` → `scrivi`. Dentro `genera`: `sorteggia` (estrae a ogni corsa i valori dagli intervalli `[min, max]` di `config.toml` e genera i gradini), `eccesso` (gradini + raffreddamento), `salti` / `eventi` (disturbi Poisson in riscaldamento e raffreddamento), poi filtro del sensore, rumore, quantizzazione.
- [config.toml](config.toml): unica fonte dei valori numerici; unità nei suffissi (`_s`, `_ms`, `_c`, `_hz`).
- [grafico.py](grafico.py): script separato, non importa `genera.py`.

## Gotcha

- `ΔT` = T − ambiente, calcolato **dopo** rumore e quantizzazione di entrambi i canali, mai dalla T vera.
- Le chiavi `[min, max]` stanno in `INTERVALLI` / `INTERVALLI_GRADINI` (validate in `leggi_config`): una nuova chiave-intervallo va aggiunta lì oltre che a `CHIAVI`.
- Nessun valore numerico nello script: ogni chiave nuova di `config.toml` va aggiunta anche a `CHIAVI` in `genera.py` (chiave mancante ⇒ exit 1) e descritta in SPEC.md e nell'epilogo di `--help`.
- Un solo `numpy.random.Generator` seminato da `--seed`: stesso seed + stessa config ⇒ file identico. Cambiare numero o ordine delle estrazioni casuali cambia i file di ogni seed.
- Tutto ciò che sembra "fisso" nelle curve (salti, picco, istanti) è casuale per seed: non esistono istanti programmati.
- Gli intervalli di §5 di SPEC.md (picco, `T`/`ΔT` finali) sono empirici su 60 seed: se cambi `config.toml` (intervalli dei gradini, durata, salti, k) ricalcolali e aggiornali.
- `uv run genera.py` usa un ambiente a parte nella cache di uv, non `.venv`; i comandi del progetto sono quelli con `.venv/bin/python`.