dewi-kadita: A Python Library for Idealized Fish Schooling Simulation with Entropy-Based Diagnostics

Il paper presenta *dewi-kadita*, una libreria Python open-source per la simulazione di stormi di pesci in 3D che introduce sette nuovi parametri diagnostici basati sull'entropia e un indice di disordine (OSI) per caratterizzare l'auto-organizzazione collettiva in modo più preciso rispetto ai metodi classici.

L'essenziale

Il "Direttore d'Orchestra" dei Pesci: Presentazione di dewi-kadita

Avete mai guardato un enorme banco di pesci muoversi nell'oceano? Sembrano una singola creatura gigante, un organismo fluido che cambia forma, curva e scatta all'unisono senza che ci sia un "capo" che impartisce ordini. In scienza, questo fenomeno si chiama comportamento collettivo.

Il problema è che studiare questo "caos organizzato" è difficilissimo. Gli scienziati hanno bisogno di strumenti matematici per capire se un gruppo di pesci è in totale disordine o se sta seguendo una danza coordinata. È qui che entra in gioco dewi-kadita, una nuova libreria software (un insieme di strumenti digitali) creata da un team di ricercatori internazionali.

1. Il Modello: Il "Codice di Condotta" dei Pesci

Immaginate di organizzare una festa in una stanza buia. Per non scontrarvi e per stare insieme, potreste seguire tre regole semplici:

1. Zona di Repulsione (Il "Non toccarmi!"): Se qualcuno è troppo vicino, allontanati per evitare lo scontro.
2. Zona di Orientamento (Il "Seguiamo il ritmo"): Se qualcuno è a una distanza media, cerca di nuotare nella sua stessa direzione.
3. Zona di Attrazione (Il "Restiamo uniti"): Se qualcuno è lontano, nuota verso di lui per non restare solo.

Il software dewi-kadita simula migliaia di "pesci digitali" che seguono queste regole in uno spazio tridimensionale, permettendo agli scienziati di vedere come nascono le diverse forme di movimento (come i cerchi o le linee parallele).

2. La Diagnostica: L'Oroscopo della Complessità (ma scientifico!)

La vera innovazione di questo lavoro non è solo simulare i pesci, ma capire quanto sono "ordinati".

Fino ad oggi, gli scienziati usavano parametri molto semplici, come misurare solo quanto tutti nuotano nella stessa direzione. Ma questo è come giudicare la qualità di un'orchestra guardando solo se tutti suonano la stessa nota: non ti dice nulla sulla bellezza della sinfonia.

dewi-kadita introduce invece dei "termometri dell'ordine" basati sull'Entropia (un concetto che misura il disordine). Immaginate di avere sette diversi sensori:

• Uno misura quanto sono vicini i pesci (Coesione).
• Uno misura quanto è regolare la loro distribuzione verticale (Profondità).
• Uno misura quanto è "allungata" la forma del gruppo (Forma).
• E così via...

Tutti questi sensori vengono poi uniti in un unico punteggio chiamato OSI (Oceanic Schooling Index). È come un "voto finale" che dice: "Questo gruppo è un caos totale (voto alto)" oppure "Questo gruppo è una macchina perfetta di coordinazione (voto basso)".

3. La Potenza: Un Turbo per la Scienza

Simulare migliaia di interazioni tra pesci richiede una potenza di calcolo enorme. Se lo facessi con un programma normale, il computer impiegherebbe ore o giorni. Gli autori hanno usato una tecnologia chiamata Numba che agisce come un "turbo" per il motore del computer, rendendo le simulazioni fino a 100 volte più veloci. Questo permette di fare esperimenti complessi in pochi minuti, direttamente sul proprio computer da ufficio.

In sintesi: Perché è importante?

dewi-kadita è come aver costruito un laboratorio virtuale ultra-tecnologico dentro un computer. Invece di dover andare in mezzo all'oceano con reti e sensori costosi per osservare i pesci, gli scienziati possono ora creare mondi digitali perfetti, testare regole diverse e capire i segreti della vita collettiva con una precisione mai vista prima.

È uno strumento che aiuta a capire non solo i pesci, ma come qualsiasi gruppo di individui (dai batteri agli stormi di uccelli) riesce a trasformare il caos in bellezza organizzata.

Sommario tecnico

Riassunto Tecnico: dewi-kadita – Una libreria Python per la simulazione idealizzata del nuoto di banchi di pesci con diagnostica basata sull'entropia

1. Il Problema (Problem Statement)

