Skip to main content

SWARMICA: Autonomous Physical Law Discovery System - From Classical Mechanics to Neural Operator Physics

Project description

๐Ÿ SWARMICA v13.0.0

A Variational and Continuum Mechanics Framework for Collective Stability in Autonomous Swarm Systems


DOI License: MIT ORCID

PyPI version PyPI downloads PyPI status

OSF Preregistration OSF Project Registration DOI Internet Archive License: CC BY 4.0

Python PyTorch JAX


"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 Manifesto

"From classical mechanics to neural operators, from PDE solvers to autonomous law discovery โ€” SWARMICA has evolved into a unified continuum swarm physics platform for scientific research."


Table of Contents


Overview

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.

Where conventional swarm control methods โ€” Boids rules, consensus protocols, artificial potential fields โ€” provide heuristic coordination without global stability guarantees, SWARMICA derives the swarm's collective equations of motion from a variational action functional, certifies stability through Jacobian eigenvalue analysis at the global attractor Q*, and drives inter-agent phase alignment through a modified Kuramoto synchronization layer that collapses the swarm's internal degrees of freedom from 6N to 6.

The framework is built on three mathematically rigorous constructs:

Construct Role
Collective Lagrangian Operator (CLO) Derives swarm trajectory equations from a variational action functional over the generalized coordinate space of the continuum density field
Effective Potential Field Engine (EPFE) Engineers the swarm potential landscape via Sum-of-Squares (SOS) semidefinite programming to guarantee a unique global attractor at Q* โ€” eliminating all local minima by construction
Kuramoto Phase Synchronization Layer (KPSL) Drives inter-agent phase alignment above the critical coupling threshold K_c, collapsing the swarm into a mechanically rigid collective body

The Problem

Conventional swarm control faces three fundamental barriers that SWARMICA resolves:

1. The Scalability Barrier Discrete agent-based stability proofs require either all-to-all connectivity (O(Nยฒ) messages per step) or graph-connectivity conditions that are difficult to maintain in dynamic environments. The state space of an N-agent 3D system has dimension 6N โ€” making Lyapunov analysis computationally intractable for N > 10ยณ and unrealizable for the N = 10โด to 10โถ agent counts of next-generation applications.

2. The Local Minima Trap Artificial potential field methods suffer from spurious local attractors in obstacle-dense environments. In the SWARMICA ground-convoy benchmark, naive potential field controllers trap formations in 34% of Monte Carlo runs. The EPFE's SOS parameterization eliminates local minima by construction, and the CLO's kinetic coherence mechanism allows the collective body to traverse residual obstacle barriers without becoming trapped.

3. The Phase Disorder Loss Disordered internal agent phases dissipate a significant fraction of the collective kinetic energy into destructive internal oscillations rather than directed motion. The KPSL drives all agent phases to a common target above K_c, producing a mechanically rigid collective body whose effective degrees of freedom collapse from 6N to 6 โ€” channeling all kinetic energy into the collective trajectory toward Q*.


Core Constructs

1. Collective Lagrangian Operator (CLO)

The CLO represents the swarm as a continuum density field ฯ(x,t) and velocity field v(x,t) on the Physical Coupling Manifold M, deriving the collective equations of motion from the Principle of Least Action:

Lagrangian:
  L[Q, Qฬ‡] = T[Qฬ‡] โˆ’ V_eff[Q]
           = ยฝ โˆซ ฯ|v|ยฒ dx  โˆ’  โˆซ ฯ(x) V(x) dx

Collective Euler-Lagrange Field Equations:
  G(Q) Qฬˆ + C(Q, Qฬ‡) Qฬ‡ + โˆ‡_Q V_eff(Q) = F_ctrl

Physical Coupling Manifold State:
  p(t) = (ฯ(x,t), v(x,t)) โˆˆ M
  โˆซ ฯ(x,t) dx = N   [agent count conservation]

Key property: the Euler-Lagrange equations have the same mathematical form regardless of N โ€” all N-dependence is absorbed into the metric G(Q) and the Christoffel connection C(Q, Qฬ‡). Stability analysis is N-independent by construction.

2. Effective Potential Field Engine (EPFE)

