dewi-kadita: Uma Biblioteca Python para Simulação Idealizada de Cardumes com Diagnósticos Baseados em Entropia
dewi-kadita: A Python Library for Idealized Fish Schooling Simulation with Entropy-Based Diagnostics
February 8, 2026
Autores: Sandy H. S. Herho, Iwan P. Anwar, Faruq Khadami, Alfita P. Handayani, Karina A. Sujatmiko, Kamaluddin Kasim, Rusmawan Suwarman, Dasapta E. Irawan
cs.AI
Resumo
O movimento coletivo em cardumes exemplifica a auto-organização emergente em sistemas de matéria ativa, porém as ferramentas computacionais para simular e analisar essas dinâmicas permanecem fragmentadas entre grupos de pesquisa. Apresentamos dewi-kadita, uma biblioteca Python de código aberto que implementa o modelo tridimensional baseado em zonas de Couzin com diagnósticos de entropia abrangentes adaptados para a pesquisa do comportamento coletivo marinho. A biblioteca introduz sete métricas de teoria da informação – entropia da coesão do cardume, entropia da polarização, entropia da estratificação por profundidade, entropia do momento angular, entropia do vizinho mais próximo, entropia da correlação de velocidades e entropia da forma do cardume – que caracterizam características organizacionais distintas inacessíveis a parâmetros de ordem clássicos. Essas métricas se combinam em um Índice de Agregação Oceânica (IAO) que fornece uma medida escalar única de desordem coletiva. A validação em quatro configurações canônicas (enxame, toro, paralelo dinâmico, altamente paralelo) confirma a reprodução correta de comportamentos de fase conhecidos: o enxame mantém desordem com polarização P < 0,1 e IAO ≈ 0,71, enquanto o estado altamente paralelo atinge P = 0,998 com IAO = 0,24 e a entropia da correlação de velocidades tendendo a zero. O arcabouço de entropia discrimina com sucesso as configurações de toro e paralelo dinâmico, que exibem magnitudes comparáveis de parâmetros de ordem através de diferentes mecanismos organizacionais. A compilação just-in-time (JIT) do Numba acelera os cálculos de interações pareadas em 10 a 100 vezes, permitindo simulações de 150 a 250 agentes ao longo de 1000 a 2000 passos de tempo em até cinco minutos em hardware padrão de estação de trabalho. A saída em NetCDF4 garante interoperabilidade com ferramentas de análise oceanográfica. A biblioteca atende à necessidade de infraestrutura padronizada e reproduzível na modelagem de comportamento coletivo, análoga aos códigos estabelecidos de dinâmica molecular.
English
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.