Source-linked AI summary
dewi-kadita: A Python Library for Idealized Fish Schooling Simulation with Entropy-Based Diagnostics
Sandy H. S. Herho, Iwan P. Anwar, Faruq Khadami, Alfita P. Handayani, Karina A. Sujatmiko, Kamaluddin Kasim, Rusmawan Suwarman, Dasapta E. Irawan
TL;DR
Computational tools for three-dimensional fish-school simulation and entropy-based analysis remain fragmented and limited in their ability to capture rich organizational structure. Dewi-kadita provides an open-source Couzin-model framework with seven entropy diagnostics and an Oceanic Schooling Index, which discriminates four canonical collective phases beyond classical order parameters. Across validation scenarios, OSI ranks disorder from Highly Parallel (0.24) to Swarm (0.71), distinguishing Torus and Dynamic Parallel states with comparable classical order parameters.
Problem
Computational tools for simulating and analyzing Couzin-model dynamics remain fragmented, while entropy metrics for fish schooling have received limited attention despite schools’ complex three-dimensional organization.
Method
Dewi-kadita is an open-source Python library implementing three-dimensional Couzin-model simulation with seven specialized entropy metrics combined into an Oceanic Schooling Index.
Results
OSI ranks the four validated phases as Highly Parallel (0.24) < Dynamic Parallel (0.42) < Torus (0.44) < Swarm (0.71), distinguishing states with comparable classical order parameters.
Takeaways & Limitations
The entropy framework provides a validated basis for distinguishing collective phases that polarization and rotation measures alone cannot separate.
Takeaways & Limitations
The validation uses periodic boundaries and homogeneous conditions, while larger ensembles above 500 agents may require parallel computation and several environmental extensions remain future work.
Abstract
from arXiv · showhide
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.
1 Introduction
The introduction frames fish schooling as emergent collective behavior and identifies fragmented simulation infrastructure and incomplete classical diagnostics as key gaps. It presents dewi-kadita as an open-source Python framework combining three-dimensional Couzin-model simulation with entropy-based diagnostics for marine collective behavior.
- Background: Couzin’s three-zone architecture models collision avoidance, velocity alignment, and long-range cohesion through repulsion, orientation, and attraction regions.The model extends Vicsek-style alignment with graduated distance-dependent behavioral responses.
- Problem: Existing Couzin-model implementations remain fragmented, often consisting of unpublished laboratory codes without standardized interfaces, comprehensive diagnostics, or archival data formats.The introduction contrasts this situation with validated, documented, extensible molecular-dynamics community codes.
- Problem: Classical polarization P and rotation M describe alignment and milling but cannot fully distinguish configurations sharing identical values while differing in spatial, correlation, or morphological organization.The introduction motivates information-theoretic measures as richer organizational descriptors.
- Motivation: Entropy metrics address schooling features including density gradients, positional preferences, and shape variations that affect predator evasion, foraging efficiency, and hydrodynamic performance.The introduction notes that applying entropy metrics to fish schooling has received limited attention.
- Contribution: dewi-kadita provides an open-source Python framework for three-dimensional Couzin-model simulation with comprehensive entropy diagnostics tailored to marine collective behavior.The library implements visual-field constraints, bounded turning rates, stochastic perturbations, and seven specialized entropy metrics.
- Implementation: Numba JIT compilation accelerates pairwise interaction kernels to near-native speeds while preserving Python accessibility for rapid prototyping and collaborative development.This positions the library as both production infrastructure and a tool for research dissemination.
2 Model Description
The model represents fish as constant-speed, self-propelled agents in a three-dimensional periodic domain governed by Couzin’s zone-based interactions, visibility constraints, and bounded turning. It also defines seven entropy metrics and combines them into an Oceanic Schooling Index for characterizing school organization and disorder.
- Model and domain: Agents are self-propelled particles confined to a three-dimensional periodic domain, with periodic boundaries representing effectively unbounded oceanic environments.The domain has toroidal topology and finite size while modeling oceanic conditions.
- Zone-based interactions: The Couzin architecture uses three concentric zones: ZOR for collision avoidance, ZOO for velocity alignment, and ZOA for long-range cohesion.The zone radii obey 0 < rr < ro ≤ ra, ensuring unambiguous interaction classification.
- Visibility and neighborhoods: Interaction neighborhoods combine distance and visibility, excluding neighbors inside a posterior blind cone and creating an asymmetric interaction topology.The limiting cases are α = 0° for omnidirectional vision and α = 180° for a hemispherical forward-only field.
- Response dynamics: Collision avoidance has lexicographic priority, while orientation weight wo modulates alignment versus cohesion; turning is bounded by a maximum angular displacement θmax.The priority rule makes repulsion supersede social coordination, and bounded rotation prevents instantaneous reorientation.
- Entropy diagnostics: Seven specialized entropy metrics capture distinct aspects of school organization, and the OSI combines them into a composite measure of school disorder.Tight schools have low Hcoh, dispersed aggregations high Hcoh, aligned schools low Hpol, and isotropic velocity fields approach maximum entropy.
3 Numerical Implementation
dewi-kadita implements three-dimensional Couzin-model simulations in Python with high-performance numerical kernels, entropy diagnostics, and modular data and visualization tools. Its implementation uses efficient spatial and matrix-based computations, validates four canonical collective phases, and supports interoperable outputs.
- Library architecture: The library provides a Python implementation of three-dimensional Couzin dynamics with comprehensive diagnostic capabilities for fish-schooling simulations.Its architecture separates core dynamics, diagnostics, data handling, and visualization into distinct subpackages.
- Numerical acceleration: O(N^2) pairwise interaction evaluation is accelerated by Numba JIT compilation of zone membership, response accumulation, priority handling, and constrained rotation kernels.Pairwise interactions are the computational bottleneck in each time step.
- Entropy computation: The entropy diagnostics use periodic k-d tree nearest-neighbor calculations and matrix multiplication to efficiently compute all N(N −1)/2 unique velocity dot products.The velocity correlation entropy calculation forms VV⊤ for the N × 3 unit-velocity matrix and extracts upper-triangular elements.
- Validation cases: Four canonical test cases cover swarm, torus, dynamic parallel, and highly parallel collective regimes as validation benchmarks for distinct Couzin-model phase behaviors.Their configurations produce disordered aggregation, sustained rotation, fluctuating alignment, and stable directed motion, respectively.
- Data and visualization: CSV, CF-compliant NetCDF4, PNG, and GIF outputs support time-series analysis, complete trajectory archiving, static visualization, and animated three-dimensional trajectories.NetCDF4 files preserve dimensions, coordinate variables, global attributes, and complete simulation metadata.
4 Results and Discussion
Results validate dewi-kadita across four canonical collective states and show that entropy diagnostics distinguish organizational mechanisms beyond classical order parameters. The library also achieves practical workstation performance for moderate simulation sizes.
- Canonical-state validation: Four canonical Couzin phases were reproduced, including disordered Swarm, unstable Torus, and strongly aligned Dynamic Parallel and Highly Parallel states.The Swarm maintained both classical order parameters below 0.1, while the aligned configurations emerged from random initial conditions.
- Canonical-state validation: 0.998 was the Highly Parallel polarization P, compared with 0.98 for Dynamic Parallel, while school shape entropy was Hshape = 0.28 versus 0.99.The Highly Parallel school was elongated and anisotropic, whereas the Dynamic Parallel school was nearly spherical.
- Entropy diagnostics: Velocity correlation entropy Hvel fell to effectively zero in the Highly Parallel case, indicating perfect pairwise velocity alignment.The metric dropped from near-unity, where pairwise correlations were broadly distributed across [−1, 1].
- Entropy diagnostics: 0.24 was the Highly Parallel OSI, followed by Dynamic Parallel at 0.42, Torus at 0.44, and Swarm at 0.71.This entropy-based ranking distinguishes Torus from Dynamic Parallel despite their comparable classical order-parameter magnitudes.
5 Conclusion
dewi-kadita is a validated, open-source platform for three-dimensional Couzin model simulation that extends classical order-parameter diagnostics with a comprehensive entropy-based framework for marine collective behavior research. Validation across four canonical collective states confirms reproduction of known phase behaviors and demonstrates the value of seven oceanic entropy metrics.
- Validated platform: dewi-kadita provides a validated, open-source platform for three-dimensional Couzin model simulation.The library extends classical order-parameter diagnostics through an entropy-based framework.
- Entropy framework: Seven oceanic entropy metrics extend classical order-parameter diagnostics for marine collective behavior research.The framework is tailored specifically to marine collective behavior research.
- Systematic validation: Four canonical collective states validate reproduction of known phase behaviors: swarm, torus, dynamic parallel, and highly parallel.The systematic validation spans the four named collective configurations.