The EPFE constructs V_eff(Q) as a Sum-of-Squares (SOS) polynomial with a guaranteed unique global minimum at Q* โ€” the target collective configuration:

SOS Parameterization:
  V_eff(Q) = p(Q)แต€ P p(Q) + ฮฑ โ€–Q โˆ’ Q*โ€–ยฒ_G

where:
  P โ‰ฝ 0        [positive semidefinite โ€” computed via SDP / CVXPY + MOSEK]
  p(Q)         [monomial basis, degree โ‰ค 2d]
  ฮฑ > 0        [quadratic floor ensuring global strict convexity]

Global attractor guarantee:
  V_eff(Q) > V_eff(Q*)    for all Q โ‰  Q*
  โˆ‡_Q V_eff(Q*) = 0       [stationarity]
  Hess V_eff(Q*) โ‰ป 0      [strict local convexity]

Kinetic coherence and barrier penetration:
  T_coh(t) > ฮ”V_barrier(Q)  โ†’  trajectory continues to Q*

3. Kuramoto Phase Synchronization Layer (KPSL)

The KPSL drives inter-agent phase alignment through a mean-field modified Kuramoto model:

Phase Dynamics:
  dฮธแตข/dt = ฯ‰แตข + (K/N) ฮฃโฑผ sin(ฮธโฑผ โˆ’ ฮธแตข) + F_ext,i(t)

Order Parameter (continuum limit):
  r(t) e^{iฯ†(t)} = โˆซ ฯ(ฯ‰,t) e^{iฮธ(ฯ‰,t)} dฯ‰

Critical Coupling Threshold (Lorentzian g(ฯ‰)):
  K_c = 2ฮ”
  r_โˆž = โˆš(1 โˆ’ K_c/K)    for K > K_c

SWARMICA design: K = 3K_c  [3ร— overcritical for robust synchronization]

Degree-of-Freedom Collapse at Full Synchronization:
  dim(Phase Space)_disordered    = 6N
  dim(Phase Space)_synchronized  = 6   [rigid body: 3 translational + 3 rotational]
  DOF Reduction Ratio: ฮพ = 1 โˆ’ 1/N  โ†’ 1  as N โ†’ โˆž

Mathematical Foundation

System Architecture

Input: Swarm state  p(t) = (ฯ(x,t), v(x,t))  on Physical Coupling Manifold M
         โ”‚
         โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚           Collective Lagrangian Operator (CLO)       โ”‚
โ”‚  Basis expansion: Q โˆˆ R^{N_basis}  (N_basis = 64)   โ”‚
โ”‚  Metric: G(Q) Qฬˆ + C(Q,Qฬ‡)Qฬ‡ + โˆ‡V_eff = F_ctrl       โ”‚
โ”‚  Integration: Dormand-Prince RK45 adaptive step      โ”‚
โ”‚  Frictionless limit: ฮผ โ†’ 0  (asymptotic ceiling)     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                       โ”‚
                       โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚       Effective Potential Field Engine (EPFE)        โ”‚
โ”‚  V_eff(Q) = p(Q)แต€ P p(Q) + ฮฑโ€–Qโˆ’Q*โ€–ยฒ_G             โ”‚
โ”‚  P โ‰ฝ 0  [SOS-SDP, degree d=4, MOSEK solver]         โ”‚
โ”‚  Global attractor Q* โ€” no local minima by design     โ”‚
โ”‚  Basin radius: R_basin from sublevel set analysis    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                       โ”‚
                       โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚      Kuramoto Phase Synchronization Layer (KPSL)     โ”‚
โ”‚  dฮธแตข/dt = ฯ‰แตข + (K/N)ฮฃโฑผ sin(ฮธโฑผโˆ’ฮธแตข) + F_ext,i      โ”‚
โ”‚  K = 3K_c  โ†’  r(t) โ†’ 0.97  within 1.2 ฯ„_A          โ”‚
โ”‚  DOF collapse: 6N โ†’ 6  (rigid collective body)       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                       โ”‚
                       โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚             Jacobian Stability Certificate           โ”‚
