dewi-kadita: Una Libreria Python per la Simulazione Idealizzata di Banchi di Pesci con Diagnostiche Basate sull'Entropia

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

February 8, 2026

Autori: Sandy H. S. Herho, Iwan P. Anwar, Faruq Khadami, Alfita P. Handayani, Karina A. Sujatmiko, Kamaluddin Kasim, Rusmawan Suwarman, Dasapta E. Irawan

cs.AI

Abstract

Il moto collettivo nei banchi di pesci esemplifica l'auto-organizzazione emergente nei sistemi di materia attiva, tuttavia gli strumenti computazionali per simulare e analizzare queste dinamiche rimangono frammentati tra i gruppi di ricerca. Presentiamo dewi-kadita, una libreria Python open-source che implementa il modello tridimensionale basato sulle zone di Couzin con diagnostiche di entropia complete specifiche per la ricerca sul comportamento collettivo marino. La libreria introduce sette metriche teorico-informatiche – entropia di coesione del banco, entropia di polarizzazione, entropia di stratificazione in profondità, entropia del momento angolare, entropia del vicino più prossimo, entropia di correlazione delle velocità ed entropia della forma del banco – che caratterizzano distinti aspetti organizzativi inaccessibili ai parametri d'ordine classici. Queste metriche si combinano in un Indice di Sciamamento Oceanico (OSI) che fornisce una misura scalare unica del disordine collettivo. La validazione su quattro configurazioni canoniche (sciame, toro, parallelo dinamico, altamente parallelo) conferma la corretta riproduzione di comportamenti di fase noti: lo sciame mantiene il disordine con polarizzazione P < 0.1 e OSI ≈ 0.71, mentre lo stato altamente parallelo raggiunge P = 0.998 con OSI = 0.24 e l'entropia di correlazione delle velocità che si annulla. Il framework entropico distingue con successo le configurazioni a toro e parallelo dinamico, che mostrano magnitudini comparabili dei parametri d'ordine attraverso meccanismi organizzativi diversi. La compilazione just-in-time (JIT) di Numba accelera i calcoli delle interazioni a coppie di 10-100 volte, consentendo simulazioni di 150-250 agenti su 1000-2000 passi temporali entro cinque minuti su hardware workstation standard. L'output in formato NetCDF4 garantisce l'interoperabilità con gli strumenti di analisi oceanografica. La libreria risponde all'esigenza di un'infrastruttura standardizzata e riproducibile per la modellazione del comportamento collettivo, analoga ai codici consolidati per la dinamica molecolare.

English

Collective motion in fish schools exemplifies emergent self-organization in active matter systems, yet computational tools for simulating and analyzing these dynamics remain fragmented across research groups. We present dewi-kadita, an open-source Python library implementing the three-dimensional Couzin zone-based model with comprehensive entropy diagnostics tailored for marine collective behavior research. The library introduces seven information-theoretic metrics -- school cohesion entropy, polarization entropy, depth stratification entropy, angular momentum entropy, nearest-neighbor entropy, velocity correlation entropy, and school shape entropy -- that characterize distinct organizational features inaccessible to classical order parameters. These metrics combine into an Oceanic Schooling Index (OSI) providing a single scalar measure of collective disorder. Validation across four canonical configurations (swarm, torus, dynamic parallel, highly parallel) confirms correct reproduction of known phase behaviors: the swarm maintains disorder with polarization P < 0.1 and OSI approx 0.71, while the highly parallel state achieves P = 0.998 with OSI = 0.24 and velocity correlation entropy vanishing to zero. The entropy framework successfully discriminates the torus and dynamic parallel configurations that exhibit comparable order parameter magnitudes through different organizational mechanisms. Numba just-in-time (JIT) compilation accelerates pairwise interaction calculations by 10--100times, enabling simulations of 150--250 agents over 1000--2000 time steps within five minutes on standard workstation hardware. NetCDF4 output ensures interoperability with oceanographic analysis tools. The library addresses the need for standardized, reproducible infrastructure in collective behavior modeling analogous to established molecular dynamics codes.