SWARMICA Documentation

📖 Overview

"The swarm is not a collection of agents. It is a single thought, distributed across a thousand bodies, moving through the geometry of its own potential. SWARMICA gives that thought a direction — and proves, mathematically, that it will arrive."

SWARMICA is a Variational and Continuum Mechanics framework for collective swarm stability that treats the swarm not as a collection of discrete reactive agents but as a continuous active matter field evolving on a Physical Coupling Manifold under the Principle of Least Action. Built on three orthogonal constructs spanning variational mechanics, SOS potential optimization, and Kuramoto phase synchronization, SWARMICA achieves certified collective stability across four canonical swarm scenarios.

🏗️ 3-Core Architecture

SWARMICA operates on the Physical Coupling Manifold M through three synergistic constructs:

CLO — Collective Lagrangian Operator

Derives swarm trajectory equations from a variational action functional over the generalized coordinate space of the continuum density field. The Euler-Lagrange equations have the same mathematical form regardless of N — all N-dependence is absorbed into the metric G(Q).

from swarmica import SwarmEngine, SwarmConfig

clo = CollectiveLagrangian(
    n_basis=64,
    mu_dissipation=0.02,
    alpha=0.15
)

EPFE — Effective Potential Field Engine

Engineers V_eff(Q) as a Sum-of-Squares polynomial with a guaranteed unique global attractor at Q*. Eliminates all local minima by construction — the SOS parameterization ensures global convexity.

KPSL — Kuramoto Phase Synchronization Layer

Drives inter-agent phase alignment above the critical coupling threshold K_c = 2Δ. At K = 3K_c, the swarm becomes a mechanically rigid collective body whose effective degrees of freedom collapse from 6N to 6.

📐 Core Equations (Eq. 1-8)

p(t) = (ρ(x,t), v(x,t)) ∈ M

L[Q, Q̇] = T[Q̇] − V_eff[Q] = ½∫ρ|v|²dx − ∫ρ(x)V(x)dx

G(Q)Q̈ + C(Q,Q̇)Q̇ + ∇_Q V_eff(Q) = F_ctrl

V_eff(Q) = p(Q)ᵀ P p(Q) + α‖Q − Q*‖²_G

dθᵢ/dt = ωᵢ + (K/N)Σⱼ sin(θⱼ − θᵢ) + F_ext,i(t)

K_c = 2Δ, r_∞ = √(1 − K_c/K) for K > K_c

Re(λᵢ) < −σ_min < 0 ∀i = 1…2N_basis

‖Q(t)−Q*‖ ≤ C e^{−σ_min t} ‖Q(0)−Q*‖

📦 Installation

# From PyPI (stable)
pip install swarmica-engine

# From source
git clone https://github.com/gitedeeper12/SWARMICA.git
cd SWARMICA && pip install -e .

# Quick test
python -c "from swarmica import SwarmEngine, SwarmConfig; print('SWARMICA ready')"

🔧 API Reference

SwarmEngine

from swarmica import SwarmEngine, SwarmConfig

# Configure swarm
cfg = SwarmConfig(
    n_agents=500,
    modality='aerial',
    n_basis=64,
    k_coupling=3.0,
    mu_dissipation=0.02,
    target_config='diamond_V'
)

engine = SwarmEngine(cfg)
engine.load_weights('experiments/weights/swarmica_v1.0.0_aerial.pt')

# Real-time control loop (1 kHz)
for obs in sensor_stream:
    ctrl = engine.step(dt=1e-3, obs=obs)
    csi = engine.get_csi()
    r = engine.get_order_parameter()
    S_s = engine.get_structural_entropy()

SwarmConfig Parameters

🧩 Core Modules

📊 Validation Summary

📈 N-Independence Certificate

Key Theoretical Result: SWARMICA's stability certificate is N-independent — no performance degradation from N=50 to N=5,000 across all four scenarios. This is a direct consequence of the continuum mechanics formulation: the CLO's Euler-Lagrange equations are defined over the continuum density field ρ(x,t) — they have the same mathematical form regardless of N.

👤 Author

📝 Citation

"The swarm is not a collection of agents. It is a single thought, distributed across a thousand bodies, moving through the geometry of its own potential. SWARMICA gives that thought a direction — and proves, mathematically, that it will arrive." — SWARMICA v1.0.0 Manifesto