Lo studio del movimento collettivo in sistemi di materia attiva (come i banchi di pesci) è fondamentale per comprendere l'auto-organizzazione emergente. Tuttavia, la ricerca attuale soffre di due limitazioni principali:

• Frammentazione degli strumenti: Gli strumenti computazionali per simulare il modello di Couzin (basato su zone di interazione) sono spesso codici proprietari o non standardizzati, rendendo difficile la riproducibilità e l'interoperabilità tra i gruppi di ricerca.
• Incompletezza diagnostica: I parametri d'ordine classici (polarizzazione $P$ e rotazione $M$) sono insufficienti per distinguere stati collettivi che presentano valori simili di $P$ e $M$ ma strutture spaziali o dinamiche interne profondamente diverse.

2. Metodologia (Methodology)

Gli autori presentano dewi-kadita, una libreria open-source in Python progettata per simulazioni tridimensionali del modello di Couzin.

• Modello Dinamico: Il modello implementa un'architettura a tre zone (Repulsione, Orientamento, Attrazione) con vincoli anatomici (campo visivo con zona cieca posteriore) e vincoli cinematici (velocità costante e velocità angolare limitata). La simulazione utilizza la topologia toroidale (condizioni al contorno periodiche) per simulare ambienti oceanici vasti.
• Implementazione Computazionale: Per superare l'inefficienza del calcolo delle interazioni a coppie ($O(N^2)$), la libreria utilizza la compilazione Just-In-Time (JIT) tramite Numba, ottenendo accelerazioni da 10 a 100 volte. Per la ricerca dei vicini più prossimi, viene impiegato il data structure k-d tree di SciPy.
• Framework Diagnostico: La novità principale è l'introduzione di un framework basato sulla teoria dell'informazione (entropia di Shannon) per caratterizzare l'organizzazione del banco.

3. Contributi Chiave (Key Contributions)

Il contributo principale è l'introduzione di sette metriche di entropia specializzate per la ricerca marina:

1. Cohesion Entropy ($H_{coh}$): Distribuzione delle distanze tra vicini più prossimi.
2. Polarization Entropy ($H_{pol}$): Dispersione delle orientazioni di velocità sulla sfera unitaria.
3. Depth Stratification Entropy ($H_{depth}$): Uniformità della distribuzione verticale (profondità).
4. Angular Momentum Entropy ($H_{ang}$): Contributi individuali al momento angolare collettivo.
5. Nearest-Neighbor Entropy ($H_{NN}$): Struttura della densità locale tramite coefficiente di variazione.
6. Velocity Correlation Entropy ($H_{vel}$): Distribuzione delle correlazioni di velocità tra coppie di agenti.
7. School Shape Entropy ($H_{shape}$): Variabilità morfologica tramite analisi delle componenti principali (PCA).

Queste metriche vengono aggregate nell'Oceanic Schooling Index (OSI), un singolo scalare che misura il disordine collettivo totale.

4. Risultati (Results)

La libreria è stata validata su quattro configurazioni canoniche: Swarm (sciame), Torus (milling/rotazione), Dynamic Parallel e Highly Parallel.

• Capacità Discriminante: L'OSI e le metriche di entropia sono riusciti a distinguere stati che i parametri classici non potevano separare. Ad esempio, il caso Torus e il caso Dynamic Parallel mostrano differenze nette nell'entropia di correlazione della velocità ($H_{vel}$) e nella forma ($H_{shape}$), nonostante valori di ordine simili.
• Performance: Le simulazioni di 150-250 agenti per 1000-2000 passi temporali sono state completate in circa 5 minuti su hardware standard.
• Validazione dei regimi:
  • Swarm: Alto disordine (OSI $\approx 0.71$).
  • Highly Parallel: Massima coerenza (OSI $\approx 0.24$, $H_{vel} \to 0$).

5. Significato e Impatto (Significance)

dewi-kadita colma il divario tra la fisica statistica e l'ecologia marina fornendo un'infrastruttura standardizzata.

• Standardizzazione: L'uso del formato NetCDF4 (conforme agli standard CF) garantisce che i dati siano pronti per l'analisi oceanografica professionale.
• Ricerca Avanzata: Il framework permette di studiare transizioni di fase, segnali di allerta precoce di cambiamenti comportamentali e la risposta dei banchi a gradienti ambientali (es. termoclini o correnti).
• Open Science: La natura open-source e l'archiviazione dei dati su OSF promuovono la riproducibilità e la collaborazione globale nella modellazione del comportamento collettivo.