Skip to content
garykuepperPublic

About

A fully decentralized coordination framework where global formation behavior emerges naturally from local agent interactions. By combining Graph Neural Networks for spatial reasoning with advanced trajectory optimization for flight dynamics, the system achieves a robust and fault-tolerant solution for complex aerial maneuvers

Resources

Stars

17 stars

Watchers

1 watching

Forks

Repository files navigation

Ruff License: MIT Python 3.11 Isaac Lab Isaac Sim Capstone

ggSwarm — A Decentralized Drone Swarm

A learned, graph-attention-based multi-drone formation policy, and the research program taking a sim-only capstone toward a real, decentralized swarm on hardware.

Two programs in one repo

ggSwarm Capstone (v1, shipped April 2026)

A simulation-only multi-agent RL drone swarm. Tested whether a single GATv2 + PPO policy can replace hand-designed multi-agent coordination logic. Yes, within tested scope: 8 drones hold triangle, polygon, and letter-G formations with <0.3 m steady-state error, recover from mid-episode dropout within 2 s — this mechanism is named DropoutGuard in the active codebase (renamed from a misnomer; it predates and is unrelated to the SwarmRaft-paper-derived localization work in ggSwarm Live) — navigate cylinder forests, and the same policy generalizes to 20 agents without retraining.

Frozen at tag v1.0.0-capstone on the capstone branch. All documentation, phase write-ups, testing report, and run history live under docs/capstone/.

ggSwarm highlight

ggSwarm Live

Direction changed 2026-09-23. A three-survey review of real swarms moved the plan to a deterministic plan-and-certify core first (ggChoreo, private), then online decentralized replanning behind a safety filter, with this repo's GATv2+PPO policy kept as a benchmarked challenger. The program is parked behind a gate; see the ggSkyGrid plan (private). The description below is the July 2026 plan and is kept as history.

Real-hardware research program. Takes the capstone policy out of an idealized, centralized simulation and makes it work decentralized, under real aerodynamics, and eventually on real drones. Two phases: Phase 1 (sim) — proper decentralization (no anchors, no central coordinator) and downwash/aero physics fidelity — then Phase 2 (hardware) — a goal list, not a detailed plan, for getting the policy flying on real drones. See docs/ggswarm_live/vision.md.

Phase 1's decentralization work runs on the ggswarm-marl-v0 task (shared-scene MAPPO, GgswarmMarlEnv) rather than the capstone's single-agent ggswarm-v0. The peer-to-peer localization slice — drones estimating their own position from simulated UWB ranging and onboard odometry instead of reading it from the simulator — is implemented in shadow mode (obs still ground truth, estimator runs and logs) with Isaac-side validation pending; see docs/ggswarm_live/decentralization_plan.md for the design and staged rollout.

The drone-light-show project is ggSkylight, a separate repo. Since 2026-09-23 both share the ggChoreo planner, and ggSkylight's show drone is the planned outdoor platform. The earlier combined plan is preserved at docs/ggswarm_live/archive/ for reference.

Table of Contents

Project Navigation

Top-level docs splitter: docs/README.md.

ggSwarm Live

Capstone (frozen)

Quickstart

The current installable code is the capstone simulation stack (ggswarm-v0 Isaac Lab task). Hardware work (Crazyflie, then the ArduPilot show drone) is gated in the ggSkyGrid plan.

Isaac Lab is expected to be installed inside your Python virtual environment. No sibling IsaacLab repository clone is required for this project setup.

  1. Clone the repo:

    git clone https://github.com/garykuepper/ggSwarm.git
    cd ggSwarm
  2. Create and activate a Python 3.11 virtual environment:

    py -3.11 -m venv env_isaaclab
    env_isaaclab\Scripts\activate
    python -m pip install --upgrade pip
  3. Install Isaac Sim and Isaac Lab into the active virtual environment:

  4. Install this package:

    pip install -e source/ggswarm
  5. If you encounter Windows HDF5 DLL conflicts, pin h5py:

    pip install "h5py>=3.9.0,<3.12" --force-reinstall

Training and Playback (capstone-era sim)

The capstone training and playback workflow still runs from this branch against ggswarm-v0. The capstone tree is frozen but the code path is not — Phase 1 of ggSwarm Live (shared-scene multi-drone training) builds on it directly.

# Train (local, headless)
env_isaaclab/Scripts/python.exe scripts/skrl/train.py --headless `
  --task ggswarm-v0 --num_envs 512 --max_iterations 500 --log_subdir p2a

# Play a checkpoint (GUI)
python scripts/skrl/play.py --task ggswarm-v0 `
  --checkpoint logs/skrl/ggswarm/p2a/<run>/checkpoints/best_agent.pt

# Record video (NVENC H.264)
python scripts/skrl/play.py --task ggswarm-v0 `
  --checkpoint <path> --video --video_prefix p2a-1

# Generate trajectory diagnostic plots
python scripts/skrl/play.py --task ggswarm-v0 `
  --checkpoint <path> --trajectories

# TensorBoard
tensorboard --logdir logs/skrl/ggswarm

For capstone-era training operations (GCE launches, log-sync workflow, post-training analysis), see docs/capstone/ops/.

Pure-Torch Test Suite (Phase 1 localization)

The ggswarm.ranging and ggswarm.localization modules (simulated UWB peer ranging and the decentralized position estimator) are pure torch with no Isaac dependency, so their tests run without Isaac Sim installed — useful for fast iteration on any machine, including CI:

python -m venv .venv-tests
.venv-tests/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu
.venv-tests/bin/pip install pytest
.venv-tests/bin/python -m pytest tests/ -q

See docs/ggswarm_live/decentralization_plan.md for what these modules do and the staged plan for wiring them into the live training obs pipeline.

Troubleshooting

  • ModuleNotFoundError: No module named 'isaacsim'
    • Ensure the venv is active: env_isaaclab\Scripts\activate
  • ModuleNotFoundError: No module named 'isaaclab'
    • Isaac Lab is not installed in the active venv
  • Long path errors on Windows
    • Enable long path support (LongPathsEnabled = 1)
  • ImportError: DLL load failed while importing _errors (h5py)
    • Run: pip install "h5py>=3.9.0,<3.12" --force-reinstall

License

Developed with Claude Code

This project is licensed under the MIT License. See LICENSE.

About

A fully decentralized coordination framework where global formation behavior emerges naturally from local agent interactions. By combining Graph Neural Networks for spatial reasoning with advanced trajectory optimization for flight dynamics, the system achieves a robust and fault-tolerant solution for complex aerial maneuvers

Resources

Stars

17 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages