docs/uso.md

# Uso

## 1. Installazione

Python ≥ 3.11 e [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`):

```bash
uv venv .venv
uv pip install -e ".[dev]"      # numpy, scipy, matplotlib; pytest e ruff per lo sviluppo
```
Il comando si chiama `fitseg`: `.venv/bin/fitseg`, oppure dopo `source .venv/bin/activate` semplicemente `fitseg`.

## 2. Dati di ingresso

I CSV da analizzare vanno nella cartella **`input/`** (la cartella è nel repository, i file `*.csv` no). Formato: intestazione, tempo
strettamente crescente, una colonna per serie, numeri senza celle vuote (A1, A2); i nomi delle colonne e l'unità del tempo sono in
`[dati]` di [config.toml](../config.toml) ([configurazione.md](configurazione.md)).

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

I CSV di prova si generano con il repository `gen_data` (modello: `extern/gen_data/docs/SPEC.md`), che non fa parte di questo repository: lo scarica
`./scarica_gen_data.sh` in `extern/gen_data` (cartella ignorata da git; `-u` lo aggiorna, `GEN_DATA_URL` cambia l'indirizzo, ad es. per SSH). Serve anche ai test di validazione ([test.md](test.md)). A ogni seed il generatore sorteggia numero dei gradini
(1–3), costante di tempo, rumore e disturbi: ogni file ha una struttura diversa.

```bash
./scarica_gen_data.sh
mkdir -p input
(cd extern/gen_data && ../../.venv/bin/python genera.py config.toml --seed 7 -o ../../input/gen_7.csv)
```
I test **non** richiedono questi file: generano i dati da soli ([test.md](test.md)).

## 3. Comandi

```bash
fitseg domini input/gen_7.csv      # passo 1: come verrebbero suddivisi i dati (tabella, domini.png, domini.toml), nessun fit
fitseg analizza input/gen_7.csv    # tutti i passi: domini, equazioni, sovrapposizione, report
fitseg analizza input/gen_7.csv --domini output/gen_7/01_domini/domini.toml   # con i domini corretti a mano
```

| Opzione | Dove | Significato |
|---|---|---|
| `--config PATH` | prima del sottocomando | file di configurazione (default `config.toml`) |
| `--output DIR` | prima del sottocomando | cartella madre dell'output (default `[output] cartella_output`); i file vanno in `DIR/<nome csv>/` |
| `--domini FILE` | solo `analizza` | usa questi domini invece della proposta automatica |

**Flusso consigliato**: lancia `fitseg domini`, guarda `01_domini/domini.png` (in particolare lo zoom); se la suddivisione è giusta lancia
`fitseg analizza`, altrimenti correggi `domini.toml` e rilancia con `--domini`.

### Correggere i domini a mano

Apri `output/<csv>/01_domini/domini.toml`, modifica `t0_s` / `t1_s` o il `tipo` (`riposo`, `riscaldamento`, `raffreddamento`), aggiungi o togli blocchi
`[[dominio]]`. I domini devono restare contigui. Formato e regole: [configurazione.md](configurazione.md) («domini.toml»). Con `--domini` il file viene
riscritto normalizzato e il grafico rigenerato, quindi `domini.png` mostra sempre la suddivisione effettivamente usata.

## 4. Cosa esce

Una cartella per CSV con `01_domini/`, `02_sovrapposizione/`, `03_report/report.md`: [output.md](output.md). Il report si apre con un visualizzatore Markdown
con supporto matematico (formule in LaTeX).

## 5. Codici di uscita

| Codice | Significato |
|---|---|
| 0 | ok |
| 2 | uso errato della riga di comando (argparse) |
| 3 | `config.toml` non valido: file illeggibile, TOML non valido, chiave mancante, valore non ammesso |
| 4 | CSV illeggibile o non valido (colonna mancante, valori non numerici, tempo non crescente) |
| 6 | `domini.toml` non valido (tipo non ammesso, intervallo vuoto, domini non contigui) |

Gli errori sono stampati su stderr in italiano come `Errore: …`.

## 6. Pulizia dei dati

```bash
./pulisci.sh                  # svuota output/ e cancella input/*.csv, chiede conferma
./pulisci.sh -n               # dry-run: mostra cosa cancellerebbe, senza cancellare
./pulisci.sh --solo-output    # pulisce solo output/, lascia input/ com'è
./pulisci.sh -y               # tutto, senza chiedere conferma
```
Cancella: il contenuto di `output/` (cartella di `[output] cartella_output`: risultati che si rifanno rilanciando `fitseg analizza`) e i file `*.csv` in `input/`
(i dati grezzi: **non** si rigenerano da soli, si rifanno con `./scarica_gen_data.sh` e `genera.py`, §2, per questo chiede conferma salvo `-y`). Le cartelle e i loro `.gitkeep`
restano; i file di `input/` che non sono `.csv` non si toccano. Rifiuta percorsi di output assoluti o con `..`. Codici di uscita: 0 ok (o niente da pulire), 1 annullato o
percorso non sicuro, 2 opzione sconosciuta.

## 7. Sviluppo

Test e controllo dello stile: [test.md](test.md). Mappa del codice e come aggiungere un modello: [moduli.md](moduli.md).