Simulazioni Idrauliche nel Browser Smoothed Particle Hydrodynamics

1. Introduzione

Questo documento racconta il progetto Lab SPH: un laboratorio di simulazioni idrauliche interattive, accessibile da qualsiasi browser, costruito con tecnologie web standard (JavaScript + Canvas HTML5) e sviluppato in collaborazione con un assistente AI (Claude, Anthropic).

L'idea nasce da una doppia curiosità: vedere cosa riesce a fare oggi un'intelligenza artificiale quando si tratta di scrivere codice scientifico vero, e tornare a giocare con la fluidodinamica computazionale dopo anni. Un Ph.D. in ingegneria idraulica porta con sé dei ricordi — sfumati con il tempo, ma ancora abbastanza nitidi da indicare la direzione giusta.

Il risultato è sorprendente. L'AI ha generato interamente il codice — sia la parte numerica SPH che l'interfaccia grafica — partendo da indicazioni tecniche: quali equazioni usare, quale metodo numerico, quale fisica simulare. Nessuna riga di codice scritta a mano. Solo idee, correzioni di rotta, e qualche bug da scovare insieme.

Nota bene: Le simulazioni di questo laboratorio sono realizzate per puro divertimento e curiosità scientifica. I risultati non hanno valore ingegneristico. Sono basate su letteratura scientifica consolidata, ma ottimizzate per comportarsi in modo visivamente realistico nel browser, non per riprodurre fedelmente casi di laboratorio specifici.

2. Il Metodo Numerico: SPH

2.1 Cos'è l'SPH — in parole semplici

Immagina di voler simulare l'acqua che scorre, ondeggia o cade. Il modo classico è dividere lo spazio in una griglia fissa (come i pixel di un'immagine) e calcolare in ogni casella come si muove il fluido. Funziona bene, ma ha un difetto: gestire superfici libere — la superficie dell'acqua che cambia forma — diventa complicato.

L'SPH (Smoothed Particle Hydrodynamics) fa il contrario: invece di una griglia, usa un insieme di particelle che si muovono con il fluido, ognuna con le sue proprietà (velocità, pressione, densità). È un metodo lagrangiano: le particelle seguono il moto del fluido, e la superficie libera emerge naturalmente da dove si trovano le particelle.

Il metodo fu inventato negli anni '70 per simulare fenomeni astrofisici (esplosioni stellari, formazione di galassie), e solo negli anni '90 è stato applicato all'idraulica. Oggi è usato per tsunami, sloshing nei serbatoi, onde frangifluite e molto altro.

2.2 Come funziona — la matematica semplificata

Ogni particella conosce la propria posizione, velocità e alcune proprietà fisiche. Ad ogni passo temporale, il programma calcola quanto ogni particella influenza le sue vicine, e aggiorna velocità e posizione di conseguenza.

L'influenza tra particelle diminuisce con la distanza, seguendo una funzione matematica chiamata kernel (nel nostro caso: cubic spline). È come una campanella smussata: al centro vale 1, ai bordi vale 0. Ogni particella sente solo le vicine entro un raggio h (lunghezza di smoothing).

Le equazioni fondamentali sono quelle della meccanica dei fluidi — conservazione della massa e della quantità di moto — riscritte in forma discreta per le particelle.

Equazione di stato (pressione)

P = B · [(ρ/ρ₀)^γ - 1] con γ = 7, B = ρ₀·cs²/γ
Dove ρ è la densità locale, ρ₀ la densità di riferimento, cs la velocità del suono artificiale. Questa è l'equazione di Tait, standard per WCSPH (Weakly Compressible SPH).

Viscosità artificiale (Monaghan 1992)

Per stabilizzare la simulazione e smorzare le oscillazioni numeriche, si aggiunge una viscosità artificiale tra coppie di particelle che si avvicinano. Il parametro α (alpha di Monaghan) controlla l'intensità: valori bassi danno un fluido più realistico, valori alti smorzano più rapidamente.

Integrazione temporale

Il moto viene aggiornato con uno schema Verlet a passo temporale adattivo. Il passo Δt è limitato dalla condizione CFL (Courant-Friedrichs-Lewy): le particelle non devono spostarsi di più di una lunghezza h per step. Nel codice: CFL = 0.4.

2.3 Condizioni al contorno — le Ghost Particles

Un problema classico dell'SPH: cosa succede alle particelle vicino ai bordi del dominio (pareti, fondo)? Senza una gestione speciale, le particelle si "perderebbero" fuori dal dominio.

La soluzione adottata è quella delle Ghost Particles (Colagrossi & Landrini, 2003): per ogni particella fluida vicina a una parete, viene creata una particella speculare virtuale oltre la parete stessa, con velocità riflessa. La pressione di questa particella fantasma respinge la particella reale verso l'interno. È un metodo elegante: non c'è nessuna forza artificiale esplicita, tutto emerge dalla fisica SPH applicata anche oltre il bordo.

