simulatore-induttori/CLAUDE.md

CLAUDE.md

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

Lingua

L'utente comunica in italiano. Tutto il codice, i commenti, la documentazione e i messaggi di commit devono essere scritti in italiano.

Comandi

Usare sempre il virtual environment:

# Creare e attivare il venv (prima volta)
python -m venv .venv
source .venv/bin/activate

# Installare le dipendenze
pip install -r requirements.txt

# Generare il dataset (scrive dataset/run_XXXX.csv + dataset/metadata.csv)
python simulate.py

# Visualizzare il primo run
python plot_csv.py

Attivare sempre il venv (source .venv/bin/activate) prima di eseguire qualsiasi comando Python.

Non sono configurati test o linter.

Architettura

Generatore di dataset per misurazioni termiche pseudo-realistiche di una piastra riscaldata da una sorgente a induzione in movimento.

Flusso dei dati:

1. config.py — tutti i parametri configurabili (dizionari SIMULAZIONE, PIASTRA, ARIA, SORGENTE, SENSORE, RANDOMIZZAZIONE)
2. materials.py — dizionario MATERIALI con proprietà termofisiche ed elettriche per materiale
3. simulate.py — motore principale: genera N run randomizzati, scrive i CSV, scrive metadata.csv
4. plot_csv.py — visualizzazione autonoma per un singolo run

Pipeline fisica dentro simula_singolo() in simulate.py:

• La skin depth è calcolata dalla resistività elettrica del materiale e dalla frequenza di induzione (calcola_skin_depth_m)
• La sorgente gaussiana in movimento è proiettata sulla linea del sensore fisso per produrre un flusso termico superficiale variabile nel tempo (flusso_termico_incidente_W_m2)
• Quel flusso è ridistribuito volumetricamente attraverso lo spessore con decadimento esponenziale (riscaldamento_volumetrico_W_m3)
• Uno schema 1D a volumi finiti con Eulero implicito integra l'equazione del calore su n_nodi celle (costruisci_matrice_implicita, poi np.linalg.solve ad ogni passo)
• Le condizioni al contorno di convezione sono incorporate nella matrice
• L'output del sensore aggiunge inerzia del primo ordine, rumore gaussiano e quantizzazione

Randomizzazione per run (configurazione_randomizzata): ogni run perturba velocità, flusso di picco, sigma del punto, offset y, temperatura ambiente e rumore del sensore con estrazioni gaussiane/uniformi da un RNG con seed fisso, garantendo riproducibilità.

Schema di output (dataset/run_XXXX.csv): serie temporale con colonne id_run, tempo_s, x_sorgente_m, offset_y_sorgente_m, flusso_termico_sorgente_W_m2, skin_depth_m, T_vera_lato_sensore_C, T_misurata_sensore_C, T_lato_caldo_C, T_ambiente_C, velocita_m_s, sigma_punto_m, flusso_picco_W_m2, materiale. metadata.csv ha una riga per run con tutti i parametri e le temperature di picco.

Convenzioni su config.py

Ogni parametro in config.py ha un commento che spiega solo cos'è (il suo significato fisico/funzionale), mai perché è impostato a un valore specifico. Quando si modifica un parametro per ottenere un certo comportamento (es. una velocità diversa, un range di temperatura target), va cambiato solo il valore: non aggiungere commenti che giustificano o motivano quel valore, perché diventano obsoleti/fuorvianti alla prossima modifica.

Vincoli progettuali chiave

• Il modello è strettamente 1D (solo attraverso lo spessore). Il movimento laterale dell'induttore non è risolto spazialmente — è collassato in un flusso scalare variabile nel tempo sulla linea del sensore.
• costruisci_matrice_implicita è calcolata una volta per run (proprietà del materiale costanti, nessun coefficiente dipendente dalla temperatura). Se si aggiungono proprietà dipendenti dalla temperatura, la matrice deve essere ricostruita ad ogni passo temporale.
• simulate.py cancella e ricrea l'intera cartella di output ad ogni esecuzione (shutil.rmtree).
• Aggiungere un nuovo materiale richiede solo una nuova voce nel dizionario MATERIALI in materials.py; la chiave del materiale va poi impostata in PIASTRA["materiale"] in config.py.