Swarm Synchronization Simulation Engine

A Python simulation engine for studying emergent collective behavior in coupled oscillator systems. Implements the Swarmalator model — agents that simultaneously swarm in space and synchronize in phase — reproducing all five canonical collective states described in the literature.

Emergent Patterns

The simulator reproduces the following collective states by varying coupling parameters J (spatial-phase attraction) and K (phase coupling strength):

Pattern	J	K	Description
Static Sync	> 0	> 0	Tight cluster, all phases aligned
Static Async	> 0	< 0	Tight cluster, phases uniformly distributed
Static Phase Wave	> 0	≈ 0	Ring structure, phase varies with angular position
Splintered Phase Wave	> 0	small	Fragmented ring with clustered sub-groups
Active Phase Wave	> 0	≈ 0	Dynamic vortex with continuous orbital motion

Implementations

Swarmalator Model

• Naive (loop-based): Clear, educational O(N²) double-loop implementation
• Vectorized (NumPy): Optimized matrix-based computation achieving ~100× speedup
• Stochastic Coupling: Extended model with probabilistic memory-based interactions (Mathematica)

Kuramoto Synchronization

• Classical Kuramoto model for phase-coupled oscillators
• Visualization of order parameter convergence

Technical Details

The swarmalator dynamics follow:

$$\dot{x}_i = \frac{1}{N} \sum_{j \neq i} \left[ \frac{x_j - x_i}{|x_j - x_i|} (1 + J \cos(\theta_j - \theta_i)) - \frac{x_j - x_i}{|x_j - x_i|^2} \right]$$

$$\dot{\theta}_i = \frac{K}{N} \sum_{j \neq i} \frac{\sin(\theta_j - \theta_i)}{|x_j - x_i|}$$

Quick Start

pip install -r requirements.txt

# Run vectorized swarmalator simulation
python src/swarmalator_vectorized.py

# Run animated visualization
python src/swarmalator_animated.py

# Run static convergence plot
python src/swarmalator_plot.py

Project Structure

swarm-sync-simulation/
├── src/
│   ├── swarmalator_animated.py       # Real-time animated swarmalator simulation
│   ├── swarmalator_vectorized.py     # NumPy-optimized vectorized simulation
│   ├── swarmalator_plot.py           # Static convergence visualization
│   └── kuramoto_sync.py             # Classical Kuramoto model
├── tests/
│   └── test_swarmalator.py           # Unit tests for dynamics + convergence
├── docs/
│   ├── analysis.md                   # Pattern analysis and observations
│   └── stochastic_coupling.txt       # Extended stochastic model (Mathematica)
└── requirements.txt

References

• O'Keeffe, K. P., Hong, H., & Strogatz, S. H. (2017). Oscillators that sync and swarm. Nature Communications, 8, 1504.
• Kuramoto, Y. (1975). Self-entrainment of a population of coupled non-linear oscillators. International Symposium on Mathematical Problems in Theoretical Physics.

License

MIT License