SAGIN Network Simulation

A comprehensive Space-Air-Ground Integrated Network (SAGIN) simulation framework with hierarchical reinforcement learning capabilities.

🚀 Quick Start

# Clone the repository
git clone <repository-url>
cd SAGIN

# Install dependencies
pip install -r requirements.txt

# Run the simulation
python examples/sagin_demo.py

📋 Overview

This simulation framework provides:

• Multi-layer network architecture: Vehicles, UAVs, and satellites
• Configurable scenarios: Pre-defined and custom configurations
• Hierarchical RL integration: Dynamic UAV allocation and task offloading
• Comprehensive metrics: Performance analysis and visualization
• Grid-based topology: Flexible network layouts

🏗️ Architecture

System Layers

SAGIN Network
├── Ground Layer: Vehicles (random movement, bus routes)
├── Air Layer: UAVs (static per region, dynamic repositioning)
└── Space Layer: Satellites (constellation with orbital mechanics)

Network Architecture Diagram

graph TB
    subgraph "Space Layer"
        S1[Satellite 1]
        S2[Satellite 2]
        S3[Satellite N]
    end
  
    subgraph "Air Layer"
        subgraph "Static UAVs"
            U1[Static UAV R1]
            U2[Static UAV R2]
            U3[Static UAV RN]
        end
        subgraph "Dynamic UAVs"
            D1[Dynamic UAV 1]
            D2[Dynamic UAV 2]
            D3[Dynamic UAV N]
        end
    end
  
    subgraph "Ground Layer"
        subgraph "Region 1"
            V1[Vehicles]
            T1[Tasks]
        end
        subgraph "Region 2"
            V2[Vehicles]
            T2[Tasks]
        end
        subgraph "Region N"
            V3[Vehicles]
            T3[Tasks]
        end
    end
  
    V1 -.->|Generate| T1
    V2 -.->|Generate| T2
    V3 -.->|Generate| T3
  
    T1 -->|Offload| U1
    T2 -->|Offload| U2
    T3 -->|Offload| U3
  
    U1 <-->|Forward| D1
    U2 <-->|Forward| D2
    U3 <-->|Forward| D3
  
    U1 -->|Escalate| S1
    U2 -->|Escalate| S2
    U3 -->|Escalate| S3
  
    D1 -.->|Reposition| U2
    D2 -.->|Reposition| U3
  
    style S1 fill:#e1f5ff
    style S2 fill:#e1f5ff
    style S3 fill:#e1f5ff
    style U1 fill:#ffe1e1
    style U2 fill:#ffe1e1
    style U3 fill:#ffe1e1
    style D1 fill:#fff4e1
    style D2 fill:#fff4e1
    style D3 fill:#fff4e1

Loading

📊 Available Configurations

Configuration	Grid Size	Vehicles	UAVs	Satellites	Use Case
small_test	2×3	13	2	4	Quick testing
medium_demo	4×4	40	5	8	Standard demo
large_simulation	5×10	100	15	12	Performance testing
highway_scenario	1×20	75	8	6	Highway simulation
city_scenario	8×12	180	20	16	Dense urban
sparse_rural	6×8	30	6	10	Rural coverage

🎯 Key Features

Configuration System

• No code changes needed for different scenarios
• Grid-based topology with configurable dimensions
• Vehicle distribution (random walkers, bus routes)
• UAV management (static per region + dynamic reallocation)
• Satellite constellations with orbital mechanics
• Task generation with burst events

Performance Models

• Shannon capacity for data rate calculations
• Latency modeling with propagation, transmission, queuing delays
• Load balancing metrics and optimization
• Energy consumption tracking

Hierarchical RL Module

• Central agent for dynamic UAV allocation
• Local agents for task offloading decisions
• MDP formulation based on research paper
• Reward structure optimizing success rate and load balance

🧠 Reinforcement Learning Design

Hierarchical RL Architecture

graph TB
    subgraph "Hierarchical RL System"
        subgraph "Central Agent (Actor-Critic)"
            CA[Central Agent]
            AS[Actor Network]
            CS[Critic Network]
            CA --> AS
            CA --> CS
        end
      
        subgraph "Local Agents (DQN)"
            LA[Shared Static UAV Agent]
            QN[Q-Network]
            TN[Target Q-Network]
            LA --> QN
            LA --> TN
        end
    end
  
    subgraph "SAGIN Environment"
        GS[Global State]
        LS[Local State]
        NET[Network Simulation]
    end
  
    GS -->|Task arrival rates<br/>Queue lengths<br/>Energy levels<br/>UAV positions| CA
    CA -->|Dynamic UAV<br/>Allocation| NET
  
    LS -->|Queue length<br/>Energy<br/>Available resources<br/>Task intensity| LA
    LA -->|Task Offloading<br/>Decisions| NET
  
    NET -->|Rewards| CA
    NET -->|Rewards| LA
  
    style CA fill:#bbdefb
    style AS fill:#90caf9
    style CS fill:#90caf9
    style LA fill:#c8e6c9
    style QN fill:#a5d6a7
    style TN fill:#a5d6a7
    style GS fill:#fff9c4
    style LS fill:#fff9c4

Loading

State-Action-Reward Flow

