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

O artigo apresenta a *dewi-kadita*, uma biblioteca Python de código aberto para simulação de cardumes de peixes baseada no modelo de Couzin, que utiliza métricas de entropia e aceleração via Numba para caracterizar de forma precisa e eficiente a organização e o desordem do movimento coletivo.

O essencial

O "Maestro Digital" dos Cardumes: Entendendo o projeto dewi-kadita

Imagine que você está em um grande estádio de futebol e, de repente, todos os torcedores começam a fazer a "ola". Ou imagine um enxame de abelhas que parece se mover como se fosse um único organismo gigante, mesmo que cada abelha esteja apenas seguindo regras simples de "não bata no vizinho" e "siga quem está perto".

Na natureza, os peixes fazem exatamente isso. Eles não têm um líder ou um general dando ordens; eles se organizam sozinhos através de interações locais. Isso é o que os cientistas chamam de "comportamento emergente".

O Problema: O caos é difícil de medir

Até agora, os cientistas que estudam esses movimentos tinham um problema: era como tentar descrever uma festa de carnaval usando apenas uma régua e um termômetro. Você consegue medir a temperatura e o tamanho da rua, mas não consegue medir a "vibe" da festa, a organização da dança ou o nível de bagunça de forma precisa.

As ferramentas de computador que existiam eram fragmentadas — cada grupo de pesquisadores tinha seu próprio "jeito" de simular, o que tornava difícil comparar os resultados.

A Solução: O dewi-kadita

Um grupo de pesquisadores criou o dewi-kadita, uma biblioteca de software (um conjunto de ferramentas digitais) que funciona como um simulador de ultra-alta definição para cardumes.

Pense no dewi-kadita como um jogo de videogame extremamente avançado, mas em vez de controlar um personagem, o cientista define as regras do mundo (como a velocidade dos peixes e o quanto eles se afastam uns dos outros) e deixa a simulação rodar para ver o que acontece.

O Diferencial: O "Termômetro de Bagunça" (Entropia)

A grande sacada deste trabalho não é apenas simular o movimento, mas sim medir a organização de um jeito novo. Eles criaram sete "sensores" especiais baseados em um conceito da física chamado Entropia.

Para entender a entropia, pense em um quarto:

• Baixa Entropia: É um quarto perfeitamente arrumado, onde cada meia está no seu par e cada livro na sua prateleira. Há muita ordem.
• Alta Entropia: É um quarto após uma festa de adolescentes. Meias, copos e papéis estão espalhados por todo lado. Há muita desordem.

O dewi-kadita usa esses sensores para dizer exatamente o quão "arrumado" ou "bagunçado" está o cardume. Ele consegue distinguir, por exemplo, se os peixes estão apenas nadando em círculos (como um redemoinho) ou se estão todos indo para a mesma direção (como uma migração organizada). Eles até criaram um índice único, o OSI (Índice de Cardume Oceânico), que dá uma nota de 0 a 1 para o nível de desordem do grupo.

Por que isso é importante?

1. Velocidade de Fórmula 1: Graças a uma tecnologia chamada Numba, o programa é incrivelmente rápido. Ele faz cálculos que levariam horas em poucos minutos.
2. Linguagem Universal: Ele salva os dados em formatos que outros cientistas do oceano já usam, como se estivesse escrevendo em uma língua que todos os oceanógrafos do mundo entendem.
3. Ciência Aberta: O código é gratuito e aberto. É como se eles tivessem inventado uma nova receita de bolo e compartilhado todos os ingredientes e o modo de preparo com o mundo para que todos possam cozinhar melhor.

Em resumo: O dewi-kadita é como um novo par de óculos de alta tecnologia para os cientistas marinhos. Com ele, eles não apenas veem o movimento dos peixes, mas conseguem "ler" a matemática invisível que mantém o cardume unido, ajudando a entender melhor como a vida funciona nos oceanos.

Resumo técnico

Resumo Técnico: Biblioteca dewi-kadita para Simulação de Cardumes

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

1. O Problema (Contexto e Motivação)

O estudo do movimento coletivo em sistemas de matéria ativa (como cardumes de peixes) é fundamental para entender a auto-organização emergente. Embora o modelo de Couzin (baseado em zonas de interação) seja o padrão teórico para simular esses comportamentos, a pesquisa enfrenta dois obstáculos principais:

