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

Presentamos *dewi-kadita*, una biblioteca de Python de código abierto que simula el movimiento colectivo de peces mediante el modelo de Couzin en 3D e introduce un novedoso marco de diagnóstico basado en la entropía para caracterizar la organización de los bancos de peces de manera más precisa que los parámetros de orden clásicos.

Lo esencial

El "Director de Orquesta" de los Peces: Presentando dewi-kadita

¿Alguna vez has visto un banco de peces moviéndose en el océano? Parecen una sola criatura gigante, una especie de "superorganismo" que gira, se estira y esquiva peligros con una coordinación casi mágica. Lo más increíble es que no hay un líder; no hay un "pez jefe" gritando órdenes. Todo sucede por pura matemática y reglas locales.

El problema es que, para los científicos, estudiar este baile es como intentar entender una coreografía compleja mirando solo a través de una cerradura. Los métodos actuales son fragmentados y a veces se quedan cortos para describir la verdadera "personalidad" del grupo.

Aquí es donde entra dewi-kadita, una nueva herramienta digital (una librería de Python) diseñada para entender este caos organizado.

1. La Metáfora del Baile y el "Termómetro del Desorden"

Imagina que estás en una fiesta.

• Si todos están dispersos por la sala, cada uno en su mundo, la fiesta es un caos total (esto es lo que los científicos llaman un enjambre).
• Si todos se ponen en fila para entrar a un club, hay orden lineal.
• Si todos empiezan a bailar en un círculo perfecto, hay orden rotacional.

Hasta ahora, los científicos solo tenían dos formas de medir esto: "¿Hacia dónde miran?" y "¿Están girando?". Pero eso es como intentar describir una película usando solo dos palabras.

Los creadores de dewi-kadita han inventado algo mucho más sofisticado: siete "termómetros de entropía". En lugar de solo mirar la dirección, estos termómetros miden la "confusión" en diferentes niveles: ¿Qué tan juntos están? ¿Qué tan uniforme es su formación? ¿Están todos a la misma profundidad?

Al combinar estos siete termómetros, crearon el OSI (Índice de Escolaridad Oceánica). Es como un puntaje de "armonía": un puntaje bajo significa que el grupo es una unidad perfecta; un puntaje alto significa que es un grupo de extraños moviéndose al azar.

2. El "Simulador de Realidad Virtual" ultra rápido

Para probar esto, los investigadores no fueron al océano (lo cual es difícil y caro), sino que construyeron un universo digital.

Usaron una tecnología llamada Numba que funciona como un "turbo" para las computadoras. Imagina que tienes que calcular la posición de 250 peces y cómo cada uno reacciona a los otros 249. ¡Eso es una cantidad de cálculos brutal! Sin este "turbo", la computadora tardaría horas; con dewi-kadita, lo hace en minutos. Es como pasar de escribir a mano una enciclopedia a usar una supercomputadora.

3. ¿Por qué es esto importante para el mundo real?

Este software no es solo un juguete matemático. Al entender cómo se organizan los peces, podemos:

• Proteger los océanos: Entender mejor cómo se mueven las especies comerciales.
• Robótica: Ayudar a crear enjambres de robots submarinos que puedan trabajar juntos para explorar el fondo del mar sin chocar entre ellos.
• Ciencia abierta: El código es "Open Source", lo que significa que es como una receta de cocina compartida: cualquier científico del mundo puede tomarla, mejorarla y usarla para sus propios descubrimientos.

En resumen: dewi-kadita es como haber pasado de ver una foto borrosa de un banco de peces a tener una cámara de alta definición con sensores inteligentes que nos dicen exactamente qué tan bien se están comunicando esos peces sin decir una sola palabra.

Resumen técnico

Resumen Técnico: Librería dewi-kadita para la Simulación de Cardúmenes de Peces

1. El Problema (Contexto y Motivación)

El estudio del movimiento colectivo en sistemas de materia activa (como los cardúmenes de peces) es fundamental para entender la autoorganización emergente. Sin embargo, la investigación actual enfrenta dos obstáculos principales:

