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

TL;DR

Dewi-kadita delivers an open-source framework for simulating three-dimensional fish schooling via the Couzin zone-based model and augments traditional metrics with seven entropy-based diagnostics to form the Oceanic Schooling Index (OSI). The approach combines a rigorous 3D agent-based formulation, NLERP-based orientation updates, and stochastic perturbations within a toroidal domain, with extensive validation across four canonical phases. The implementation emphasizes performance (Numba JIT speedups) and interoperability (NetCDF4 CF output), enabling reproducible, scalable analyses and cross-domain integration. The entropy framework provides richer, orthogonal characterization of collective states beyond polarization and rotation alone, enabling robust state classification and phase detection in time series. Overall, the work establishes a standardized, extensible computational toolset for marine collective behavior research with practical implications for ecological modeling and bio-inspired engineering.

Abstract

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$--$100\times$, 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.

Figures (4)

• Figure 1: Spatiotemporal evolution of collective states across four Couzin model scenarios. Rows correspond to distinct behavioral regimes: Swarm (a--c), Torus (d--f), Dynamic Parallel (g--i), and Highly Parallel (j--l). Columns represent temporal snapshots at initial ($t = 0$), middle ($t = T/2$), and final ($t = T$) simulation times. Three-dimensional quiver plots display fish positions with velocity vectors; instantaneous polarization $P$ and rotation $M$ values are annotated for each panel. The Swarm configuration maintains disordered aggregation throughout, while the Torus case transitions from initial milling ($M = 0.95$) toward partial alignment. Both Dynamic Parallel and Highly Parallel cases exhibit rapid ordering from random initial conditions to coherent directed motion ($P > 0.98$).
• Figure 2: Temporal evolution of classical order parameters for all four scenarios. Each panel displays polarization $P$ (solid lines) and rotation $M$ (dashed lines) as functions of time, with horizontal dotted lines indicating equilibrium mean values computed over the second half of each simulation. Panel annotations report final values. (a) Swarm: both parameters fluctuate near zero with no sustained ordering. (b) Torus: initial high rotation decays while polarization grows, indicating transition from milling toward partial alignment. (c) Dynamic Parallel: rapid convergence to $P \approx 0.98$ within $t \approx 30$ time units. (d) Highly Parallel: fastest convergence to near-unity polarization ($P = 0.998$) with minimal fluctuations ($\sigma_P = 0.0003$).
• Figure 3: Temporal evolution of oceanic entropy metrics across all scenarios. (a) School cohesion entropy $H_{\mathrm{coh}}$ based on nearest-neighbor distance distributions. (b) Polarization entropy $H_{\mathrm{pol}}$ quantifying velocity orientation spread on the unit sphere. (c) Velocity correlation entropy $H_{\mathrm{vel}}$ characterizing pairwise alignment distributions. (d) OSI, a weighted composite of all seven entropy metrics. Lower values indicate more ordered states. The Highly Parallel case achieves the lowest final OSI (0.24), while Swarm maintains elevated disorder (OSI $\approx 0.71$) throughout.
• Figure 4: Final state comparison of all metrics across scenarios. (a) Primary entropy metrics: school cohesion ($H_{\mathrm{coh}}$), polarization ($H_{\mathrm{pol}}$), and velocity correlation ($H_{\mathrm{vel}}$). (b) Secondary entropy metrics: depth stratification ($H_{\mathrm{depth}}$), angular momentum ($H_{\mathrm{ang}}$), nearest-neighbor variability ($H_{\mathrm{NN}}$), and school shape ($H_{\mathrm{shape}}$). (c) Composite indices: OSI and OI. (d) Classical order parameters: polarization ($P$) and rotation ($M$). The entropy metrics collectively distinguish all four phases, with OSI providing monotonic ranking from ordered (Highly Parallel, OSI $= 0.24$) to disordered (Swarm, OSI $= 0.71$).