2.4 XSPH — correzione per la coerenza del moto

L'XSPH (Monaghan, 1989) è una correzione al moto delle particelle: invece di muoversi esattamente alla loro velocità, si muovono a una velocità leggermente mediata con quella dei vicini (parametro ε, epsilon). Riduce il penetration tra particelle e migliora la coerenza del flusso — soprattutto utile nella fase di assestamento iniziale.

2.5 Implementazione tecnica

Linguaggio e ambiente: JavaScript puro (ES6+), Canvas HTML5. Nessuna libreria di fisica o GPU: tutto il calcolo gira sulla CPU del browser.

Neighbor search: Per trovare le particelle vicine entro il raggio h, viene usata una griglia spaziale (hash grid). Ad ogni step, le particelle vengono assegnate a celle della griglia; la ricerca dei vicini scorre solo le celle adiacenti.

Struttura del loop principale: Ad ogni frame (requestAnimationFrame), vengono eseguiti più sub-step SPH (da 1 a 8, controllati dal CFL) per garantire stabilità anche con frame rate variabile.

Colormap: Le particelle possono essere colorate per tipo di fluido (colore fisso) o per velocità (colormap plasma: blu-verde-giallo-bianco). La scala è calibrata sulla velocità caratteristica della simulazione.

Ghost particles dinamiche: I wall segments vengono ricostruiti ad ogni resize del canvas. Le ghost particles vengono rigenerate ad ogni sub-step SPH — non sono memorizzate, ma calcolate al volo dalla posizione delle particelle fluide vicine alle pareti.

3. Le Tre Simulazioni

3.1 SPH Calice — Riempimento di un Bicchiere

Idea e motivazione

La prima simulazione — e la più divertente da guardare. Un getto di liquido cade dall'alto dentro un bicchiere di forme diverse. Semplice nell'idea, ma ricco di fisica: il getto si curva, impatta, forma onde, trabocca. Perfetta come primo test del motore SPH.

Geometria e forme

Il bicchiere può essere di quattro tipi, tutti definiti da curve parametriche che descrivono il profilo interno:

• Calice: forma classica a calice di vino, con gambo stretto e coppa larga

• Flute: bicchiere da champagne, alto e stretto

• Tumbler: bicchiere basso e largo, cilindrico

La geometria è definita da segmenti che descrivono il profilo del bicchiere. Le ghost particles vengono generate dinamicamente lungo questi segmenti.

Efflusso — la bottiglia

Il liquido entra da un emitter posizionabile interattivamente. La velocità di uscita è calcolata con la formula di Torricelli: v = √(2·g·h), dove h è il dislivello tra il livello del liquido nella bottiglia e il buco di uscita. La direzione del getto segue l'orientamento della bottiglia, controllabile trascinando il mouse.

Le particelle vengono iniettate in fila alla frequenza giusta per mantenere un flusso continuo. L'età delle particelle (age) viene tracciata per evitare instabilità nelle prime iterazioni.

Interattività

• Selezione forma bicchiere (3 tipi)

• Posizione e inclinazione bottiglia con drag del mouse

• Densità fluido (acqua, olio, miele,...)

• Numero di particelle del getto

• Colorazione per tipo fluido o velocità

• Frecce velocità sulle particelle (toggle)

Commento personale

Il calice è la simulazione più immediata e soddisfacente visivamente. Il trabocco, le onde che rimbalzano sulle pareti, il getto che si incurva per gravità: tutto emerge spontaneamente dalla fisica SPH senza nessuna regola esplicita. Un ottimo test di correttezza qualitativa del motore.

3.2 Wave Maker SPH — Generazione di Onde

Idea e motivazione

Una vasca d'acqua con un pistone che oscilla su un lato: è il classico wave maker da laboratorio, usato in ingegneria costiera per testare strutture marine, protezioni da onde, dighe. Qui simulato in 2D con SPH.

Geometria del canale

Il canale può avere quattro sezioni diverse, che rappresentano diversi profili costieri:

• Rettangolare: pareti verticali, fondo piatto — il caso più semplice

• Costa dolce 1:20: rampa gentile sul lato sinistro, come una spiaggia sabbiosa

• Costa media 1:8: pendenza moderata

• Costa ripida 1:3: scarpata quasi verticale, come una costa rocciosa

Il pistone

Il pistone si muove orizzontalmente sul lato sinistro del canale, generando onde che si propagano verso destra e interagiscono con la costa. Quattro modalità di movimento:

• Sinusoidale: oscillazione cossenoide regolare — il caso più studiato in letteratura

