# algorithm_verification

**Repository Path**: zera12138/algorithm_verification

## Basic Information

- **Project Name**: algorithm_verification
- **Description**: 控制算法验证和学习
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Algorithm Verification — 算法验证仓库

本仓库用于**控制算法与强化学习算法的验证与对比**，以倒立摆 (Cartpole) 等经典任务为载体，统一仿真环境（MuJoCo）、统一评测口径，从经典控制算法逐步递进到强化学习算法。

## 分支架构 (Branch Architecture)

仓库按**算法类别**分分支管理，`main` 分支仅存放仓库说明与分支索引：

| 分支 | 内容 | 说明 |
|------|------|------|
| `main` | 本说明（分支架构 + 工程架构） | 仓库入口，默认分支 |
| `traditional-algorithm` | `cartpole_ctrl/` | **传统算法分支**：经典控制算法（PID / LQR / MPC / Linear-MPC）C++ 实现，基于 MuJoCo 物理引擎 |
| `rl-algorithm` | 占位说明 | **强化学习算法分支**：DQN / PPO / SAC 等 RL 算法（规划中） |

### 获取方式

```bash
# 拉取传统算法分支（当前唯一含代码的分支）
git clone -b traditional-algorithm https://gitee.com/zera12138/algorithm_verification.git

# 拉取强化学习算法分支
git clone -b rl-algorithm https://gitee.com/zera12138/algorithm_verification.git

# 克隆全部内容
git clone https://gitee.com/zera12138/algorithm_verification.git
git branch -a
```

### 分支演进约定

- 新增**传统算法**项目（如其他经典任务、新控制器）→ 提交到 `traditional-algorithm` 分支；
- 新增**强化学习**算法 → 提交到 `rl-algorithm` 分支；
- 各分支自包含，互不依赖；跨类别对比时分别检出相应分支。

## 工程架构 (Project Architecture)

### traditional-algorithm 分支：`cartpole_ctrl`

基于 MuJoCo 物理引擎的倒立摆控制算法验证框架，从 PID → LQR → MPC 逐步递进。

**分层设计**：每个控制器是独立的 `.h`/`.cpp` 对，继承统一基类 `Controller`，通过共享的仿真运行器 (`sim_runner.h`) 驱动，易于扩展新算法。

```
cartpole_ctrl/
├── CMakeLists.txt                    # CMake 构建配置 (C++17)
├── models/
│   └── cartpole.xml                  # 自包含倒立摆模型 (MuJoCo MJCF)
├── include/cartpole_ctrl/
│   ├── types.h                       # 公共类型定义 (状态向量, 配置等)
│   ├── environment.h                 # MuJoCo 环境封装
│   ├── controller.h                  # 控制器抽象基类
│   ├── pid_controller.h              # PID 控制器
│   ├── lqr_controller.h              # LQR 控制器
│   ├── mpc_controller.h              # MPC (iLQR) 控制器
│   └── linear_mpc_controller.h       # Linear-MPC 控制器
├── src/                              # 各控制器实现
├── apps/
│   ├── sim_runner.h                  # 通用仿真运行器 (共享)
│   ├── main_pid.cpp / main_lqr.cpp   # 各控制器独立 demo
│   ├── main_mpc.cpp / main_linear_mpc.cpp
│   └── main_demo.cpp                 # 多控制器对比 demo
├── python/                           # 可视化/绘图脚本 (run_sim, plot_scope 等)
├── docs/                             # 控制理论推导与调参记录 (control_theory.md 等)
├── plots/                            # 仿真结果图
└── claude_fable_code/                # 早期独立版本的单文件实现
```

**控制器一览**：

| 控制器 | 原理 | 特点 |
|--------|------|------|
| PID | 能量泵送摆起 + PD 平衡 | 无需模型，实时性极高，需手动调参 |
| LQR | 平衡点线性化 + CARE 求解，增益离线计算 | 平衡点附近理论最优，运行时仅矩阵乘法 |
| MPC (iLQR) | 滚动时域优化：前向 rollout + 反向递推 + line search | 处理非线性/约束，自动 swingup，计算量大 |
| Linear-MPC | 基于 LQR 增益的近似 MPC | 折中方案 |

**依赖**：MuJoCo 2.1.0、Eigen3、CMake ≥ 3.14、C++17。构建与运行方式见该分支内 `cartpole_ctrl/README.md`。

### rl-algorithm 分支（规划中）

将逐步加入深度强化学习算法在 Cartpole 任务上的实现与对比：

- DQN / Double DQN：离散动作空间
- PPO / SAC：连续动作空间
- 与传统算法分支的控制器进行统一基准对比

## 相关说明

- 倒立摆模型来自 Google DeepMind `dm_control` (Apache 2.0 License)
- 各分支详细文档：`cartpole_ctrl/README.md`、`docs/`（控制理论推导）