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

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.

💡 Research Summary

The paper introduces dewi‑kadita, an open‑source Python library that implements the three‑dimensional Couzin zone‑based model for simulating fish schooling and provides a comprehensive suite of entropy‑based diagnostics. The authors note that while the Couzin model has become a standard theoretical framework for collective motion, existing implementations are scattered across individual research groups, lack standardized interfaces, and rely primarily on classical order parameters such as polarization (P) and milling (M). To address these gaps, dewi‑kadita offers a unified, well‑documented code base, accelerated with Numba just‑in‑time (JIT) compilation, and outputs results in CF‑compliant NetCDF4 files for seamless integration with oceanographic analysis tools.

Model core – Each agent is a self‑propelled particle moving at a constant speed v₀ in a periodic cubic domain. Interactions are organized into three concentric spherical zones: a Zone of Repulsion (ZOR) with radius rᵣ, a Zone of Orientation (ZOO) with radius rₒ, and a Zone of Attraction (ZOA) with radius rₐ. A visual field limitation is introduced via a blind‑cone half‑angle α, ensuring that agents only consider neighbors within a forward‑facing sector. The model follows the classic lexicographic priority rule: repulsion overrides all other cues, while orientation and attraction are combined using a weight wₒ that interpolates between alignment‑dominated and cohesion‑dominated dynamics. Angular turning is bounded by a maximum per‑step rotation θₘₐₓ, reflecting realistic fish maneuverability.

Entropy diagnostics – The library defines seven Shannon‑entropy metrics that capture distinct aspects of school organization:

1. Cohesion entropy – entropy of the nearest‑neighbor distance distribution, measuring overall density uniformity.
2. Polarization entropy – entropy of the velocity‑direction angle distribution, quantifying spread in alignment.
3. Depth stratification entropy – entropy of the vertical (z‑coordinate) distribution, detecting layering in three‑dimensional environments.
4. Angular momentum entropy – entropy of the distribution of per‑agent angular momentum, sensitive to milling or torus‑like rotation.
5. Nearest‑neighbor entropy – entropy of the local density field derived from each agent’s nearest‑neighbor distance.
6. Velocity‑correlation entropy – entropy of pairwise alignment angle distributions, reflecting long‑range correlation structure.
7. School‑shape entropy – entropy derived from the eigenvalue distribution of the positional covariance matrix (principal component analysis), characterizing morphological complexity.

These metrics are combined into a single scalar Oceanic Schooling Index (OSI) via a weighted average (weights are user‑definable). OSI ranges from 0 (perfectly ordered, e.g., highly parallel schooling) to 1 (maximally disordered, e.g., a swarm). The authors demonstrate that OSI can distinguish configurations that share similar classical order parameters but differ in internal structure.

Implementation and performance – Core interaction loops (pairwise distance, zone assignment, visual‑field masking) are JIT‑compiled with Numba, achieving speedups of 10–100× relative to pure Python. Benchmarks on a typical workstation (Intel i7‑10700K) show that simulations with 150–250 agents over 1,000–2,000 time steps complete within five minutes. Output is written as NetCDF4 variables with CF metadata, enabling immediate use with xarray, Panoply, or other climate‑data tools and satisfying FAIR data principles.

Validation – Four canonical collective states are reproduced by varying model parameters:

• Swarm – low polarization (P < 0.1), high OSI (~0.71), all entropy measures elevated, indicating disorder.
• Torus (milling) – moderate polarization (P ≈ 0.3) and high milling (M ≈ 0.8), high angular‑momentum entropy, OSI ≈ 0.55.
• Dynamic parallel – intermediate polarization (P ≈ 0.6), moderate OSI (~0.45), distinct velocity‑correlation and shape entropies that separate it from the torus despite similar P and M values.
• Highly parallel – near‑perfect alignment (P = 0.998), low OSI (0.24), velocity‑correlation entropy essentially zero, confirming a highly ordered state.

These results confirm that the entropy suite captures subtle organizational differences missed by P and M alone, particularly distinguishing torus and dynamic parallel regimes.

Discussion and future work – The authors acknowledge current limitations: the model does not incorporate fluid dynamics, external environmental gradients (e.g., currents, temperature), or non‑periodic boundaries, and the OSI weighting scheme is heuristic. They propose extensions such as coupling with CFD solvers, Bayesian parameter inference, direct comparison with high‑resolution video tracking data, and GPU acceleration to enable simulations of thousands of agents.

Conclusion – dewi‑kadita fills a critical gap in collective‑behavior research by delivering a standardized, high‑performance simulation platform together with a rich, information‑theoretic diagnostic framework. By making the code open, well‑documented, and interoperable with existing oceanographic data standards, the library promises to accelerate reproducible research, facilitate cross‑disciplinary collaborations (e.g., robotics, ecology, physics), and deepen quantitative understanding of the emergent order in marine animal groups.