4.6 KiB
Uso
1. Installazione
Python ≥ 3.11 e uv (curl -LsSf https://astral.sh/uv/install.sh | sh):
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 (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). A ogni seed il generatore sorteggia numero dei gradini
(1–3), costante di tempo, rumore e disturbi: ogni file ha una struttura diversa.
./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).
3. Comandi
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 («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. 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
./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. Mappa del codice e come aggiungere un modello: moduli.md.