• Asimmetrico: avanzata lenta (60%), ritirata rapida (40%) — riproduce il comportamento di onde marine reali

• Rampa: push + pausa + pull + pausa — genera onde separate e pulite

• Casuale: target random — simula mare irregolare

• Manuale: drag del mouse sul pistone — controllo diretto

La velocità del pistone è limitata alla velocità critica al pelo libero: v_c = √(g·h), dove h è il tirante. Questo corrisponde al numero di Froude = 1, la condizione di transizione tra corrente lenta e corrente veloce.

Frequenza naturale e risonanza

Per un canale chiuso, esiste una frequenza naturale di sloshing: f₁ = (1/2π)·√(π·g/L·tanh(π·h/L)). L'HUD mostra questa frequenza, quella di eccitazione del pistone, e il rapporto f/f₁. Quando si avvicina a 1 (risonanza), le onde crescono in ampiezza — l'HUD lo segnala in verde.

Parametri controllabili

• Frequenza pistone (0.05–0.50 Hz)

• Ampiezza pistone (1–15% larghezza canale)

• Velocità massima pistone (0.02–0.50 m/s)

• Tirante iniziale (30–75% altezza canale)

• Risoluzione SPH (da ~500 a 5000+ particelle)

• Viscosità α Monaghan (0.01–0.80)

• Correzione XSPH ε (0.0–0.9)

Commento personale

È la simulazione con cui sono meno soddisfatto — non per colpa dell'implementazione, ma perché conosco meno bene la fisica reale del wave maker sperimentale. Senza un riferimento di laboratorio da confrontare, è difficile capire se il comportamento è corretto o solo plausibile. Un limite onesto da ammettere ma anche non avevo tempo e voglia di studiare l'argomento.

3.3 Risalto Idraulico SPH — Stramazzo e Deflusso

Idea e motivazione

Il risalto idraulico è uno dei fenomeni più iconici dell'idraulica: una corrente veloce (corrente rapida, numero di Froude > 1) che, trovando un ostacolo o una variazione di quota, transisce bruscamente a corrente lenta (corrente lenta, Fr < 1), con una zona turbolenta di transizione. È l'ABC dell'ingegneria idraulica: chiunque abbia seguito un corso di idraulica l'ha studiato. Non simularlo sarebbe stato un peccato.

Schema fisico della simulazione

La simulazione riproduce uno schema classico da laboratorio:

• Vasca a monte (serbatoio): riempita di particelle ferme con pressione idrostatica. Battente costante: ogni volta che il pelo libero scende di un diametro particella, viene aggiunta una fila di particelle ferme (v=0) in cima — il metodo standard SPH per serbatoio a battente costante (Violeau, 2012)

• Paratoia verticale: separa la vasca dalla rampa. All'avvio, dopo 1 secondo di assestamento, si alza automaticamente aprendo una luce alla base. Le particelle escono per efflusso libero, spinte dalla pressione idrostatica — nessuna velocità imposta

• Rampa discendente: le particelle accelerano per gravità lungo la pendenza. Tre pendenze selezionabili: dolce 1:20, media 1:8, ripida 1:3

• Fondo piatto: zona di deflusso orizzontale prima dello stramazzo

• Stramazzo a parete sottile: ostacolo verticale che blocca il flusso. Le particelle si accumulano a monte, si alzano oltre la cresta e cadono a valle

• Canale a valle aperto: nessuna parete destra — le particelle che superano lo stramazzo cadono, rimbalzano sul fondo e scorrono fino ad uscire dal bordo

La portata specifica

L'HUD calcola in tempo reale la portata specifica q [l/s·m] — portata per metro di larghezza — usando la formula di Francis per stramazzo a parete sottile:

q = (2/3) · Cd · √(2g) · h^(3/2)
Con Cd = 0.611 (coefficiente di efflusso standard), h = carico idraulico sopra la cresta. La simulazione è 2D, quindi implica 1 metro di larghezza — il risultato è una portata specifica, non una portata assoluta. Ma non ho verificato che sia dimensionalmente corretta (è un gioco).

Parametri controllabili

• Pendenza rampa (dolce / media / ripida)

• Tirante iniziale nella vasca (regola il battente e la velocità di efflusso)

• Altezza stramazzo (10–35% del dislivello, default ~19%)

• Fluido (acqua / olio)

• Risoluzione SPH (da bassa ad altissima, default: livello 7)

• Viscosità α e XSPH ε

Output idraulici visualizzati

• Tirante a monte (cm)

• Tirante a valle (cm)

• Altezza stramazzo H (cm)

• Portata specifica q (l/s·m)

• Numero particelle attive

Commento personale

