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.
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/.
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.
- Two programs in one repo
- Project Navigation
- Quickstart
- Training and Playback (capstone-era sim)
- Pure-Torch Test Suite (Phase 1 localization)
- License
Top-level docs splitter: docs/README.md.
- Program overview
- Vision
- Decentralization detail plan — peer-to-peer localization design and staged rollout
- Phases: 0 capstone baseline · 1 sim: decentralization + downwash · 2 hardware transfer
- Backlog — loose, unscheduled ideas
- References
- Archive — earlier 18-phase plan, kept for reference
- Status: changelog · log
- Capstone README
- Architecture · Assumptions · Tensor contracts
- Proposal · Testing Report
- Phases: 1 · 2 · 3 · 4 · 5 · 6
- Concepts — ML / RL / GNN glossary
- Status: weekly updates · changelog · run history
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
IsaacLabrepository clone is required for this project setup.
-
Clone the repo:
git clone https://github.com/garykuepper/ggSwarm.git cd ggSwarm
-
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
-
Install Isaac Sim and Isaac Lab into the active virtual environment:
- Isaac Sim pip package: NVIDIA Isaac Sim
- Isaac Lab install docs: Isaac Lab Installation
-
Install this package:
pip install -e source/ggswarm
-
If you encounter Windows HDF5 DLL conflicts, pin
h5py:pip install "h5py>=3.9.0,<3.12" --force-reinstall
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/ggswarmFor capstone-era training operations (GCE launches, log-sync workflow,
post-training analysis), see
docs/capstone/ops/.
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/ -qSee docs/ggswarm_live/decentralization_plan.md
for what these modules do and the staged plan for wiring them into the
live training obs pipeline.
ModuleNotFoundError: No module named 'isaacsim'- Ensure the venv is active:
env_isaaclab\Scripts\activate
- Ensure the venv is active:
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)
- Enable long path support (
ImportError: DLL load failed while importing _errors(h5py)- Run:
pip install "h5py>=3.9.0,<3.12" --force-reinstall
- Run:
Developed with Claude Code
This project is licensed under the MIT License. See LICENSE.