โ”‚  Re(ฮปแตข) < โˆ’ฯƒ_min < 0    โˆ€ i = 1โ€ฆ2N_basis           โ”‚
โ”‚  ฯƒ_min = ฮป_min(Hess V_eff) / ฮป_max(G(Q*))           โ”‚
โ”‚  โ€–Q(t)โˆ’Q*โ€– โ‰ค C e^{โˆ’ฯƒ_min t} โ€–Q(0)โˆ’Q*โ€–             โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                       โ”‚
                       โ–ผ
Output: F_ctrl(t)   โ€” actuator commands for all agents
        CSI          โ€” Collective Stability Index โˆˆ [0,1]
        r(t)         โ€” Kuramoto order parameter โˆˆ [0,1]
        S_struct(t)  โ€” structural entropy
        ERI          โ€” Entropy Reduction Index โˆˆ [0,1]

Core Equations

# Equation Description
1 p(t) = (ฯ(x,t), v(x,t)) โˆˆ M Physical Coupling Manifold state
2 T = ยฝ โˆซ ฯ(x)|v(x)|ยฒ dx = ยฝ Qฬ‡แต€G(Q)Qฬ‡ Collective kinetic energy / manifold metric
3 L[Q,Qฬ‡] = T[Qฬ‡] โˆ’ V_eff[Q] Ideal SWARMICA Lagrangian
4 G(Q)Qฬˆ + C(Q,Qฬ‡)Qฬ‡ + โˆ‡_Q V_eff(Q) = F_ctrl Collective Euler-Lagrange equations
5 V_eff(Q) = p(Q)แต€Pp(Q) + ฮฑโ€–Qโˆ’Q*โ€–ยฒ_G SOS potential field
6 T_coh > ฮ”V_barrier โŸน trajectory reaches Q* Kinetic coherence barrier penetration
7 L_ฮผ = T โˆ’ V_eff โˆ’ ฮผD[Qฬ‡] Dissipative extension (physical ฮผ > 0)
8 dฮธแตข/dt = ฯ‰แตข + (K/N)ฮฃโฑผsin(ฮธโฑผโˆ’ฮธแตข) + F_ext,i Modified Kuramoto phase dynamics
9 K_c = 2ฮ”, r_โˆž = โˆš(1โˆ’K_c/K) Critical coupling and order parameter
10 dim_synchronized = 6 (vs 6N) DOF collapse at full synchronization
11 Re(ฮปแตข) < โˆ’ฯƒ_min < 0 Jacobian eigenvalue stability certificate
12 โ€–Q(t)โˆ’Q*โ€– โ‰ค C e^{โˆ’ฯƒ_min t}โ€–Q(0)โˆ’Q*โ€– Exponential convergence bound
13 S_struct(t) = k_B ln(ฮฉ(t)) Structural entropy of the swarm
14 ERI = 1 โˆ’ S_struct(t_final) / S_struct(0) Entropy Reduction Index
15 B(Q*) โЇ {Q : V_eff(Q) โ‰ค V_max} Basin of attraction via sublevel sets

Key Results

Metric Value
Mean Collective Stability Index (CSI) 94.7%
Mean Entropy Reduction Index (ERI) 88.3% vs. uncontrolled baseline
Mean convergence time to Q* 2.3 ฯ„_A (Alfvรฉn-analog time units)
Formation collapse rate < 1% vs. 34% for best competing method
Improvement over Vicsek + MPC hybrid +11.1 pp CSI
Improvement over artificial potential fields +21.9 pp CSI
N-independence Proved โ€” no CSI degradation N=50 to N=5,000
Inference latency (A100 FP32, N=500) 1.2 ms full control cycle (833 Hz)
Inference latency (Orin INT8, domain-selective) 0.24 ms (4,167 Hz)
Total parameters (CLO + KPSL) 24.6 M
Training compute 620 GPU-hours (8ร— A100)

Project Structure

