From 96da685582816f544792a180ce7580cbab6e7fe1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=91=B8=E9=B1=BC=E7=8E=8B?= <hongruliu@mail.nwpu.edu.cn>
Date: Fri, 6 Feb 2026 13:00:56 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0README?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 199 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d1763e8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,199 @@
+# AeroEngine Control Challenge: 航空发动机智能全包线控制挑战赛
+
+## 📖 项目简介 (Introduction)
+
+本项目提供了一个高保真的双转子涡扇发动机仿真环境，旨在探索**深度强化学习 (Deep RL)** 在复杂工业控制系统中的应用。
+
+参赛者需要设计一个智能 Agent（替代传统的 FADEC 电子控制器），在**全飞行包线**内实现对航空发动机的精准控制。任务涵盖了从**地面冷态起动**、**慢车维持**到**高空巡航**的全过程，要求在满足严苛的安全约束（温度、压力、转速限制）前提下，实现对双转子转速的快速、无静差追踪。
+
+---
+
+## 🌟 核心特性 (Key Features)
+
+* **高保真物理模型**：底层基于 C++ 编译的 DLL 热力学模型，能够真实反映发动机在不同工况下的非线性、强耦合特性。
+* **Gymnasium 标准接口**：完全兼容 OpenAI/Farama Gymnasium API，可直接接入 PPO, SAC, TD3 等主流强化学习算法。
+* **多变量解耦控制**：涉及燃油流量 () 与尾喷管面积 () 的协同控制 (2-DOF Control)。
+* **全流程仿真**：支持从静止状态 () 开始的起动过程模拟，包含起动机介入与点火逻辑。
+* **官方 PID 基准**：内置增量式 PID 控制器基准代码，展示了无扰切换与解耦控制策略。
+
+---
+
+## 🛠️ 安装说明 (Installation)
+
+1. **环境依赖**
+建议使用 Python 3.8 或更高版本。
+2. **安装步骤**
+在项目根目录下运行以下命令进行安装：
+```bash
+cd AeroEngineChallenge
+pip install -e .
+
+```
+
+
+3. **验证安装**
+运行随机测试脚本，确保环境无报错：
+```bash
+python test_random.py
+
+```
+
+
+
+---
+
+## 🎮 环境说明 (Environment Specs)
+
+### 1. 状态空间 (Observation Space)
+
+维度：`Box(8,)`，包含物理状态、控制目标及误差。
+
+| 索引 | 名称 | 描述 | 单位/备注 |
+| --- | --- | --- | --- |
+| 0 | `NH` | 高压转子转速 | 归一化 (0~1.0) |
+| 1 | `NL` | 低压转子转速 | 归一化 (0~1.0) |
+| 2 | `T5` | 涡轮后温度 | K (开尔文) |
+| 3 | `P3` | 压气机出口压力 | kPa |
+| 4 | `Target_NH` | 高压转速目标 | 由 PLA 查表得到 |
+| 5 | `Target_NL` | 低压转速目标 | 由 PLA 查表得到 |
+| 6 | `Error_NH` | `Target_NH - NH` | 误差 |
+| 7 | `Error_NL` | `Target_NL - NL` | 误差 |
+
+### 2. 动作空间 (Action Space)
+
+维度：`Box(5,)`，范围 `[-1.0, 1.0]`。Agent 输出后会被映射到物理范围。
+
+| 索引 | 名称 | 物理范围 | 说明 |
+| --- | --- | --- | --- |
+| 0 | `FanVane` | -20° ~ 20° | 风扇导叶 (辅助) |
+| 1 | `CompVane` | -20° ~ 20° | 压气机导叶 (辅助) |
+| 2 | `AddPower` | 0 ~ 100 kW | **起动电机功率** (仅起动阶段使用) |
+| 3 | `Wf` | 50 ~ 5000 kg/h | **燃油流量** (主控变量) |
+| 4 | `A8` | 0.2 ~ 0.6  | **尾喷管面积** (主控变量) |
+
+### 3. 任务输入：PLA (Power Lever Angle)
+
+环境不自动生成任务曲线，需通过外部接口设置油门杆角度：
+
+```python
+env.set_pla(60.0) # 设置当前油门为 60度
+
+```
+
+* **0° ~ 15°**: 起动/慢车区
+* **15° ~ 110°**: 工作区 (推力增加)
+
+---
+
+## 🏆 评价指标 (Evaluation Metrics)
+
+比赛的最终得分由环境返回的 `Reward` 决定，包含以下几个维度：
+
+1. **跟踪精度 (Tracking Accuracy)**:
+* 核心指标。计算  和  与目标的均方误差。
+
+
+2. **起动性能 (Startup Performance)**:
+* 起动耗时越短越好。
+* 消耗的起动功率 (`AddPower`) 越少越好。
+
+
+3. **动态品质 (Dynamic Quality)**:
+* **超调量**: 超过目标值会有额外惩罚。
+* **调节时间**: 快速进入 2% 误差带内。
+
+
+4. **动作平滑性 (Smoothness)**:
+* 惩罚控制量（特别是燃油和喷管）的剧烈高频抖动。
+
+
+5. **安全约束 (Safety Constraints)**:
+* **硬约束 (Terminated)**: 触发即任务失败 (Reward -1000)。
+*  (超温)
+*  或  (超转)
+
+
+* **软约束 (Penalty)**: 超过控制计划限制但未达硬限，持续扣分。
+
+
+
+---
+
+## 🚀 快速开始 (Quick Start)
+
+### 1. 运行 PID 基准
+
+我们提供了一个基于**增量式 PID** 和 **解耦控制策略** 的强力 Baseline。
+
+* **策略**: 燃油控制高压转子 ()，喷管控制低压转子 ()。
+* **运行**:
+```bash
+python test_pid_correct_pairs.py
+
+```
+
+
+*运行后将生成详细的仿真曲线图，展示起动及加速全过程。*
+
+### 2. 训练强化学习 Agent (示例)
+
+```python
+import gymnasium as gym
+from engine_env.envs.engine_env import AeroEngineGymEnv
+
+# 1. 初始化环境
+env = AeroEngineGymEnv()
+obs, info = env.reset(options={'pla': 0.0})
+
+# 2. 模拟训练循环
+for step in range(1000):
+    # 设定任务：前200步起动(15度)，之后巡航(60度)
+    pla_cmd = 15.0 if step < 200 else 60.0
+    env.set_pla(pla_cmd)
+    
+    # 随机动作 (替换为你的 RL Policy)
+    action = env.action_space.sample()
+    
+    # 环境交互
+    obs, reward, terminated, truncated, info = env.step(action)
+    
+    if terminated:
+        print("Crash! Resetting env...")
+        obs, info = env.reset()
+
+env.close()
+
+```
+
+---
+
+## 📂 项目结构
+
+```text
+AeroEngineChallenge/
+├── README.md                 # 项目说明书
+├── setup.py                  # 安装脚本
+├── test_pid_correct_pairs.py # 官方 PID 基准测试 (推荐)
+├── test_random.py            # 随机动作测试
+└── engine_env/               # 核心包
+    ├── __init__.py
+    ├── core_model.py         # DLL 调用接口
+    ├── libEngine.dll         # 发动机物理模型库
+    ├── schedule.py           # 控制计划 (PLA插值)
+    └── envs/
+        ├── __init__.py
+        └── engine_env.py     # Gym 环境主程序
+
+```
+
+---
+
+## 💡 参赛 Tips
+
+1. **物理直觉**: 喷管面积 () 对低压转子 () 影响直接，且呈现负相关特性（关小喷管  增加背压  转速上升）。不要忽视物理规律。
+2. **起动难点**: 在  的起动阶段，必须配合使用 `AddPower` 和合适的燃油供给，防止熄火或超温悬挂。
+3. **奖励设计**: 官方 Reward 函数较为严格，训练初期建议使用 `RewardWrapper` 进行适当的 Reward Shaping (如放宽误差容忍度) 以加速收敛。
+
+---
+
+**祝各位选手挑战成功，飞出完美包线！** ✈️
\ No newline at end of file