# Co-MADDPG: 面向语义与传统混合通信的合作竞争多智能体资源分配框架

**Co-MADDPG: Cooperative-Competitive Multi-Agent Resource Allocation for Semantic-Traditional Hybrid Wireless Communication**

---

## 项目简介 / Project Overview

本项目实现了 Co-MADDPG 算法——一种基于 Stackelberg 博弈和动态合作-竞争切换机制的多智能体深度强化学习框架，用于语义通信与传统比特级通信共存场景下的 OFDMA 无线资源分配。

This project implements the Co-MADDPG algorithm — a multi-agent deep reinforcement learning framework based on Stackelberg game dynamics and dynamic cooperation-competition switching for OFDMA wireless resource allocation in semantic-traditional hybrid communication systems.

### 核心创新 / Key Innovations

1. **合作竞争博弈建模 / Coopetition Game Modeling**: 将语义用户 (Leader) 与传统用户 (Follower) 之间的资源竞争建模为 Stackelberg 博弈
2. **动态 λ(t) 切换 / Dynamic λ(t) Switching**: `λ(t) = sigmoid(β·(QoE_sys - Q_th))`，根据系统 QoE 在合作与竞争之间自适应切换
3. **异构 QoE 指标 / Heterogeneous QoE**: 语义用户使用 SSim + 压缩率，传统用户使用速率满足度
4. **CTDE 架构 / CTDE Architecture**: 集中训练分散执行，联合 Critic 网络

### 目标期刊 / Target Venue

IEEE Transactions on Communications (TCOM)

---

## 环境要求 / Requirements

### Python 版本 / Python Version
- Python 3.8+

### 依赖库 / Dependencies

```bash
pip install numpy torch pyyaml matplotlib
```

| 库 / Library | 版本 / Version | 用途 / Purpose |
|---|---|---|
| `numpy` | ≥1.20 | 数值计算、信道建模 / Numerical computation, channel modeling |
| `torch` | ≥1.10 (CPU 或 GPU) | 神经网络训练 / Neural network training |
| `pyyaml` | ≥5.0 | 配置文件加载 / Configuration file loading |
| `matplotlib` | ≥3.4 | IEEE 风格绘图 / IEEE-style plotting |

### 硬件建议 / Hardware Recommendations

| 场景 / Scenario | 配置 / Configuration |
|---|---|
| 功能验证 (Smoke Test) | CPU, 2-5 episodes, ~30 秒 |
| 短期训练 (Short Training) | CPU/GPU, 100-500 episodes, ~10-60 分钟 |
| 完整训练 (Full Training) | GPU (CUDA), 5000 episodes, ~2-8 小时 |

---

## 快速开始 / Quick Start

### 1. 克隆项目 / Clone

```bash
git clone <repo-url>
cd SemantiCommunication/code
```

### 2. 功能验证 (Smoke Test)

```bash
# 训练 Co-MADDPG 2 个 episode（验证代码逻辑）
python train.py --algo co_maddpg --episodes 2 --steps 10

# 训练所有 8 个算法各 2 个 episode
python train.py --algo all --episodes 2 --steps 10
```

### 3. 正式训练 / Full Training

```bash
# 单算法训练（推荐先跑主算法）
python train.py --algo co_maddpg --episodes 5000

# 训练全部 8 个算法
python train.py --algo all --episodes 5000

# 指定配置文件
python train.py --algo co_maddpg --config configs/default.yaml --episodes 5000
```

### 4. 评估与绘图 / Evaluation & Plotting

```bash
# 运行全部 8 个评估场景，生成 12+ 张图
python evaluate.py

# 指定结果目录
python evaluate.py --results_dir results/
```

---

## 支持的算法 / Supported Algorithms

| # | 算法 / Algorithm | CLI 名称 | λ | 更新方式 / Update | Critic 类型 | 用途 / Purpose |
|---|---|---|---|---|---|---|
| 1 | **Co-MADDPG** | `co_maddpg` | 动态 dynamic | Stackelberg | Joint (CTDE) | 本文提出 / Proposed |
| 2 | PureCooperative | `pure_coop` | 1.0 | Simultaneous | Joint | 消融：去除竞争 / Ablate competition |
| 3 | PureCompetitive | `pure_comp` | 0.0 | Simultaneous | Joint | 消融：去除合作 / Ablate cooperation |
| 4 | FixedLambda | `fixed_lambda` | 0.5 | Stackelberg | Joint | 消融：去除动态 λ / Ablate dynamic λ |
| 5 | IDDPG | `iddpg` | 0.0 | Simultaneous | Independent | 消融：去除 CTDE / Ablate CTDE |
| 6 | SingleAgentDQN | `single_dqn` | 0.5 | N/A | Centralized | 非 MARL 基线 / Non-MARL baseline |
| 7 | EqualAllocation | `equal_alloc` | 0.5 | N/A | None | 性能下界 / Lower bound |
| 8 | SemanticOnly | `semantic_only` | 1.0 | N/A | Single | 消融：去除异构性 / Ablate heterogeneity |