SWARMICA/
โ”‚
โ”œโ”€โ”€ README.md                                    # This file
โ”œโ”€โ”€ LICENSE                                      # MIT License ยฉ 2026 Samir Baladi
โ”œโ”€โ”€ CITATION.cff                                 # Citation metadata (CFF format)
โ”œโ”€โ”€ pyproject.toml                               # Build configuration
โ”œโ”€โ”€ setup.py                                     # Package setup
โ”œโ”€โ”€ .gitlab-ci.yml                               # CI/CD: lint, test, benchmark, deploy
โ”œโ”€โ”€ CHANGELOG.md                                 # Release history (v1.0 โ†’ v13.0)
โ”‚
โ”œโ”€โ”€ paper/
โ”‚   โ”œโ”€โ”€ SWARMICA_Research_Paper.pdf              # Full academic paper (v1.0.0)
โ”‚   โ””โ”€โ”€ figures/
โ”‚       โ”œโ”€โ”€ fig1_pcm_manifold.png
โ”‚       โ”œโ”€โ”€ fig2_epfe_potential.png
โ”‚       โ”œโ”€โ”€ fig3_kpsl_synchronization.png
โ”‚       โ”œโ”€โ”€ fig4_jacobian_eigenvalues.png
โ”‚       โ”œโ”€โ”€ fig5_s1_aerial_formation.png
โ”‚       โ”œโ”€โ”€ fig6_s2_convoy_obstacles.png
โ”‚       โ”œโ”€โ”€ fig7_s3_underwater_school.png
โ”‚       โ”œโ”€โ”€ fig8_ablation_study.png
โ”‚       โ””โ”€โ”€ fig9_n_independence.png
โ”‚
โ”œโ”€โ”€ swarmica/                                    # Core Python library (swarmica-engine)
โ”‚   โ”œโ”€โ”€ manifold/                               # Physical Coupling Manifold
โ”‚   โ”œโ”€โ”€ field/                                  # CLO + EPFE + SOS optimizer
โ”‚   โ”œโ”€โ”€ synchronization/                        # KPSL + Kuramoto order parameter
โ”‚   โ”œโ”€โ”€ stability/                              # Jacobian certificate + basin estimator
โ”‚   โ”œโ”€โ”€ control/                                # SwarmEngine top-level API
โ”‚   โ””โ”€โ”€ interface/                              # Config, ROS2, TensorRT export
โ”‚
โ”œโ”€โ”€ benchmarks/                                 # Validation scripts (S1โ€“S4)
โ”œโ”€โ”€ training/                                   # Three-phase training curriculum
โ”œโ”€โ”€ notebooks/                                  # Jupyter walkthrough notebooks
โ”œโ”€โ”€ examples/                                   # Minimal working examples
โ”œโ”€โ”€ docs/                                       # API reference + guides
โ””โ”€โ”€ tests/                                      # Unit and integration tests

Installation

Requirements: Python โ‰ฅ 3.11 | PyTorch โ‰ฅ 2.4 | JAX โ‰ฅ 0.4 | NumPy โ‰ฅ 2.1 | SciPy โ‰ฅ 1.14 | CVXPY โ‰ฅ 1.4 (with MOSEK for SOS-SDP)

# Stable release from PyPI
pip install swarmica-engine

# Development install from source
git clone https://github.com/gitdeeper12/SWARMICA.git
cd SWARMICA
pip install -e .

# With CUDA-accelerated JAX
pip install swarmica-engine[cuda]

# With ROS2 bridge
pip install swarmica-engine[ros2]

# Full install (CUDA + ROS2 + MOSEK)
pip install swarmica-engine[full]

Quick Start

Minimal example โ€” 50-agent aerial diamond-V formation:

from swarmica import SwarmEngine, SwarmConfig

cfg = SwarmConfig(
    n_agents       = 50,
    modality       = 'aerial',
    n_basis        = 64,
    k_coupling     = 3.0,
    mu_dissipation = 0.02,
    target_config  = 'diamond_V',
    sos_degree     = 4,
)

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

for obs in sensor_stream:
    ctrl = engine.step(dt=1e-3, obs=obs)
    csi  = engine.get_csi()
    r    = engine.get_order_parameter()
    eri  = engine.get_eri()
    print(f"CSI={csi:.4f} | r={r:.4f} | ERI={eri:.4f}")

Ground convoy through obstacle field:

from swarmica import SwarmEngine, SwarmConfig

cfg = SwarmConfig(
    n_agents                 = 100,
    modality                 = 'ground',
    n_basis                  = 64,
    k_coupling               = 3.0,
    mu_dissipation           = 0.08,
    target_config            = 'convoy_line',
    obstacle_field           = True,
    kinetic_coherence_boost  = 1.5,
)

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

result = engine.run_scenario(
    duration_s    = 120.0,
    control_hz    = 100,
    initial_state = initial_positions_velocities,
    log_metrics   = True,
)

print(f"Collapse events : {result.collapse_count}")
print(f"Mean CSI        : {result.mean_csi:.4f}")
print(f"Conv. time      : {result.convergence_time:.2f} ฯ„_A")

Run full validation benchmark:

python benchmarks/run_all_scenarios.py \
    --weights experiments/weights/ \
    --output  results/ \
    --scenarios S1 S2 S3 S4 \
    --n_monte_carlo 50

Validation Scenarios

All results are mean values over 50 independent Monte Carlo runs with random initial condition sampling from within the basin of attraction B(Q*).

ID Scenario Modality N Agents CSI ERI Conv. Time Collapse Rate
S1 Diamond-V aerial formation reconfiguration Aerial (quadrotor) 50โ€“5,000 96.2% 91.4% 1.8 ฯ„_A < 1%
S2 Ground convoy through dense obstacle field Ground (UGV) 10โ€“500 94.1% 87.9% 2.4 ฯ„_A < 1%
S3 Underwater school under ocean current disturbance Underwater (AUV) 20โ€“1,000 93.8% 86.2% 2.6 ฯ„_A < 1%
S4 Mixed-modality heterogeneous swarm Aerial + Ground 30โ€“300 94.7% 88.1% 2.3 ฯ„_A < 1%
Mean โ€” โ€” โ€” 94.7% 88.3% 2.3 ฯ„_A < 1%

Ablation Study

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 (partial) 28%
EPFE + KPSL โ€” no Jacobian certificate 91.8% 85.3% 2.6 ฯ„_A 4%
SWARMICA v13.0.0 (Full) 94.7% 88.3% 2.3 ฯ„_A < 1%

Comparison with Competing Methods

Method Mean CSI ERI Conv. Time N-independent? Collapse Rate
Boids (Reynolds, 1987) 44.2% 29.1% > 8 ฯ„_A Yes (heuristic) 38%
Consensus Protocol (Olfati-Saber, 2004) 67.3% 55.8% 5.1 ฯ„_A Partially 22%
Artificial Potential Fields (Khatib, 1986) 72.8% 63.4% 4.6 ฯ„_A No 17%
Graph-theoretic Formation (Fax-Murray, 2004) 79.1% 70.2% 3.9 ฯ„_A Partially 12%
Vicsek + MPC hybrid 83.6% 76.4% 3.2 ฯ„_A No 8%
SWARMICA v13.0.0 (Full) 94.7% 88.3% 2.3 ฯ„_A Yes (proved) < 1%

Training Configuration

Hyperparameter Value
Basis dimension N_basis 64
SOS polynomial degree d 4
Kuramoto coupling K 3.0 ร— K_c
CLO integration scheme Dormand-Prince RK45 (adaptive step)
Control update rate 1 kHz (1 ms)
EPFE ฮฑ (quadratic floor) 0.15
Physics loss weight ฮป_1 8.0 (NTK-adaptive)
Training compute 620 GPU-hours (8ร— A100)
Total parameters (CLO + KPSL) 24.6 M
A100 FP32 inference (N=500) 1.2 ms / 833 Hz
Orin INT8 inference (domain-selective) 0.24 ms / 4,167 Hz

Reproducibility Infrastructure

Platform Identifier / URL Content
GitHub (Primary) github.com/gitdeeper12/SWARMICA Source code, issues, contributions
GitLab (Mirror) gitlab.com/gitdeeper12/SWARMICA CI/CD pipelines, mirror
Bitbucket (Mirror) bitbucket.org/gitdeeper-12/SWARMICA Mirror repository
Codeberg (Mirror) codeberg.org/gitdeeper12/SWARMICA Mirror repository
Zenodo (Archive) 10.5281/zenodo.20168278 DOI, datasets, model weights, paper
PyPI swarmica-engine pip install swarmica-engine
ORCID 0009-0003-8903-0029 Author identifier (Samir Baladi)

