DocsEpisode I — Surviving the Jam

Getting started with Episode I

Install Surviving the Jam and explore multi-agent coordination under communication jamming.

Welcome to Swarm Squad Episode I: Surviving the Jam, a specialized simulation framework focusing on hybrid control architecture for autonomous multi-agent systems in communication-challenged environments.

What is Episode I?

Swarm Squad Episode I is a research-focused simulation framework that explores how multi-agent systems can maintain coordination and achieve objectives when communication is disrupted or jammed. The framework features:

Hybrid control architecture: Combines behavior-based and formation control approaches
Communication jamming simulation: Models realistic communication disruptions
LLM integration: Incorporates Large Language Models for high-level decision making
Formation control: Advanced algorithms for maintaining swarm formations
Adaptive behavior: Agents that adapt to changing communication conditions
Real-time visualization: Interactive GUI for monitoring swarm behavior
Research-oriented: Built for academic research and experimental studies

Quick start

For most users, getting started with Episode I is as simple as:

# Install Swarm Squad Episode I
uv pip install swarm-squad-ep1
 
# Run the application
swarm-squad-ep1
swarm-squad-ep1 --help

That's it. The application will start and you can begin exploring communication-challenged multi-agent systems.

Prerequisites

For basic usage, you only need:

uv: For package installation and management (recommended)

Installing uv

If you don't have uv installed, you can install it using:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation

Option 1: Install from PyPI (recommended)

The simplest way to install Episode I is directly from PyPI:

# Install the package using uv
uv pip install swarm-squad-ep1

Option 2: Development installation

For contributors, developers, or if you plan to modify the framework:

Additional prerequisites for development:

git: For cloning the repository
ruff: For code linting and formatting
pre-commit: For code quality hooks

# Clone the repository
git clone https://github.com/Sang-Buster/Swarm-Squad-Ep1
cd Swarm-Squad-Ep1
 
# Option 1 (Recommended): Synchronize environment with dependencies
uv sync
source .venv/bin/activate  # On Linux/macOS
# Or: .venv\Scripts\activate  # On Windows
 
# Option 2 (Manual): Create virtual environment manually
uv venv --python 3.10
source .venv/bin/activate  # On Linux/macOS
# Or: .venv\Scripts\activate  # On Windows
uv pip install -e .

Running Episode I

After installation, you can run Episode I using the command-line interface:

# Run with default settings
swarm-squad-ep1
 
# Show available options and help
swarm-squad-ep1 --help

Development setup

If you're planning to develop or extend Episode I, set up the development environment:

Install development tools

# Install development dependencies
uv pip install ruff pre-commit

Set up git hooks

# Install git hooks for code quality
pre-commit install --install-hooks

These hooks perform different checks at various stages:

commit-msg: Ensures commit messages follow the conventional format
pre-commit: Runs Ruff linting and formatting checks before each commit
pre-push: Performs final validation before pushing to remote

Code quality checks

# Run linting and formatting
ruff check --fix
ruff check --select I --fix
ruff format

Running from source

When developing, you can run directly from the source code:

uv run src/swarm_squad_ep1/main.py

Project structure

Understanding the Episode I file structure will help you navigate and extend the framework:

Swarm Squad Episode I
├── src/swarm_squad_ep1/             # Main source code
│   ├── controllers/                 # Control system implementations
│   │   ├── base_controller.py       # Base controller interface
│   │   ├── behavior_controller.py   # Behavior-based control
│   │   ├── formation_controller.py  # Formation control algorithms
│   │   ├── llm_controller.py        # LLM integration for decision making
│   │   └── controller_factory.py    # Controller management
│   ├── models/                      # Data models and state management
│   │   └── swarm_state.py           # Swarm formation state
│   ├── gui/                         # Graphical user interface
│   │   └── formation_control_gui.py # Main GUI implementation
│   ├── config/                      # Configuration files
│   │   └── config.py                # Simulation parameters
│   └── main.py                      # Application entry point
├── lib/                             # Supplementary materials
│   ├── papers/                      # Research papers
│   ├── presentations/               # Slides and presentations
│   └── simulations/                 # Original simulation results
├── pyproject.toml                   # Project configuration
└── uv.lock                          # Dependency lock file

Key components

Episode I includes several specialized components for communication-challenged environments:

Controllers

Located in src/swarm_squad_ep1/controllers/, these implement different control strategies:

base_controller.py: Defines the interface for all controllers
behavior_controller.py: Implements behavior-based control algorithms
formation_controller.py: Handles formation control and maintenance
llm_controller.py: Integrates Large Language Models for high-level decision making
controller_factory.py: Manages controller instantiation and selection

Models

Located in src/swarm_squad_ep1/models/:

swarm_state.py: Manages the state of the swarm formation and agent positions

GUI

Located in src/swarm_squad_ep1/gui/:

formation_control_gui.py: Provides real-time visualization and user interaction

Simulation configuration

The simulation behavior can be configured through parameters in src/swarm_squad_ep1/config/config.py, including:

Formation settings: Define swarm formation parameters and constraints
Communication parameters: Configure communication range and reliability
Jamming simulation: Set up communication disruption scenarios
Visualization options: Customize the GUI appearance and behavior
LLM integration: Configure language model parameters and endpoints

First simulation

Once you have Episode I installed, you can run your first simulation:

Launch the application:
bash
```
swarm-squad-ep1
```
Explore the GUI: The interface provides:
- Real-time swarm visualization
- Formation control parameters
- Communication status indicators
- Performance metrics dashboard
Run scenarios: Test different communication jamming scenarios to observe adaptive behavior

Supplementary materials

For more in-depth understanding, refer to the supplementary materials in the lib directory:

Research papers: Detailed theoretical background and methodology
Presentation slides: Visual explanations of key concepts and results
Original simulations: Implementation details and experimental results

Next steps

Now that you have Episode I installed and running, explore these areas:

Architecture: Understand the hybrid control system design
Configuration: Learn about simulation parameters and customization
Demo: Try out example scenarios and use cases
Research integration: Explore the academic papers and experimental results

Troubleshooting

If you encounter issues during installation or setup:

Common issues

Python version: Ensure you're using Python 3.10 or higher
Virtual environment: Always work within a virtual environment to avoid conflicts
Dependencies: Run uv pip install -e . again if you encounter import errors
GUI issues: Ensure you have the necessary graphics libraries installed

Getting help

Check the error messages for specific guidance
Review the logs in the terminal output
Ensure all prerequisites are correctly installed
Visit the project's GitHub repository for issue tracking and community support

With Episode I properly installed and configured, you're ready to explore adaptive multi-agent systems in communication-challenged environments.

Edit this page on GitHub