---

## 项目结构 / Project Structure

```
SemantiCommunication/code/
│
├── configs/                     # 配置文件 / Configuration
│   ├── __init__.py
│   └── default.yaml             # 主配置（超参数、环境参数）/ Main config
│
├── envs/                        # 环境模块 / Environment modules
│   ├── __init__.py
│   ├── channel_model.py         # 3GPP 信道模型 / 3GPP channel model (Eq.5-8)
│   ├── semantic_module.py       # 语义相似度 SSim / Semantic similarity (SSim)
│   └── wireless_env.py          # Gym 风格无线环境 / Gym-like wireless env
│
├── agents/                      # 核心算法 / Core algorithm
│   ├── __init__.py
│   ├── actor.py                 # Actor 网络 FC→Tanh→[0,1]
│   ├── critic.py                # Critic 网络 (Joint Q-value)
│   ├── noise.py                 # OU 探索噪声 / OU exploration noise
│   ├── replay_buffer.py         # 9-field 经验回放 / 9-field replay buffer
│   └── co_maddpg.py             # Co-MADDPG 主算法 / Main algorithm (★)
│
├── baselines/                   # 7 个基线算法 / 7 baseline algorithms
│   ├── __init__.py
│   ├── pure_coop.py             # λ=1 纯协作
│   ├── pure_comp.py             # λ=0 纯竞争
│   ├── fixed_lambda.py          # λ=0.5 固定
│   ├── iddpg.py                 # 独立 DDPG (无 CTDE)
│   ├── single_dqn.py            # 集中式 DQN
│   ├── equal_alloc.py           # 均分分配
│   └── semantic_only.py         # 仅语义 DDPG
│
├── utils/                       # 工具模块 / Utility modules
│   ├── __init__.py
│   ├── metrics.py               # 评估指标 (Jain fairness, λ, rewards)
│   └── visualization.py         # IEEE 风格绘图 (12 种图)
│
├── train.py                     # 训练入口 / Training entry point (★)
├── evaluate.py                  # 评估入口 / Evaluation entry point (★)
├── README.md                    # 本文件 / This file
├── ARCHITECTURE.md              # 架构设计文档 / Architecture document
├── API.md                       # API 接口文档 / API reference
└── results/                     # 训练结果输出 / Training output directory
```

---

## 配置说明 / Configuration

配置文件位于 `configs/default.yaml`，主要分为 4 个部分：

### env（环境参数）

| 参数 | 默认值 | 说明 |
|---|---|---|
| `num_subcarriers` | 64 | OFDMA 子载波数 N |
| `bandwidth` | 10.0e+6 | 系统带宽 (Hz) |
| `subcarrier_spacing` | 156250.0 | 子载波间隔 Δf (Hz) |
| `max_power` | 1.0 | 最大发射功率 (W) |
| `noise_psd` | -174 | 噪声功率谱密度 (dBm/Hz) |
| `carrier_freq` | 3.5 | 载波频率 (GHz) |
| `num_semantic_users` | 3 | 语义用户数 K_s |
| `num_traditional_users` | 3 | 传统用户数 K_b |
| `min_rate_req` | 5.0e+5 | 传统用户最低速率需求 (bps) |
| `rho_max` / `rho_min` | 1.0 / 0.05 | 压缩率范围 |
| `w1` / `w2` | 0.7 / 0.3 | 语义 QoE 权重 |

### training（训练参数）

| 参数 | 默认值 | 说明 |
|---|---|---|
| `max_episodes` | 5000 | 最大训练轮数 |
| `max_steps` | 200 | 每轮最大步数 |
| `batch_size` | 256 | 批量大小 |
| `buffer_capacity` | 100000 | 经验回放容量 |
| `actor_lr` / `critic_lr` | 1e-4 / 3e-4 | 学习率 |
| `gamma` | 0.95 | 折扣因子 |
| `tau` | 0.01 | 软更新系数 |
| `beta` | 5.0 | λ(t) sigmoid 的陡度 |
| `q_threshold` | 0.6 | λ(t) 切换阈值 Q_th |

