dewi-kadita: A Python Library for 3D Idealized Couzin Model Fish Schooling Simulation

Named after Kanjeng Ratu Kidul, the legendary Queen of the Southern Sea in Javanese mythology

A Python library for simulating fish schooling behavior using the 3D Couzin model with Numba JIT acceleration and comprehensive oceanic entropy metrics designed specifically for marine collective motion analysis.

Model

The Couzin model (2002) describes collective animal motion through three concentric behavioral zones around each individual:

Zone-Based Behavior

Each fish $i$ responds to neighbors based on their distance:

Zone of Repulsion (ZOR) — radius $r_r$: Collision avoidance takes priority $$\mathbf{d}i^{(r)} = -\sum{j \in ZOR} \frac{\mathbf{r}{ij}}{|\mathbf{r}{ij}|}$$

Zone of Orientation (ZOO) — radius $r_o > r_r$: Align with neighbors' headings $$\mathbf{d}i^{(o)} = \sum{j \in ZOO} \hat{\mathbf{v}}_j$$

Zone of Attraction (ZOA) — radius $r_a > r_o$: Move toward distant neighbors $$\mathbf{d}i^{(a)} = \sum{j \in ZOA} \frac{\mathbf{r}{ij}}{|\mathbf{r}{ij}|}$$

Update Rules

The desired direction combines zone responses with priority to repulsion:

$$\mathbf{d}_i = \begin{cases} \mathbf{d}_i^{(r)} & \text{if } |\mathbf{d}_i^{(r)}| > 0 \ \mathbf{d}_i^{(o)} + \mathbf{d}_i^{(a)} & \text{otherwise} \end{cases}$$

Velocity updates with angular noise and turning rate constraint $\theta_{max}$:

$$\mathbf{v}_i(t + \Delta t) = v_0 \cdot \text{rotate}(\hat{\mathbf{v}}_i, \mathbf{d}i, \theta{max}, \sigma)$$

Position updates with periodic boundaries:

$$\mathbf{r}_i(t + \Delta t) = \mathbf{r}_i(t) + \mathbf{v}_i(t + \Delta t) \cdot \Delta t$$

Key Parameters

Collective States

The Couzin model produces four distinct collective states:

Order Parameters

Polarization (alignment measure): $$P = \frac{1}{N} \left| \sum_{i=1}^{N} \hat{\mathbf{v}}_i \right|$$

Rotation (milling measure): $$M = \frac{1}{N} \left| \sum_{i=1}^{N} \hat{\mathbf{v}}_i \times \hat{\mathbf{r}}_i^c \right|$$

where $\hat{\mathbf{r}}_i^c$ is the unit vector from fish $i$ to the group centroid.

Oceanic Entropy Metrics

This library implements specialized information-theoretic measures designed for marine collective behavior:

Oceanic Schooling Index (OSI)

The composite metric specifically designed for fish school analysis:

$$\text{OSI} = w_1 H_{cohesion} + w_2 H_{polar} + w_3 H_{depth} + w_4 H_{angular} + w_5 H_{nn} + w_6 (1 - H_{vel}) + w_7 H_{shape}$$

where weights are optimized for marine schooling behavior assessment.

Installation

From PyPI:

pip install dewi-kadita

From source:

git clone https://github.com/sandyherho/dewi-kadita.git
cd dewi-kadita
pip install .

Development installation with Poetry:

git clone https://github.com/sandyherho/dewi-kadita.git
cd dewi-kadita
poetry install

Quick Start

CLI:

dewi-kadita case1          # Run swarm phase scenario
dewi-kadita case2          # Run torus/milling scenario
dewi-kadita case3          # Run dynamic parallel scenario
dewi-kadita case4          # Run highly parallel scenario
dewi-kadita --all          # Run all test cases
dewi-kadita case1 --no-entropy  # Skip entropy computation

Python API:

from dewi_kadita import CouzinSystem, CouzinSolver
from dewi_kadita import compute_metrics_timeseries

# Create system with 150 fish
system = CouzinSystem(
    n_fish=150,
    box_size=25.0,
    speed=1.0,
    r_repulsion=1.0,
    r_orientation=5.0,
    r_attraction=10.0,
    max_turn=0.3,
    noise=0.1,
    blind_angle=30.0
)

# Initialize solver with Numba acceleration
solver = CouzinSolver(dt=0.1, use_numba=True)

# Run simulation for 1000 steps
result = solver.solve(system, n_steps=1000)

# Compute oceanic entropy metrics
metrics = compute_metrics_timeseries(
    result['positions'],
    result['velocities'],
    result['time'],
    system.box_size
)

print(f"Final polarization: {result['final_polarization']:.4f}")
print(f"Final rotation: {result['final_rotation']:.4f}")
print(f"Final OSI: {metrics['oceanic_schooling_index_final']:.4f}")

Features

• High-performance: Numba JIT compilation for 10-100x speedup
• 3D simulation: Full three-dimensional fish schooling dynamics
• Couzin zones: Proper implementation of repulsion, orientation, attraction zones
• Blind angle: Realistic rear visual field limitation
• Maximum turning rate: Biologically realistic angular velocity constraint
• Oceanic entropy metrics: Specialized measures for marine collective behavior
• Multiple output formats: CSV, NetCDF (CF-compliant), PNG, GIF
• Stunning oceanic visualization: Deep sea aesthetic with bioluminescent effects
• Configurable scenarios: Text-based configuration files

Output Files

The library generates:

• CSV files:
  • *_order_parameters.csv - Polarization and rotation time series
  • *_entropy_timeseries.csv - All oceanic entropy measures over time
  • *_entropy_summary.csv - Statistics (mean, std, min, max, final)
  • *_final_state.csv - Final fish positions and velocities
• NetCDF: Full trajectory data with all metrics and CF-compliant metadata
• PNG: Static summary plots with oceanic entropy visualization
• GIF: Animated 3D visualization with underwater aesthetic

Dependencies

• numpy >= 1.20.0
• scipy >= 1.7.0
• matplotlib >= 3.3.0
• pandas >= 1.3.0
• netCDF4 >= 1.5.0
• numba >= 0.53.0
• Pillow >= 8.0.0
• tqdm >= 4.60.0

License

MIT 2026 © Sandy H. S. Herho, Iwan P. Anwar, Faruq Khadami, Alfita P. Handayani, Karina A. Sujatmiko, Kamaluddin Kasim, Rusmawan Suwarman, and Dasapta E. Irawan

Citation

@software{herhoEtAl2026_dewi_kadita,
  title   = {{\texttt{dewi-kadita}: A Python library for 3D idealized Couzin model fish schooling simulation}},
  author  = {Herho, Sandy H. S. and Anwar, Iwan P. and Khadami, Faruq and Handayani, Alfita P. and Sujatmiko, Karina A. and Kasim, Kamaluddin and Suwarman, Rusmawan and Irawan, Dasapta E.},
  year    = {2026},
  url     = {https://github.com/sandyherho/dewi-kadita}
}