# CatOpt-Swarm

Safe, verifiable distributed optimization for robotic swarms.

CatOpt-Swarm models swarm coordination as a small validated IR:

- `LocalProblem` captures each robot's local objective and state.
- `PlanDelta` carries deterministic, contract-tagged updates.
- `SharedVariables` stores consensus state and versioning.
- `SafetyPolicy` enforces travel, separation, and energy limits.
- `ContractRegistry` records adapter and mission contracts as a graph.

The solver is a deterministic ADMM-lite loop with:

- bounded-step local updates
- delta reconciliation with bounded staleness
- separation projection for collision avoidance
- audit logs and convergence certificates

## Package Layout

- `catopt_swarm.models`
- `catopt_swarm.registry`
- `catopt_swarm.adapters`
- `catopt_swarm.solver`
- `catopt_swarm.verification`
- `catopt_swarm.cli`

## Install

```bash
python3 -m pip install -e .
```

## Run

```bash
python3 -m catopt_swarm.cli
```

Or use the compatibility script:

```bash
python3 admm_solver.py
```

## Test

```bash
bash test.sh
```

## What the demo covers

- Two-robot consensus planning
- Adapter conformance checks for aerial and ground controllers
- Graph-based contract registration
- Safety verification after solve

## Notes

This repository currently focuses on the core planning and verification substrate. The next extension point is integrating ROS/Gazebo-backed mission replay and richer platform adapters.