manuk-kepudang

A Python framework for spatial entropy quantification in the three-dimensional Vicsek model

Abstract

Collective motion in active matter systems arises from local interactions among self-propelled constituents, producing emergent behavior observed across scales from bacterial colonies to bird flocks. This article introduces manuk-kepudang, an open-source Python library that implements the three-dimensional Vicsek model alongside a suite of information-theoretic diagnostics for characterizing spatial organization. The library pairs Numba-accelerated simulation of alignment dynamics with six entropy measures (positional, orientational, local alignment, pair correlation, Voronoi, and position-velocity mutual information), which are combined into a composite Spatial Complexity Index (SCI). These metrics capture aspects of configurational and orientational disorder that scalar order parameters alone cannot resolve. Validation across four test cases covering ordered, disordered, and critical regimes confirms that the entropy measures distinguish between collective states and reproduce the expected phenomenology of noise-driven phase transitions. We further apply nonparametric statistical methods suited to non-Gaussian velocity distributions, enabling rigorous characterization of how distributions evolve as collective alignment emerges. The library provides an accessible platform for studying collective motion, with applications ranging from biological swarm dynamics and robotic coordination to fundamental investigations of nonequilibrium phase transitions.