Documentazione: uso con ambiente .venv creato con uv

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Stato
 
-[genera.py](genera.py) è lo script unico (PEP 723, `uv run genera.py config.toml --seed 42`, scrive in `output/`). [grafico.py](grafico.py) disegna un CSV di output (script separato, dipende da matplotlib; `genera.py` resta con solo numpy); `genera.py` implementa [docs/SPEC.md](docs/SPEC.md), unica fonte di verità su output, modello, CLI, errori e controlli di accettazione. Leggila per intero prima di scrivere codice. Documentazione, commenti e messaggi di errore sono in italiano.
+[genera.py](genera.py) è lo script unico (`python genera.py config.toml --seed 42` nell'ambiente `.venv`, creato con `uv venv`; scrive in `output/`). [grafico.py](grafico.py) disegna un CSV di output (script separato, dipende da matplotlib; `genera.py` resta con solo numpy); `genera.py` implementa [docs/SPEC.md](docs/SPEC.md), unica fonte di verità su output, modello, CLI, errori e controlli di accettazione. Leggila per intero prima di scrivere codice. Documentazione, commenti e messaggi di errore sono in italiano.
 
 ## File
 

README.md

@@ -2,9 +2,17 @@
 
 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
+## Requisiti e ambiente
 
-[uv](https://docs.astral.sh/uv/). Gli script dichiarano le loro dipendenze (Python ≥ 3.11, `numpy`, `matplotlib` per il grafico): al primo avvio uv crea da solo l'ambiente virtuale e, se serve, scarica Python. Non serve installare altro.
+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
 
@@ -18,11 +26,13 @@ Apri un nuovo terminale e verifica con `uv --version`. Altre opzioni (Homebrew,
 
 ## Uso
 
+Con l'ambiente `.venv` attivo (altrimenti sostituisci `python` con `.venv/bin/python`):
+
 ```bash
-uv run genera.py config.toml                      # scrive output/gen_<seed>.csv, seed casuale
-uv run genera.py config.toml --seed 42            # riproducibile: output/gen_42.csv
-uv run genera.py config.toml -o dati/prova.csv    # percorso a scelta (cartelle create se mancano)
-uv run genera.py config.toml -o - > out.csv       # su stdout
+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 |
@@ -36,12 +46,12 @@ Stesso seed e stessa configurazione danno sempre lo stesso file. La cartella `ou
 ## Grafico
 
 ```bash
-uv run grafico.py                          # apre il grafico dell'ultimo CSV in output/
-uv run grafico.py output/gen_42.csv        # un CSV preciso
-uv run grafico.py -o grafico.png           # salva l'immagine (png, pdf, svg) invece di aprire la finestra
+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`), gestite da uv come per `genera.py`; senza schermo usa `-o`.
+Mostra `T` e `ΔT` in funzione del tempo. `grafico.py` ha le sue dipendenze (`numpy`, `matplotlib`), vedi sopra; senza schermo usa `-o`.
 
 ## Pulizia
 

docs/FUNZIONALITA.md

@@ -31,7 +31,7 @@ Formato dell'uscita: `t_ms,T_C,dT_C` (`t_ms` intero, gli altri a due decimali).
 
 ## Ambiente
 
-- Gli script girano con [uv](https://docs.astral.sh/uv/): le dipendenze (`numpy`, più `matplotlib` per il grafico) sono dichiarate nello script (PEP 723) e uv crea da solo l'ambiente virtuale.
+- 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.
 
 ## Riferimento dati reali

docs/SPEC.md

@@ -36,9 +36,9 @@ Nessun valore è scritto nello script: chiave mancante ⇒ errore.
    Poi arrotondamento a `passo_T_c`.
 5. **Ambiente e ΔT**: `amb_i = round_{amb_passo}( amb_inf + amb_A·exp(−t/τ_amb) + N(0, amb_sigma²) )`; `dT_i = round_{passo}( T_i − amb_i )`.
 
-## 4. Uso con uv (un solo file, nessun progetto)
+## 4. Uso (script unico, ambiente `.venv`)
 
-`genera.py` con dipendenza dichiarata in testa (PEP 723):
+`genera.py` con dipendenza dichiarata in testa (PEP 723, usata anche da `uv run`); ambiente `.venv` creato con `uv venv` e `uv pip install numpy`:
 ```python
 # /// script
 # requires-python = ">=3.11"
@@ -46,9 +46,9 @@ Nessun valore è scritto nello script: chiave mancante ⇒ errore.
 # ///
 ```
 ```bash
-uv run genera.py config.toml --seed 42                # riproducibile -> output/gen_42.csv
-uv run genera.py config.toml -o out.csv               # percorso a scelta, seed casuale (stampato su stderr)
-uv run genera.py config.toml -o - > out.csv           # stdout
+python genera.py config.toml --seed 42                # riproducibile -> output/gen_42.csv
+python genera.py config.toml -o out.csv               # percorso a scelta, seed casuale (stampato su stderr)
+python genera.py config.toml -o - > out.csv           # stdout
 ```
 Opzioni: `config` (posizionale), `-o/--output` (default `output/gen_<seed>.csv`, cartella creata se manca; `-` = stdout), `--seed` (default: casuale, stampato su stderr).
 Uscita con errore (exit 1) e messaggio in italiano se manca una chiave, se `t_impulsi_s` e `dT_impulsi_c` hanno lunghezze diverse