manuk-kepudang 0.0.2

3D Vicsek Model Collective Motion Simulator with Numba Acceleration

manuk-kepudang: A Python Library for 3D Vicsek Model Simulation

A Python library for simulating collective motion using the 3D Vicsek model with Numba JIT acceleration and spatial entropy metrics.

Model

The Vicsek model (1995) describes self-propelled particles exhibiting collective motion through simple alignment rules. In 3D, each particle $i$ updates its velocity according to:

$$\mathbf{v}i(t + \Delta t) = v_0 \cdot \hat{\mathbf{u}}\left( \langle \hat{\mathbf{v}}j \rangle{|r{ij}| < r} + \eta \boldsymbol{\xi}_i \right)$$

where:

• $v_0$ is the constant speed of all particles
• $\langle \hat{\mathbf{v}}_j \rangle$ is the normalized average velocity of neighbors within radius $r$
• $\eta$ is the noise amplitude
• $\boldsymbol{\xi}_i$ is a random unit vector
• $\hat{\mathbf{u}}(\cdot)$ denotes normalization to unit vector

Position updates follow:

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

with periodic boundary conditions in a cubic box of side $L$.

Key Parameters

Parameter	Symbol	Description	Typical Range
N	$N$	Number of particles	50-5000
L	$L$	Box size	5-50
v0	$v_0$	Particle speed	0.1-1.0
r	$r$	Interaction radius	1.0-5.0
eta	$\eta$	Noise magnitude	0.0-2.0
dt	$\Delta t$	Time step	0.1-1.0

Order Parameter

The collective alignment is quantified by the order parameter:

$$\phi = \frac{1}{N v_0} \left| \sum_{i=1}^{N} \mathbf{v}_i \right|$$

where $\phi \approx 0$ indicates disordered motion and $\phi \approx 1$ indicates collective alignment.

Spatial Entropy Metrics

This library includes rigorous information-theoretic measures to quantify spatial order/disorder:

Metric	Description	High Value	Low Value
Positional Entropy	Shannon entropy of spatial distribution	Uniform (disordered)	Clustered (ordered)
Orientational Entropy	Entropy of velocity directions on unit sphere	Isotropic (disordered)	Aligned (ordered)
Local Alignment Entropy	Heterogeneity of local order	Heterogeneous	Homogeneous
Pair Correlation Entropy	From radial distribution function g(r)	Ideal gas	Crystalline
Voronoi Cell Entropy	Geometric packing disorder	Irregular	Regular
Position-Velocity MI	Mutual information coupling	Spatial structure	Homogeneous
Spatial Complexity Index	Weighted composite measure	Disordered	Ordered

*SCI = (H_positional + H_orientational + H_local_align + H_pair + H_voronoi + (1-MI)) / 6

Installation

From PyPI:

pip install manuk-kepudang

From source:

git clone https://github.com/sandyherho/manuk-kepudang.git
cd manuk-kepudang
pip install .

Development installation with Poetry:

git clone https://github.com/sandyherho/manuk-kepudang.git
cd manuk-kepudang
poetry install

Quick Start

CLI:

manuk-kepudang case1          # Run ordered phase scenario
manuk-kepudang case2          # Run disordered phase scenario
manuk-kepudang --all          # Run all test cases
manuk-kepudang case1 --no-entropy  # Skip entropy computation

Python API:

from manuk_kepudang import VicsekSystem, VicsekSolver
from manuk_kepudang import compute_metrics_timeseries

# Create system with 200 particles
system = VicsekSystem(
    n_particles=200,
    box_size=10.0,
    speed=0.5,
    interaction_radius=2.0,
    noise=0.3
)

# Initialize solver with Numba acceleration
solver = VicsekSolver(dt=1.0, use_numba=True)

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

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

print(f"Final order parameter: {result['final_order_parameter']:.4f}")
print(f"Final SCI (disorder): {metrics['spatial_complexity_index_final']:.4f}")

Features

• High-performance: Numba JIT compilation for 10-100x speedup
• 3D simulation: Full three-dimensional particle dynamics
• Periodic boundaries: Correct handling of boundary conditions
• Order parameter tracking: Real-time collective alignment measurement
• Spatial entropy metrics: Rigorous information-theoretic disorder measures
• Multiple output formats: CSV, NetCDF (CF-compliant), PNG, GIF
• Configurable scenarios: Text-based configuration files

Output Files

The library generates:

• CSV files:
  • *_order_parameter.csv - Order parameter time series
  • *_entropy_timeseries.csv - All entropy measures over time
  • *_entropy_summary.csv - Statistics (mean, std, min, max, final)
  • *_final_state.csv - Final particle positions and velocities
• NetCDF: Full trajectory data with all metrics and CF-compliant metadata
  • Variables: x, y, z, vx, vy, vz, order_parameter, all entropy metrics
• PNG: Static summary plots with entropy visualization
• GIF: Animated 3D visualization with camera rotation

Test Cases

Case	Description	N	η
1	Ordered phase	200	0.3
2	Disordered phase	200	2.0
3	Large system	500	0.5
4	Phase transition	300	1.0

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 © Sandy H. S. Herho, Gandhi Napitupulu, Iwan P. Anwar, Nurjanna J. Trilaksono, Rusmawan Suwarman, Dasapta E. Irawan

Citation

@software{herho2025_manuk_kepudang,
  title   = {manuk-kepudang: A Python library for 3D Vicsek model simulation},
  author  = {Herho, Sandy H. S. and Napitupulu, G. and Anwar, Iwan P. and Trilaksono, Nurjanna J. and Suwarman, Rusmawan and Irawan, Dasapta E.},
  year    = {2025},
  url     = {https://github.com/sandyherho/manuk-kepudang}
}