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

The paper introduces *dewi-kadita*, an open-source Python library that implements a 3D Couzin-based fish schooling model enhanced by a novel suite of seven entropy-based metrics and an Oceanic Schooling Index (OSI) to provide a more nuanced characterization of collective organization than traditional order parameters.

The Gist

The "Digital Fish School" Project: Making Sense of the Swarm

Imagine you are standing on a pier, watching a massive school of fish dart through the water. One second they are a loose, chaotic cloud; the next, they snap into a perfect, shimmering arrow, moving as if they share a single mind.

How do they do it? How do thousands of individual fish—each with its own tiny brain—coordinate such complex "group dances" without a leader shouting orders?

Scientists have been trying to model this for decades, but they’ve had a problem: they had the "math" to simulate the movement, but they didn't have a good "ruler" to measure the quality of the dance.

That is where dewi-kadita comes in.

---

The Problem: The "Blurry Ruler"

Before this paper, scientists used two main tools to measure fish schools: Polarization (are they all facing the same way?) and Rotation (are they swimming in a circle?).

Think of it like judging a synchronized swimming team. If you only look at whether everyone is facing North, you might think they are doing a great job. But you might miss the fact that they are all spaced too far apart, or that half of them are swimming at different depths. The old "rulers" were too blurry; they could tell you if the group was moving, but they couldn't tell you how organized the group actually was.

The Solution: The "Entropy Toolkit"

The creators of dewi-kadita (a new Python software library) decided to borrow a concept from physics called Entropy. In simple terms, entropy is a measure of disorder or "messiness."

Instead of just two measurements, they created seven specialized "messiness detectors" (Entropy Metrics). Imagine these as different types of high-tech sensors:

1. The Social Distancing Sensor (Cohesion Entropy): Are the fish huddled too close, or are they spread out like a messy crowd at a concert?
2. The Compass Sensor (Polarization Entropy): Are they all pointing North, or is everyone pointing in a random direction?
3. The Elevator Sensor (Depth Entropy): Are they all swimming at the same level, or are they scattered from the surface to the bottom?
4. The Merry-Go-Round Sensor (Angular Momentum Entropy): Is the "circle dance" smooth, or is it wobbling?
5. The Neighbor Sensor (Nearest-Neighbor Entropy): Is the spacing between fish regular (like soldiers on parade) or irregular (like people in a grocery store line)?
6. The Buddy-System Sensor (Velocity Correlation Entropy): If one fish turns, do its neighbors turn with it?
7. The Shape Sensor (Shape Entropy): Is the school a neat sphere, or a long, stretched-out cigar shape?

By combining these seven sensors, they created the Oceanic Schooling Index (OSI). This is a single "Master Score" from 0 to 1.

• A score near 0 means a perfectly choreographed ballet.
• A score near 1 means a chaotic, unorganized swarm.

The "Turbo-Charged" Engine

Simulating hundreds of fish is hard work for a computer because every single fish has to "check in" with every other fish to see how close they are. It’s like trying to organize a dinner party where every guest has to constantly ask every other guest, "Are you sitting too close to me?"

To prevent the computer from crashing or slowing down, the researchers used a technology called Numba. Think of this as giving the computer a "super-brain" that allows it to do these millions of tiny calculations 10 to 100 times faster than usual. This allows scientists to run complex simulations in minutes rather than hours.

Why does this matter?

This isn't just about playing with digital fish. By having a standardized, high-speed, and incredibly precise way to measure "group intelligence," scientists can:

• Understand Marine Life: Better predict how real fish schools react to predators or changing ocean temperatures.
• Build Better Robots: Help engineers design "swarms" of tiny underwater robots that can work together to explore the deep ocean.
• Study Complex Systems: Use the same math to understand how birds flock, how insects swarm, or even how cells move in the human body.

In short: dewi-kadita provides the high-definition glasses that scientists need to finally see the true patterns hidden within the chaos of the sea.

Technical Summary

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

1. Problem Statement

The study of collective motion in biological systems (e.g., fish schooling) is a cornerstone of active matter physics and marine ecology. However, the authors identify two critical gaps in the current research landscape:

• Fragmented Computational Tools: Unlike molecular dynamics (which benefits from standardized codes like LAMMPS), simulations of fish schooling are often implemented in isolated, unpublished, and non-standardized laboratory codes. This lack of infrastructure hinders reproducibility and cross-study comparisons.
• Incomplete Diagnostic Metrics: Classical order parameters—specifically Polarization ($P$) for alignment and Rotation ($M$) for milling—are insufficient for fully characterizing complex collective states. Two different organizational structures can exhibit identical $P$ and $M$ values, masking subtle differences in spatial structure, velocity correlations, or morphology.

2. Methodology

The authors developed dewi-kadita, an open-source Python library designed to provide a standardized, high-performance framework for 3D schooling simulations.

• Simulation Model: The library implements a three-dimensional Couzin zone-based model. This agent-based model uses a hierarchical interaction architecture consisting of three concentric zones:
  • Zone of Repulsion (ZOR): Collision avoidance.
  • Zone of Orientation (ZOO): Velocity alignment.
  • Zone of Attraction (ZOA): Long-range cohesion.
    The model incorporates biological constraints such as a conical blind zone (posterior vision limitation), bounded turning rates (physiological limits), and stochastic noise (environmental/sensory uncertainty).
• Computational Implementation:
  • Performance: To overcome the $O(N^2)$ complexity of pairwise interactions, the library utilizes Numba Just-In-Time (JIT) compilation, achieving 10–100× speedups.
  • Spatial Efficiency: It employs SciPy’s cKDTree for accelerated nearest-neighbor queries.
  • Data Standards: Outputs are provided in NetCDF4 format (CF-compliant) to ensure interoperability with oceanographic tools, alongside CSV and animated GIF formats.
• Entropy-Based Diagnostics: The core innovation is the introduction of seven information-theoretic metrics to quantify organizational complexity:
  1. Cohesion Entropy ($H_{coh}$): Nearest-neighbor distance distribution.
  2. Polarization Entropy ($H_{pol}$): Spread of velocity orientations on a sphere.
  3. Depth Stratification Entropy ($H_{depth}$): Vertical position uniformity.
  4. Angular Momentum Entropy ($H_{ang}$): Distribution of rotational contributions.
  5. Nearest-Neighbor Entropy ($H_{NN}$): Local density/spacing regularity.
  6. Velocity Correlation Entropy ($H_{vel}$): Pairwise alignment distributions.
  7. School Shape Entropy ($H_{shape}$): Morphological anisotropy via PCA.
  • These are aggregated into a single scalar: the Oceanic Schooling Index (OSI).

3. Key Contributions

• A Standardized Software Framework: Provides a reproducible, high-performance, and extensible platform for collective behavior modeling.
• New Diagnostic Suite: Moves beyond first-moment statistics (like $P$ and $M$) to full-distribution characterization using Shannon entropy.
• The Oceanic Schooling Index (OSI): A composite metric that provides a monotonic measure of collective disorder.
• FAIR Data Compliance: Ensures research outputs are Findable, Accessible, Interoperable, and Reusable through standardized data formats.

4. Results and Validation

The library was validated against four canonical Couzin model phases: Swarm, Torus (milling), Dynamic Parallel, and Highly Parallel.

• Phase Discrimination: While classical parameters ($P, M$) struggled to distinguish between the Torus and Dynamic Parallel states, the entropy metrics successfully discriminated them.
• Metric Sensitivity:
  • $H_{vel}$ (Velocity Correlation Entropy) proved highly sensitive, dropping to near zero in the Highly Parallel state, indicating perfect pairwise correlation.
  • $H_{shape}$ successfully identified the elongated morphology of highly parallel schools.
• OSI Performance: The OSI provided a clear, monotonic ranking of disorder:
  $$\text{Highly Parallel (0.24)} < \text{Dynamic Parallel (0.42)} < \text{Torus (0.44)} < \text{Swarm (0.71)}$$
• Computational Efficiency: Simulations of up to 250 agents over 2000 time steps were completed within approximately five minutes on standard workstation hardware.

5. Significance

The dewi-kadita library bridges the gap between statistical physics and marine ecology. By providing a robust toolset for simulating and quantifying complex biological motion, it enables researchers to perform large-scale parameter sweeps, detect phase transitions, and analyze real-world observational data with a level of mathematical rigor previously reserved for molecular dynamics. It serves as foundational infrastructure for future studies involving heterogeneous populations, predator-prey dynamics, and oceanic current interactions.