SWARMICA v1.0.0 · Variational & Continuum Mechanics

SWARMICA v1.0.0

A Variational and Continuum Mechanics Framework for Collective Stability

Collective Lagrangian Operator · EPFE · KPSL · DOI: 10.5281/zenodo.20168278 · MIT License

🐝 pip install swarmica-engine 📄 Research Paper (DOI) 🐙 GitHub

94.7%

Mean CSI

88.3%

Mean ERI

2.3 τ_A

Convergence Time

N_basis

SOS Degree

3×K_c

Kuramoto Coupling

Scroll

"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

The Problem

Three Barriers.
One Resolution.

Conventional swarm control faces fundamental barriers that SWARMICA resolves through variational mechanics.

Barrier 01

The Scalability Barrier

Discrete agent-based stability proofs require all-to-all connectivity (O(N²) messages per step). The state space of an N-agent 3D system has dimension 6N — making Lyapunov analysis intractable for N > 10³.

SWARMICA: N-independent stability

Barrier 02

The Local Minima Trap

Artificial potential field methods suffer from spurious local attractors. In SWARMICA benchmarks, naive controllers trap formations in 34% of runs.

SWARMICA: SOS eliminates local minima

Barrier 03

The Phase Disorder Loss

Disordered internal phases dissipate collective kinetic energy into destructive internal oscillations.

SWARMICA: KPSL → DOF collapse 6N → 6

Core Architecture

Three Constructs.
One Continuum.

SWARMICA treats the swarm as a continuous active matter field on the Physical Coupling Manifold M.

Construct 01 · 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).

L = T − V_effG(Q)Q̈ + C(Q,Q̇)Q̇ + ∇V_eff = F_ctrlN-independent

Construct 02 · 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.

V_eff = p(Q)ᵀPp(Q) + α‖Q−Q*‖²P ≽ 0Unique global minimum

Construct 03 · 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.

dθᵢ/dt = ωᵢ + (K/N)Σ sin(θⱼ−θᵢ)K_c = 2ΔDOF collapse: 6N → 6

Mathematical Foundation

Core Equations

The formal mathematical foundation of SWARMICA's variational control framework.

Eq. 1 — PCM State

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

ρ: swarm density field · v: collective velocity field · ∫ρ dx = N

Eq. 2 — Collective Lagrangian

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

T: collective kinetic energy · V_eff: engineered potential field

Eq. 3 — Euler-Lagrange Field Equations

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

G: metric tensor · C: Coriolis-Christoffel tensor

Eq. 4 — SOS Potential Field

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

P ≽ 0: PSD matrix · α > 0: quadratic floor · Unique global attractor Q*

Eq. 5 — Kuramoto Phase Dynamics

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

K: coupling strength · F_ext: external phase correction from EPFE

Eq. 6 — Critical Coupling

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

K_c: synchronization threshold · r: order parameter · SWARMICA: K = 3K_c

Eq. 7 — Jacobian Stability Certificate

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

σ_min = λ_min(Hess V_eff) / λ_max(G(Q*)) · Exponential convergence guaranteed

Eq. 8 — Convergence Bound

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

Exponential return to organized state following bounded perturbations

Experimental Validation

Four Scenarios.
One Framework.

Validated across aerial formation reconfiguration, ground convoy navigation, underwater school coherence, and mixed-modality heterogeneous swarms. All results are mean over 50 Monte Carlo runs.

ID	Scenario	Modality	N Agents	CSI	ERI	Conv. Time
S1	Diamond-V aerial formation	Aerial	50–5000	96.2%	91.4%	1.8 τ_A
S2	Ground convoy obstacle field	Ground	10–500	94.1%	87.9%	2.4 τ_A
S3	Underwater school disturbance	Underwater	20–1000	93.8%	86.2%	2.6 τ_A
S4	Mixed-modality heterogeneous	Mixed	30–300	94.7%	88.1%	2.3 τ_A
Mean	—	—	—	94.7%	88.3%	2.3 τ_A

Ablation Study · Component Contributions
Configuration	Mean CSI	Mean ERI	Conv. Time	Collapse Rate
No EPFE (random potential)	31.4%	18.7%	>10 τ_A	61%
EPFE only — no KPSL	78.3%	71.2%	4.2 τ_A	11%
KPSL only — no EPFE	52.6%	44.8%	3.8 τ_A	28%
EPFE + KPSL — no Jacobian certificate	91.8%	85.3%	2.6 τ_A	4%
SWARMICA v1.0.0 (Full)	94.7%	88.3%	2.3 τ_A	<1%

Installation & Quick Start

Deploy in Seconds.

Certified collective stability in four lines of Python.

bash — install

python — quick start

# 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')"