Clone Commands

# Primary
git clone https://github.com/gitdeeper12/SWARMICA.git

# Mirrors
git clone https://gitlab.com/gitdeeper12/SWARMICA.git
git clone https://bitbucket.org/gitdeeper-12/SWARMICA.git
git clone https://codeberg.org/gitdeeper12/SWARMICA.git

Quick Commands

pip install swarmica-engine                          # Stable release
pip install swarmica-engine[cuda]                    # CUDA-accelerated JAX
pip install swarmica-engine[full]                    # Full: CUDA + ROS2 + MOSEK

python benchmarks/run_all_scenarios.py               # Full S1โ€“S4 validation suite
python benchmarks/ablation_study.py                  # CLO / EPFE / KPSL ablation
python benchmarks/n_independence_test.py             # N-scaling invariance test
python examples/quick_start.py                       # 50-agent aerial formation demo
python bin/swarmica_run.py --scenario S2 --n 200     # Run convoy scenario, 200 agents

OSF Preregistration

This project has been formally preregistered on the Open Science Framework (OSF) Registries, providing a timestamped, publicly archived record of the research design, hypotheses, and methodology prior to analysis.

Field Details
Registration Type OSF Preregistration
Registry OSF Registries
Associated Project osf.io/trgkq
Registration DOI 10.17605/OSF.IO/Q4N8E
Date Created May 14, 2026, 4:58 PM
Date Registered May 14, 2026, 4:58 PM
Internet Archive archive.org/details/osf-registrations-q4n8e-v1
Registration License CC-By Attribution 4.0 International

OSF Preregistration Registration DOI Internet Archive


Version History

SWARMICA has evolved from a classical variational mechanics framework (v1.0) through eight major scientific paradigms to a full autonomous physical law discovery platform (v13.0). See CHANGELOG.md for complete release notes.

Version Release Focus Scientific Domain Tests Status
v13.0 May 15, 2026 Autonomous Physical Law Discovery PDE Discovery + SINDy 30 Research
v12.0 May 15, 2026 Constrained Neural Physics Hamiltonian Systems 28 Breakthrough
v11.0 May 14, 2026 Neural Operator Swarm Physics Neural Operators 36 Frontier
v10.0 May 14, 2026 Neural Field + Inverse Physics Scientific ML 26 Breakthrough
v9.0 May 14, 2026 PDE Swarm Physics CFD + Active Matter 13 Alpha
v8.0 May 14, 2026 Unified Field Control Agent-based Continuum 23 Stable
v2.0 May 14, 2026 Stochastic Continuum Dynamics SDE Systems 28 Beta
v1.0 May 14, 2026 Classical Variational Mechanics Lagrangian Dynamics 28 Stable

v13.0 Highlights โ€” Autonomous Physical Law Discovery

The current release introduces a full PDE Discovery Engine powered by SINDy (Sparse Identification of Nonlinear Dynamics):

  • PDE Library Builder โ€” candidate term library: [u, uยฒ, โˆ‚u/โˆ‚x, โˆ‚u/โˆ‚y, โˆ‡ยฒu, uยทโˆ‚u/โˆ‚x, uยทโˆ‚u/โˆ‚y, sin(u)]
  • Sparse Selector โ€” Lasso regression: min ||y - ฮ˜ฮพ||ยฒ + ฮฑ||ฮพ||โ‚
  • Constraint Verifier โ€” physical validity: mass conservation, positivity, boundedness
  • Key result: 3 PDE terms discovered ยท 62.5% sparsity ยท physically valid

Development Roadmap