• Fragmentação de Ferramentas: Não existe uma infraestrutura de software padronizada, documentada e interoperável para simulações de comportamento coletivo, ao contrário do que ocorre na dinâmica molecular (ex: LAMMPS).
• Limitação de Diagnósticos: Os parâmetros de ordem clássicos (Polarização $P$ e Rotação $M$) são insuficientes para distinguir estados coletivos que possuem valores similares de $P$ e $M$, mas estruturas organizacionais e morfológicas distintas.

2. Metodologia

Os autores desenvolveram a dewi-kadita, uma biblioteca de código aberto em Python que implementa o modelo de Couzin em três dimensões (3D).

• Modelo de Interação: Implementa uma arquitetura de três zonas concêntricas ao redor de cada agente:
  1. Zona de Repulsão (ZOR): Evita colisões.
  2. Zona de Orientação (ZOO): Alinhamento de velocidade.
  3. Zona de Atração (ZOA): Coesão do grupo.
     O modelo inclui restrições biológicas como campo de visão limitado (zona cega posterior), taxas de curva máxima e ruído estocástico.
• Implementação Computacional: Para superar a lentidão do Python em cálculos de interação par a par ($O(N^2)$), a biblioteca utiliza a compilação Just-In-Time (JIT) via Numba, permitindo aceleração de 10 a 100 vezes. A estrutura de dados espacial utiliza k-d trees (via SciPy) para otimizar buscas de vizinhos.
• Saída de Dados: Utiliza o formato NetCDF4 (compatível com padrões oceanográficos CF) para garantir a reprodutibilidade e interoperabilidade.

3. Principais Contribuições: O Framework de Entropia

A maior inovação do trabalho é a introdução de sete métricas baseadas na teoria da informação (entropia de Shannon) para caracterizar a organização do cardume:

1. Entropia de Coesão ($H_{coh}$): Distribuição das distâncias entre vizinhos próximos.
2. Entropia de Polarização ($H_{pol}$): Dispersão das orientações de velocidade na esfera unitária.
3. Entropia de Estratificação de Profundidade ($H_{depth}$): Uniformidade da posição vertical.
4. Entropia de Momento Angular ($H_{ang}$): Heterogeneidade das contribuições rotacionais individuais.
5. Entropia de Vizinho Próximo ($H_{NN}$): Estrutura de densidade local (variabilidade de distâncias).
6. Entropia de Correlação de Velocidade ($H_{vel}$): Distribuição de alinhamentos de pares de velocidade.
7. Entropia de Forma do Cardume ($H_{shape}$): Variabilidade morfológica via análise de componentes principais (PCA).

A partir dessas métricas, os autores definiram o Oceanic Schooling Index (OSI), um escalar único que mede o desordem coletiva total.

4. Resultados e Validação

A biblioteca foi validada através de quatro configurações canônicas do modelo de Couzin:

• Swarm (Enxame): Desordem total ($P \approx 0, M \approx 0$).
• Torus (Moinho/Milling): Movimento circular coerente.
• Dynamic Parallel (Paralelo Dinâmico): Alinhamento com flutuações.
• Highly Parallel (Altamente Paralelo): Alinhamento máximo e estável.

Conclusões dos resultados:

• Poder de Discriminação: O framework de entropia conseguiu distinguir estados que os parâmetros clássicos falharam (especialmente entre o estado Torus e o Dynamic Parallel).
• Eficiência do OSI: O índice OSI classificou os estados de forma monotônica, do mais ordenado (Highly Parallel, OSI $\approx 0.24$) ao mais desordenado (Swarm, OSI $\approx 0.71$).
• Desempenho: Simulações de até 250 agentes por 2000 passos de tempo foram concluídas em menos de cinco minutos em hardware padrão.

5. Significância

O trabalho preenche uma lacuna crítica na modelagem de sistemas biológicos ativos. Ao fornecer uma ferramenta que combina alta performance computacional com diagnósticos matemáticos sofisticados, a dewi-kadita permite que pesquisadores de ecologia marinha e física estatística realizem explorações de parâmetros mais profundas, comparem estudos de forma padronizada e integrem modelos computacionais com dados observacionais reais de oceanografia.