EquationMiner/CLAUDE.md

CLAUDE.md

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

fitseg legge un CSV t_ms,T_C,dT_C (temperatura di un sensore IR che si scalda e si raffredda), lo divide in domini (riposo / riscaldamento = gradini di flusso in entrata / raffreddamento) e trova per ogni (dominio, serie) l'equazione che meglio lo approssima. Documentazione, commenti e messaggi sono in italiano: mantieni la lingua.

Fonti di verità (leggile prima di cambiare il comportamento, non duplicarne il contenuto):

• docs/SPEC.md — specifica, stato di implementazione (§1), algoritmi, limiti noti. docs/USO.md — uso pratico.
• config.toml — unica fonte dei valori. Nessun default nel codice: ogni chiave nuova va aggiunta a CHIAVI in src/fitseg/config.py (mancante ⇒ exit 3) e descritta in SPEC.md.

Comandi

uv venv .venv && uv pip install -e ".[dev]"
.venv/bin/fitseg domini dati/gen_1.csv                # propone i domini → lavoro/domini.toml
.venv/bin/fitseg analizza dati/gen_1.csv [--domini lavoro/domini.toml]   # → lavoro/out/ (report.md, modello_finale.json, fit_*.png)
.venv/bin/pytest                                      # tutti i test; singolo: .venv/bin/pytest -k raffreddamento

Opzioni globali --config/--lavoro vanno prima del sottocomando. lavoro/ è ignorato da git.

Dati

dati/gen_<seed>.csv sono prodotti dal repository fratello ../gen_data (.venv/bin/python genera.py config.toml --seed N -o ...). Sono i dati dei test: verità nota τ_raffreddamento = 1/k = 15.9 s (k perturbato del 2 % per seed), 3 gradini a ≈15.7/17.8/21.7 s, T ambiente ≈ 23 °C. Il generatore inserisce anche scarti casuali (≤ 4 °C) che rendono i residui autocorrelati: è un limite noto, non un bug del fit.

Architettura (src/fitseg/)

Flusso: domini.proponi → pipeline.analizza_domini (per ogni dominio e serie: fit.adatta su ogni modello abilitato → selezione.scegli) → riepilogo (report, JSON, grafici). cli.py è l'unico punto di I/O oltre a riepilogo/dati.

• domini.py: i domini derivano solo dai gradini positivi della serie_riferimento (diff > soglia_gradino_c), con arretramento ai campioni di transizione; non c'è più PELT/fusione BIC (presente nelle prime versioni della spec). domini.toml è modificabile e rientra con --domini; deve essere contiguo.
• modelli.py: registro MODELLI (funzione, parametri, equazione testuale, indici dei τ). Nuovo modello = voce qui + riga in SPEC §4.
• fit.py: least_squares con perdita robusta; gli esponenziali partono da una griglia su τ (VARPRO). "Non identificabile" = condizione > soglia o IC 95 % > |valore| per un parametro diverso dal primo; la logistica ha t_m limitato a [0, L] altrimenti degenera in esponenziale.
• pipeline.py: i domini di raffreddamento si fittano per primi e i loro c/tau vengono fissati nei domini di riscaldamento (riscaldamento_fissa_da_raffreddamento, adatta(..., fissi=)); i modelli provati dipendono dal tipo ([fit.modelli_per_tipo]).
• selezione.py: regola SPEC §5.3 (validi → adeguati se RMSE ≤ soglia·σ → entro ΔAICc vince chi ha meno parametri).
• σ del rumore è stimata per dominio da MAD(d²y); il tempo del fit è traslato a t' = t − t0 del dominio.

Gotcha

• scarta_dopo_salto_n deve coprire i campioni di transizione del sensore (τ_sensore 0.07 s, dt 0.15 s ⇒ ≥ 2–3 campioni); se troppo basso, 1–2 punti a ~100 °C dal fit sporcano la fine del dominio.
• Domini di riscaldamento di 14–26 campioni: τ non identificabile da solo, quindi è fisso al valore del raffreddamento; gli IC di A sono condizionati a quei fissi. Se il raffreddamento non è valido, il riscaldamento ricade sul fit libero e può risultare indeterminato.
• Cambiando config.toml del generatore (gradini, rumore) ricontrolla soglia_gradino_c e i test in tests/test_pipeline.py, che usano dati/gen_{1,2,3}.csv.
• Il parser CSV richiede la colonna tempo e tutte le serie in config; il tempo deve essere strettamente crescente (exit 4 altrimenti).
• Exit code: 0 ok · 2 uso · 3 config · 4 CSV · 6 domini non validi.