• Fragmentación de herramientas: Las implementaciones de modelos computacionales (como el modelo de Couzin) suelen ser códigos de laboratorio no publicados, carentes de interfaces estandarizadas, documentación y formatos de datos interoperables.
• Limitaciones diagnósticas: Los parámetros de orden clásicos (polarización $P$ y rotación $M$) son insuficientes para caracterizar la complejidad estructural. Dos estados pueden tener valores similares de $P$ y $M$ pero poseer organizaciones espaciales y dinámicas radicalmente distintas.

2. Metodología

Los autores presentan dewi-kadita, una librería de código abierto en Python diseñada para simulaciones en tres dimensiones (3D) basadas en el modelo de zonas de Couzin.

• Modelo Dinámico: Implementa una arquitectura de interacción jerárquica basada en tres zonas esféricas alrededor de cada agente:
  1. Zona de Repulsión (ZOR): Evita colisiones.
  2. Zona de Orientación (ZOO): Facilita la alineación de velocidades.
  3. Zona de Atracción (ZOA): Mantiene la cohesión del grupo.
     El modelo incorpora restricciones biológicas como la visión limitada (zona ciega posterior), tasas de giro máximas y ruido estocástico gaussiano.
• Implementación Computacional: Para superar el cuello de botella de la complejidad $O(N^2)$ de las interacciones de pares, la librería utiliza compilación Just-In-Time (JIT) con Numba, lo que acelera los cálculos entre 10 y 100 veces. Además, emplea estructuras de datos k-d tree (vía SciPy) para optimizar las búsquedas de vecinos cercanos.
• Validación: Se probaron cuatro configuraciones canónicas: Swarm (enjambre desordenado), Torus (molienda/rotación), Dynamic Parallel (alineación con fluctuaciones) y Highly Parallel (alineación máxima).

3. Contribuciones Clave: El Marco de Diagnóstico de Entropía

La innovación principal es la introducción de un marco de diagnóstico basado en la teoría de la información mediante siete métricas de entropía de Shannon que capturan características organizativas inaccesibles para los parámetros clásicos:

1. Entropía de cohesión ($H_{coh}$): Distribución de distancias entre vecinos más cercanos.
2. Entropía de polarización ($H_{pol}$): Dispersión de las orientaciones de velocidad en la esfera unitaria.
3. Entropía de estratificación de profundidad ($H_{depth}$): Uniformidad de la posición vertical.
4. Entropía de momento angular ($H_{ang}$): Heterogeneidad de las contribuciones rotacionales individuales.
5. Entropía de vecino más cercano ($H_{NN}$): Estructura de densidad local.
6. Entropía de correlación de velocidad ($H_{vel}$): Distribución de las alineaciones de pares de velocidad.
7. Entropía de forma del cardumen ($H_{shape}$): Variabilidad morfológica mediante PCA.

Estas métricas se combinan en un único escalar denominado Índice de Cardumen Oceánico (OSI), que cuantifica el desorden colectivo total.

4. Resultados Principales

• Capacidad de Discriminación: El marco de entropía logró distinguir con éxito estados que los parámetros clásicos no podían. Por ejemplo, el OSI permitió diferenciar claramente entre las fases Torus y Dynamic Parallel, a pesar de que sus valores de ordenación eran comparables.
• Rendimiento: Las simulaciones de 150-250 agentes durante 1000-2000 pasos de tiempo se completaron en menos de cinco minutos en hardware estándar.
• Comportamiento de los Índices: En el estado Highly Parallel, la entropía de correlación de velocidad ($H_{vel}$) cayó a casi cero, indicando una correlación perfecta entre pares, mientras que el OSI alcanzó su valor mínimo (0.24), confirmando un estado de alta organización.

5. Significancia e Impacto

dewi-kadita establece un estándar de infraestructura para la investigación del comportamiento colectivo, similar a lo que códigos como LAMMPS representan para la dinámica molecular. Su importancia radica en:

• Interoperabilidad: El uso de formatos NetCDF4 (cumpliendo con las convenciones CF) permite que los datos de simulación se integren directamente con herramientas de análisis oceanográfico estándar.
• Reproducibilidad: Al ser de código abierto y seguir los principios FAIR (Encontrable, Accesible, Interoperable y Reutilizable), facilita la comparación sistemática entre estudios.
• Aplicabilidad: Proporciona una herramienta robusta tanto para la física estadística como para la ecología marina, permitiendo estudiar desde la evasión de depredadores hasta la eficiencia de forrajeo mediante métricas cuantitativas avanzadas.