Milestone Target Platform Status
v13.0.0 release + PyPI May 2026 All GPUs โœ… Complete
ROS2 bridge validation Q3 2026 ROS2 Humble ๐Ÿ”„ In progress
v14.0 โ€” experimental validation with real data Q4 2026 A100 cluster ๐Ÿ“ Design phase
v14.0 โ€” comparison with CFD literature Q4 2026 A100 cluster ๐Ÿ“ Design phase
v15.0 โ€” physical swarm deployment Q2 2027 Physical hardware ๐Ÿ“‹ Planned
v15.0 โ€” publication-ready framework Q2 2027 All GPUs ๐Ÿ“‹ Planned
FPGA deployment Q4 2027 Xilinx Versal ๐Ÿ“‹ Planned
Large-scale field trial (N > 10,000) Q3 2028 Physical hardware ๐Ÿ“‹ Planned

Citation

If you use SWARMICA in your research, please cite both the Zenodo software archive and the OSF preregistration.

Software Archive (Zenodo)

DOI

@software{baladi2026swarmica,
  author       = {Baladi, Samir},
  title        = {{SWARMICA} v13.0.0: A Variational and Continuum Mechanics
                  Framework for Collective Stability in Autonomous Swarm Systems},
  year         = {2026},
  month        = {May},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.20168278},
  url          = {https://doi.org/10.5281/zenodo.20168278},
  note         = {Biomedical \& Autonomous Systems Research Series.
                  Ronin Institute / Rite of Renaissance.
                  PyPI: pip install swarmica-engine}
}

OSF Preregistration

Registration DOI

@misc{baladi2026swarmica_osf,
  author       = {Baladi, Samir},
  title        = {{SWARMICA}: Preregistration โ€” Variational and Continuum Mechanics
                  Framework for Collective Stability in Autonomous Swarm Systems},
  year         = {2026},
  month        = {May},
  publisher    = {OSF Registries},
  doi          = {10.17605/OSF.IO/Q4N8E},
  url          = {https://doi.org/10.17605/OSF.IO/Q4N8E},
  note         = {OSF Preregistration. Associated project: https://osf.io/trgkq.
                  Archived: https://archive.org/details/osf-registrations-q4n8e-v1.
                  License: CC-By Attribution 4.0 International.}
}

PyPI Package

PyPI version

@misc{baladi2026swarmica_pypi,
  author       = {Baladi, Samir},
  title        = {{swarmica-engine}: Python Package for Variational Swarm Control},
  year         = {2026},
  month        = {May},
  howpublished = {Python Package Index (PyPI)},
  url          = {https://pypi.org/project/swarmica-engine/},
  note         = {Install: \texttt{pip install swarmica-engine}.
                  Ronin Institute / Rite of Renaissance. MIT License.}
}

Author

Samir Baladi Independent Researcher โ€” Ronin Institute / Rite of Renaissance


License

MIT License
Copyright ยฉ 2026 Samir Baladi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

SWARMICA v13.0.0 โ€” A Variational and Continuum Mechanics Framework for Collective Stability ยฉ 2026 Samir Baladi โ€” Ronin Institute / Rite of Renaissance โ€” MIT License Zenodo: 10.5281/zenodo.20168278 | OSF: 10.17605/OSF.IO/Q4N8E | PyPI: swarmica-engine

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

swarmica_engine-13.0.0.tar.gz (52.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

swarmica_engine-13.0.0-py3-none-any.whl (38.4 kB view details)

Uploaded Python 3

File details

Details for the file swarmica_engine-13.0.0.tar.gz.

File metadata

  • Download URL: swarmica_engine-13.0.0.tar.gz
  • Upload date:
  • Size: 52.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: SWARMICA-Uploader/1.0

File hashes

Hashes for swarmica_engine-13.0.0.tar.gz
Algorithm Hash digest
SHA256 b2404c10be69ee4fbfb4d202fd6ae6b8257799ec7898384b9d7810cb2b55e13f
MD5 30e9854a634edfd85c8b72d0ec2f0a64
BLAKE2b-256 9319291e4f001b2173ae778a77002ff3eb302b3161c0cbefd0d07630a80f184b

See more details on using hashes here.

File details

Details for the file swarmica_engine-13.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for swarmica_engine-13.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3467d354f2175404e8b5c4d87030d0ba5cb7972c2ddff7115c8bce95cdf8a091
MD5 226a95498087d79edfcb2619c70eea80
BLAKE2b-256 b33044475873c902fe2912a82d618473eb5c015cacaa0aabd3cc77018b876673

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page