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 è 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):

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, 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: unica fonte dei valori numerici; unità nei suffissi (_s, _ms, _c, _hz).
• 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.