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 fascetta (anello cilindrico sottile) riscaldata da sorgenti a induzione in movimento.

Geometria: la fascetta ha diametro, spessore e lunghezza configurabili. Il dominio simulato è la sezione rettangolare lunghezza × spessore, con origine (0, 0) nel vertice in alto a sinistra: x = lunghezza (le sorgenti si muovono in direzione -x sul lato esterno), z = spessore (0 = lato esterno, spessore = lato interno). La coordinata circonferenziale y non è risolta: l'offset y delle sorgenti è collassato in un'attenuazione gaussiana del flusso. Il sensore è un pirometro a infrarossi dentro la fascetta che misura la superficie interna in un punto x fisso.

Flusso dei dati:

1. config.py — tutti i parametri configurabili (dizionari SIMULAZIONE, FASCETTA, 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)
• Le sorgenti gaussiane in movimento producono un profilo di flusso termico superficiale q(x) sul lato esterno, variabile nel tempo (profilo_flusso_incidente_W_m2)
• Quel flusso è ridistribuito volumetricamente attraverso lo spessore con decadimento esponenziale in z (profilo_deposizione_z_1_m): q_vol(x, z) = q(x) · p(z)
• Uno schema 2D a volumi finiti con Eulero implicito integra l'equazione del calore su n_nodi_x × n_nodi_z celle: prepara_stato_termico costruisce griglia, coefficienti e matrice sparsa fattorizzata LU una volta per run (costruisci_solutore_implicito_2d, che restituisce l'oggetto splu), poi passo_implicito avanza il campo risolvendo solo il sistema triangolare
• Le condizioni al contorno sono incorporate nella matrice: convezione su tutti e quattro i lati della sezione, più un termine di conduzione circonferenziale (y) verso il resto della fascetta assunto a temperatura ambiente. Il termine è un'equazione di aletta ricavata sull'intero volume del cilindro: il calore conduce lungo y attraverso l'intero spessore mentre le superfici esterna e interna dell'intero cilindro scambiano per convezione, dando q_y = -(h_esterno + h_interno)/spessore · (T - T_amb), senza parametri di conduzione y configurabili a parte
• La temperatura iniziale del campo è la temperatura ambiente (randomizzata per run)
• L'output del sensore aggiunge inerzia del primo ordine, rumore gaussiano e quantizzazione

prepara_stato_termico e passo_implicito sono condivisi con plot_animazione.py, che riproduce la fisica di run_0001 per animare la sezione: ogni modifica alla fisica va fatta lì, non duplicata.

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 è 2D nella sezione (x = lunghezza, z = spessore). La coordinata circonferenziale y non è risolta spazialmente — l'offset y del percorso delle sorgenti è collassato in un'attenuazione gaussiana del flusso, e la conduzione lungo y è un termine di scambio lineare verso la temperatura ambiente; il diametro è registrato solo come geometria del setup.
• Le posizioni di inizio/fine corsa delle sorgenti (x_inizio_m, x_fine_m) sono distanze dal punto x del sensore lungo il verso di marcia; il segno di velocita_m_s determina il verso (negativo = -x).
• La matrice implicita è costruita e fattorizzata 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 e rifattorizzata 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 FASCETTA["materiale"] in config.py.