sequenceDiagram
    participant Env as SAGIN Environment
    participant CA as Central Agent
    participant LA as Local Agent
    participant Net as Network Simulator
  
    Note over Env,Net: Episode t
  
    Env->>CA: Global State s^global_t<br/>{λ_r, L_r, E_r, A_n, x_n}
    CA->>CA: Select Action (ε-greedy)<br/>UAV Allocation
    CA->>Net: Execute Central Action<br/>A^dyn(t)
  
    loop For each region r
        Env->>LA: Local State s^local_r,t<br/>{Q_r, E_r, N^dyn_r, Λ_r}
        LA->>LA: Select Action (ε-greedy)<br/>Task Decision
        LA->>Net: Execute Local Action<br/>D_j(t) ∈ {local, dynamic, satellite}
    end
  
    Net->>Net: Simulate Network<br/>Process Tasks
  
    Net->>CA: Reward r^global_t<br/>Success - α₁·ΔL - α₂·Energy
    Net->>LA: Reward r^local_r,t<br/>Task Completion
  
    CA->>CA: Update Policy<br/>(Actor-Critic)
    LA->>LA: Update Q-Network<br/>(DQN with Target Network)

Loading

Neural Network Architectures

graph LR
    subgraph "Central Agent: Actor-Critic"
        CS[State Input<br/>λ_r, L_r, E_r, A_n, x_n]
      
        subgraph "Actor Network"
            A1[Dense 256 + ReLU]
            A2[Dense 256 + ReLU]
            A3[Dense 128 + ReLU]
            A4[Dense action_dim + Softmax]
            A_OUT[Action Probabilities]
        end
      
        subgraph "Critic Network"
            C1[Dense 256 + ReLU]
            C2[Dense 256 + ReLU]
            C3[Dense 128 + ReLU]
            C4[Dense 1]
            C_OUT[State Value]
        end
      
        CS --> A1 --> A2 --> A3 --> A4 --> A_OUT
        CS --> C1 --> C2 --> C3 --> C4 --> C_OUT
    end
  
    subgraph "Local Agent: DQN"
        LS[State Input<br/>Q_r, E_r, N^dyn_r, Λ_r]
      
        subgraph "Q-Network"
            Q1[Dense 128 + ReLU]
            Q2[Dense 128 + ReLU]
            Q3[Dense 64 + ReLU]
            Q4[Dense 3]
            Q_OUT[Q-Values<br/>local, dynamic, satellite]
        end
      
        LS --> Q1 --> Q2 --> Q3 --> Q4 --> Q_OUT
    end
  
    style CS fill:#fff9c4
    style LS fill:#fff9c4
    style A_OUT fill:#a5d6a7
    style C_OUT fill:#90caf9
    style Q_OUT fill:#ce93d8

Loading

Reward Function

The reward function balances multiple objectives:

$$ r_t = \sum_j I(T_{total,j} \leq \tau_j) - \alpha_1 \cdot \Delta L_t - \alpha_2 \cdot \sum_v I(E_v(t) < E_{min}) $$

Where:

• First term: Task success rate (completed within deadline)
• Second term: Load imbalance penalty (α₁ = 0.1)
• Third term: Energy constraint penalty (α₂ = 0.0)

🔧 Configuration

Edit config/grid_config.py to customize:

# Example custom configuration
custom_config = SAGINConfig(
    name="my_scenario",
    grid=GridConfig(
        grid_rows=3,
        grid_cols=5,
        area_bounds=(0.0, 15000.0, 0.0, 9000.0)
    ),
    vehicles=VehicleConfig(
        random_vehicles=50,
        bus_vehicles=10
    ),
    uavs=UAVConfig(
        dynamic_uavs=8
    ),
    # ... other settings
)

📈 Usage Examples

Basic Simulation

from examples.sagin_demo import SAGINDemo

demo = SAGINDemo()
network = demo.run_simulation("medium_demo")
demo.print_summary(network)

Custom Configuration

from config.grid_config import get_sagin_config

config = get_sagin_config("highway_scenario")
network = demo.create_network("highway_scenario")

RL Training

from src.rl.trainers import HierarchicalRLTrainer

trainer = HierarchicalRLTrainer(network)
trainer.train(num_episodes=1000)

📊 Metrics and Analysis

The simulation provides comprehensive metrics:

• Task Success Rate: Percentage of tasks completed within deadline
• Average Latency: End-to-end task completion time
• Load Imbalance: Distribution of workload across UAVs
• Resource Utilization: UAV and satellite usage efficiency
• Energy Consumption: Power usage tracking
• Coverage: Network coverage percentage

🧪 Testing

📁 Project Structure

SAGIN/
├── config/                 # Configuration files
│   └── grid_config.py     # Main configuration system
├── src/
│   ├── core/              # Core simulation components
│   │   ├── network.py     # Main network orchestrator
│   │   ├── vehicles.py    # Vehicle management
│   │   ├── uavs.py        # UAV models
│   │   ├── satellites.py  # Satellite constellation
│   │   └── tasks.py       # Task generation and management
│   ├── models/            # Mathematical models
│   │   ├── communication.py # Shannon capacity, path loss
│   │   └── latency.py     # Latency components
│   └── rl/                # Reinforcement learning
│       ├── environment.py # RL environment
│       ├── agents.py      # Central and local agents
│       └── trainers.py    # Training algorithms
├── examples/
│   └── sagin_demo.py      # Main demonstration script
├── docs/                  # Documentation
└── tests/                 # Test files

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📄 License

[Add your license information here]

🙋 Support

For questions and support:

• Check the documentation in docs/
• Run tests to verify installation
• Review configuration examples in config/