Questa è la simulazione che mi ha soddisfatto di più. L'efflusso spontaneo dalla paratoia, il flusso che accelera sulla rampa, l'accumulo a monte dello stramazzo e il trabocco: tutto fisicamente corretto e visivamente bello. È idraulica applicata, quella che conosco meglio nei canali e negli impianti.

4. L'Interfaccia e il Laboratorio

4.1 Hub — il Laboratorio

L'accesso alle simulazioni avviene tramite una pagina hub (lab.danielesturla.it) che presenta le tre simulazioni come card con anteprima SVG. Il design è dark, con palette navy/indigo, ispirato agli strumenti di analisi dati scientifici. Su smartphone appare un blocco che invita ad usare il desktop — le simulazioni richiedono potenza di calcolo e schermo largo.

4.2 Pannello di controllo

Ogni simulazione ha un pannello laterale con slider, bottoni e informazioni in tempo reale. Il pannello è progettato per essere compatto ma leggibile: etichette brevi, valori numerici aggiornati in tempo reale, colori coerenti con il tema visivo.

4.3 Frecce velocità

Un toggle attiva le frecce di velocità sulle particelle: ogni particella mostra una freccia bianca nella direzione del moto, con lunghezza proporzionale alla velocità. Le particelle quasi ferme non mostrano freccia — si evita il rumore visivo.

4.4 Colormap velocità

La colormap plasma (blu → verde → giallo → bianco) mappa la velocità delle particelle. La scala è calibrata dinamicamente sulla velocità caratteristica della simulazione — non sulla velocità massima assoluta, che creerebbe scale inutilizzabili.

4.5 Pannello Info Scientifico

Ogni simulazione ha un bottone ⓘ Info in basso a sinistra che apre un overlay con la descrizione del metodo numerico, i riferimenti bibliografici e il disclaimer. Stesso testo per tutte e tre le simulazioni.

5. Riflessioni Finali

5.1 Cosa ha funzionato bene

• Il motore SPH è sorprendentemente stabile per una simulazione browser

• L'efflusso per gravità nel risalto idraulico è fisicamente corretto

• La ghost particle approach gestisce bene geometrie complesse (bicchiere, rampa)

• L'interfaccia grafica è pulita e funzionale — merito dell'AI per la parte CSS/layout

• La ricerca dei vicini con hash grid mantiene le simulazioni fluide anche con 2000+ particelle

5.2 Limitazioni oneste

• La simulazione è 2D — molti fenomeni reali sono essenzialmente 3D

• Il wave maker non è stato confrontato con dati sperimentali

• I parametri SPH (α, ε, CFL) sono calibrati empiricamente per stabilità visiva, non validati quantitativamente

• L'equazione di stato WCSPH introduce una piccola comprimibilità artificiale

5.3 Il ruolo dell'AI

Cosa ha fatto l'AI (Claude, Anthropic): Ha scritto interamente il codice — il kernel SPH, la neighbor search, l'integrazione temporale, le ghost particles, le condizioni al contorno, l'interfaccia grafica, il debug. Ha interpretato le indicazioni tecniche e le ha tradotte in codice funzionante.
Cosa ho fatto io: Ho definito cosa simulare, ho scelto i metodi numerici da usare (WCSPH, Monaghan viscosity, ghost particles, Verlet + CFL), ho corretto la rotta quando il comportamento fisico non sembrava giusto, ho affinato la geometria e i parametri. Un orientamento che viene da un dottorato in ingegneria idraulica — con ricordi che si fanno più sfumati col tempo, ma ancora abbastanza nitidi da indicare la direzione giusta.
Per quanto riguarda la programmazione scntifica pura: meglio farlo da soli, se si ha il tempo e la voglia o se è il proprio lavoro. Ma per trovare bug, generare interfacce grafiche, e tenere insieme decine di migliaia di righe di codice scientifico? L'AI è straordinariamente efficace. Un piccolo esperimento per vedere fin dove arriva — e la risposta è: più lontano di quanto mi aspettassi.

6. Riferimenti Bibliografici

1. Monaghan, J.J. (1992) — Smoothed Particle Hydrodynamics. Annual Review of Astronomy and Astrophysics, 30, 543–574

2. Monaghan, J.J. (2005) — Smoothed particle hydrodynamics. Reports on Progress in Physics, 68(8), 1703–1759

3. Colagrossi, A. & Landrini, M. (2003) — Numerical simulation of interfacial flows by smoothed particle hydrodynamics. Journal of Computational Physics, 191(2), 448–475

4. Violeau, D. (2012) — Fluid Mechanics and the SPH Method: Theory and Applications. Oxford University Press

5. Dalrymple, R.A. & Rogers, B.D. (2006) — Numerical modeling of water waves with the SPH method. Coastal Engineering, 53(2–3), 141–147