dewi-kadita: A Python Library for Idealized Fish Schooling Simulation with Entropy-Based Diagnostics
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--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.
Community
Simulating collective animal behavior requires robust tools to capture emergent complexity. This paper introduces dewi-kadita, an open-source Python library that implements the three-dimensional Couzin model for fish schooling. Unlike traditional tools that rely solely on polarization and rotation order parameters, this library introduces a suite of seven entropy-based metrics combined into a single Oceanic Schooling Index (OSI) to rigorously quantify collective disorder and differentiate between complex states like milling tori and dynamic parallel groups.
This is an automated message from the Librarian Bot. I found the following papers similar to this paper.
The following papers were recommended by the Semantic Scholar API
- Flocking phase transition and threat responses in bio-inspired autonomous drone swarms (2025)
- Non-reciprocal visual perception and polar alignment drive collective states in chiral active particles (2026)
- Collective behavior based on agent-environment interactions (2026)
- Transformer Learning of Chaotic Collective Dynamics in Many-Body Systems (2026)
- The Vicsek-Kuramoto model in collective dynamics: macroscopic equations and pattern formation (2025)
- Compressing Complexity: A Critical Synthesis of Structural, Analytical, and Data-Driven Dimensionality Reduction in Dynamical Networks (2026)
- FDA Flocking: Future Direction-Aware Flocking via Velocity Prediction (2026)
Please give a thumbs up to this comment if you found it helpful!
If you want recommendations for any Paper on Hugging Face checkout this Space
You can directly ask Librarian Bot for paper recommendations by tagging it in a comment:
@librarian-bot
recommend
Models citing this paper 0
No model linking this paper
Datasets citing this paper 0
No dataset linking this paper
Spaces citing this paper 0
No Space linking this paper
Collections including this paper 0
No Collection including this paper