### network（网络结构）

| 参数 | 默认值 | 说明 |
|---|---|---|
| `actor_hidden` | [256, 256, 128] | Actor 隐藏层 |
| `critic_hidden` | [512, 512, 256] | Critic 隐藏层 |

### reward（奖励权重）

| 参数 | 默认值 | 说明 |
|---|---|---|
| `coop_self` / `coop_other` / `coop_sys` | 0.5 / 0.3 / 0.2 | 合作奖励权重 |
| `comp_self` / `comp_sys` | 0.8 / 0.2 | 竞争奖励权重 |

---

## 关键公式 / Key Formulas

| 公式 | 表达式 | 论文编号 |
|---|---|---|
| 路径损耗 / Path Loss | `PL(d) = 36.7·log₁₀(d) + 22.7 + 26·log₁₀(fc)` | Eq.(5) |
| 信道增益 / Channel Gain | `h_{k,n} ~ CN(0, 10^{-PL/10})` | Eq.(6) |
| 噪声功率 / Noise Power | `σ² = 10^{(N₀_dBm-30)/10} · Δf` | Eq.(7) |
| 信噪比 / SNR | `γ_{k,n} = p_{k,n} · \|h_{k,n}\|² / σ²` | Eq.(8) |
| 语义相似度 / SSim | `φ(γ̄,ρ) = 1 - exp(-a(ρ)·γ̄^{b(ρ)})` | — |
| 语义 QoE | `QoE_s = 0.7·SSim + 0.3·(1-ρ/ρ_max)` | — |
| 传统 QoE | `QoE_b = min(R_k/R_req, 1)` | — |
| 动态 λ | `λ(t) = sigmoid(β·(QoE_sys - Q_th))` | — |
| 混合奖励 | `r_i = λ·r_coop + (1-λ)·r_comp` | — |

---

## 评估场景 / Evaluation Scenarios

`evaluate.py` 包含 8 个评估场景，对应论文 Section VII 的 12 张图：

| # | 场景 | 对应图表 | 说明 |
|---|---|---|---|
| 1 | Convergence | Fig.2 | 收敛曲线对比 |
| 2 | QoE vs SNR | Fig.3 | 不同 SNR 下的系统 QoE |
| 3 | Fairness vs SNR | Fig.4 | 不同 SNR 下的 Jain 公平性 |
| 4 | QoE vs Users | Fig.5 | 用户数量扩展性 |
| 5 | Rate Satisfaction vs Users | Fig.6 | 速率满足度 |
| 6 | Lambda Trajectory | Fig.7-8 | λ(t) 演化轨迹和散点图 |
| 7 | Ablation Study | Fig.10 | 消融实验柱状图 |
| 8 | Sensitivity | Fig.11-12 | β 和 Q_th 敏感性分析 |

---

## 输出文件 / Output Files

训练和评估产生的文件保存在 `results/` 目录：

```
results/
├── <algo_name>/
│   ├── model_s.pth              # 语义智能体模型权重
│   ├── model_b.pth              # 传统智能体模型权重
│   ├── training_log.json        # 训练指标日志
│   └── config_snapshot.yaml     # 训练时的配置快照
├── figures/
│   ├── fig02_convergence.png
│   ├── fig03_qoe_vs_snr.png
│   ├── ...
│   └── fig12_qth_sensitivity.png
└── evaluation_results.json      # 评估汇总数据
```

---

## 已知问题与注意事项 / Known Issues & Notes

1. **YAML 科学记数法**: 使用 `5.0e+5` 格式（非 `500.0e3`），否则 `yaml.safe_load()` 会将其解析为字符串
2. **Smoke Test QoE 值**: 2 episode 的 smoke test 中所有算法的 QoE 值相近（~0.7-0.9），这是因为网络尚未充分训练。需完整训练（5000 episodes）才能看到显著差异
3. **GPU 加速**: 默认自动检测 CUDA。CPU 训练较慢但功能完整
4. **随机种子**: 默认 seed=42，可在配置中修改

---

## 论文引用 / Citation

如引用本工作，请参考论文：

> Co-MADDPG: 面向语义与传统混合通信的合作竞争多智能体资源分配框架

论文文件位于 `../paper/` 目录。

---

## License

MIT License