# 知识库 — PCB轴向磁通电机自动化仿真系统

> 本文件是项目的核心知识沉淀，供人和任何 AI 工具阅读使用。
> 全部结论基于参考案例 axial_mag_pull 和 torqrippswap 的实测验证。
> 入口文件：仓库根 AGENTS.md（AI）/ README.md（人）。

## 1. 环境事实

| 项 | 值 |
|---|---|
| Motor-CAD | 2026R1 (v261) |
| 定位方式 | 环境变量 `MOTORCAD_ACTIVEX` → activex.bat → exe 路径；未注册时脚本内用 `set_motorcad_exe()` 回退 |
| Python | ≥ 3.10，`pip install ansys-motorcad-core pyside6 pandas` |
| 许可证 | FlexNet: `ANSYSLMD_LICENSE_FILE=1055@localhost`，lmgrd + ansyslmd 都必须在跑 |
| 非登录 shell 陷阱 | AI 工具的 shell 可能不继承机器级环境变量，需 inline 设置或脚本内回退 |
| 单次电磁求解耗时 | 约 90~150 秒（视机器性能和网格设置） |
| 窗口不可见陷阱 | pymotorcad 用 `/SCRIPTING` 模式启动，默认主窗口隐藏，必须 `set_visible(True)` |

### 1.1 环境验证命令

```powershell
# 验证 Motor-CAD 自动化注册
echo $env:MOTORCAD_ACTIVEX

# 验证许可证
echo $env:ANSYSLMD_LICENSE_FILE

# 验证 Python 包
python -c "import ansys.motorcad.core; print('pymotorcad OK')"
```

### 1.2 常见环境问题

| 现象 | 原因 | 解决 |
|---|---|---|
| Motor-CAD 启动后 30s 退出 | 许可证 ansyslmd 未运行 | 检查 ANSYS License Management Center (http://localhost:1084) |
| pymotorcad 报 NoSuchProcess | 同上，或环境变量未继承 | inline export 两个环境变量 |
| Motor-CAD 窗口看不见 | /SCRIPTING 模式默认隐藏 | `mc.set_visible(True)`；若仍找不到，点任务栏图标 → Win+↑ 最大化 |
| 改电流无效 | CurrentDefinition=1 时改了 PeakCurrent | 改 `RMSCurrent` |

---

## 2. Motor-CAD 自动化核心方法

### 2.1 连接与实例管理

```python
import ansys.motorcad.core as pymotorcad

# 创建独立实例（不要连接已有实例，可能控制错误窗口）
mc = pymotorcad.MotorCAD(open_new_instance=True, keep_instance_open=False)
mc.set_visible(True)  # 必须，否则窗口隐藏
mc.set_variable("MessageDisplayState", 2)
mc.display_screen("Scripting")
```

### 2.2 模型加载与保存

```python
# 加载基线模型
mc.load_from_file(r"models\MARS-12S10P_SSSR_D76-C150_V5.0-0819.mot")

# 另存工作副本（不污染原模型）
mc.save_to_file(r"output\working_<timestamp>.mot")
```

### 2.3 参数写入与回读校验

```python
import math

def write_and_verify(mc, variable, value):
    mc.set_variable(variable, value)
    applied = float(mc.get_variable(variable))
    if not math.isclose(applied, value, rel_tol=1e-8, abs_tol=1e-7):
        raise RuntimeError(
            f"Write verification failed for {variable}: "
            f"wrote {value}, read {applied}"
        )
```

**为什么必须回读**：Motor-CAD 对不适用的参数有时会静默接受，不回读就不知道参数是否真的生效了。

### 2.4 求解

```python
mc.do_magnetic_calculation()  # 电磁求解，约 90-150 秒
```

### 2.5 结果导出

```python
# 导出电磁结果（分号分隔的 CSV，不是普通逗号 CSV）
mc.export_results("EMagnetic", r"output\raw\result_<timestamp>.csv")
```

---

## 3. .mot 参数语义（AFM 模板，易错！）

| 参数 | 正确语义 | 常见误读 | MARS模型值 |
|---|---|---|---|
| `Magnet_Length` | 磁钢**轴向厚度** | 以为是长度 | 3 mm |
| `Magnet_Thickness` | 磁钢环**径向深度** = (D_out−D_in)/2 | 以为是厚度 | 13 mm |
| `Magnet_Arc_[ED]` | 极弧（电角度） | — | 121° |
| `Pole_Arc` | 某些转子类型不生效 | 以为是极弧 | 勿用 |
| `CurrentDefinition` | 1=RMS口径 → 改电流设 `RMSCurrent` | 改 PeakCurrent 无效且不报错 | 1 |
| `RMSCurrent` | RMS相电流（CurrentDefinition=1时的电流入口） | — | 21 A |
| `Magnet_Temperature` | 磁钢温度，**默认100°C热态** | 以为是常温20°C | 100 |
| `Airgap` | 气隙长度 | — | 1 mm |
| `Shaft_Speed` | 轴转速 | — | 5000 rpm |
| `TorquePointsPerCycle` | 每电周期转矩采样点数 | — | 30（模型默认） |
| `AirgapMeshPoints_mesh` | 气隙内部网格点 | 与 layers 成对设置 | 840 |
| `AirgapMeshPoints_layers` | 气隙表面网格点 | 与 mesh 成对设置 | 840 |

### 3.1 温度定律

F ∝ Br²，磁钢剩磁 Br 随温度变化。实测 100°C vs 20°C 的轴向力比值与 Br² 比值一致（<1% 偏差）。

### 3.2 电流口径

`CurrentDefinition=1` 表示 RMS 口径。此时：
- 改 `RMSCurrent` 生效
- 改 `PeakCurrent` **无效且不报错**（首跑踩坑）

---

## 4. 结果指标提取

### 4.1 核心指标（Phase 1 必选）

| 指标 key | 显示名称 | Motor-CAD 导出字段名 | 单位 |
|---|---|---|---|
| `tavg_nm` | 平均转矩 | `Average torque (virtual work)` | Nm |
| `ripple_pct` | 转矩脉动 | `Torque Ripple (VW) [%]` | % |
| `ripple_nm` | 转矩脉动绝对值 | `Torque Ripple (VW)` | Nm |
| `efficiency_pct` | 系统效率 | `System Efficiency` | % |
| `total_losses_w` | 总损耗 | `Total Losses (on load)` | W |
| `copper_loss_w` | 铜耗 | `Armature DC Copper Loss (on load)` | W |
| `iron_loss_w` | 定子铁耗 | `Stator iron Loss [total] (on load)` | W |
| `magnet_loss_w` | 磁钢损耗 | `Magnet Loss (on load)` | W |
| `back_emf_v` | 反电动势 | `Back EMF Line-Line Voltage (rms)` | V |
| `input_power_w` | 输入功率 | `Input Power` | W |
| `output_power_w` | 输出功率 | `Output Power` | W |
| `shaft_speed_rpm` | 轴转速 | `Shaft Speed` | rpm |

### 4.2 导出文件格式

Motor-CAD 的 `export_results` 输出是**分号分隔**的文本文件，不是普通逗号 CSV：
- 第一列是字段名，第二列是数值
- 按 section 分段（E-Magnetics、Drive、Losses、Materials、Miscellaneous）
- 同一指标可能在多个 section 重复，优先取 E-Magnetics
- 编码可能是 UTF-8、cp1252、gbk 或 latin-1，需逐个尝试

### 4.3 字段名匹配策略

1. 先精确匹配（按 section 优先级：E-Magnetics → Drive → Losses → Materials → Miscellaneous）
2. 再全 section 精确匹配
3. 最后前缀模糊匹配（避免短字段误匹配，长度 > 3 才匹配）

---

## 5. AFM 轴向力数据口（Phase 1 暂不使用，保留参考）

Motor-CAD 对 AFM 的轴向力**没有输出变量、没有 2D 结果图、帮助文档无记录**。唯一入口是 3D lumped 力图：

```python
mc.get_magnetic_3d_graph_point(graph_name, section, node, timestep)
# graph_name ∈ {Fr|Ft}_{Rotor|Stator}_{OL|OC}_Lumped
```

- **Fr（法向力）= 轴向力**（AFM 2.5D 展开模型沿用径向机命名）
- Ft = 切向力（可由 Σ(Ft×r) 交叉核对转矩）
- OL=负载, OC=空载 — 一次求解两者全出
- 求解前必须开开关：`ElectromagneticForcesCalc_Load=True`, `ElectromagneticForcesCalc_OC=True`
- 节点首尾 0°/360° 重复，求和须去重
- 净力 = 对全部去重节点求和 + 对全部径向切片求和

> Phase 1 不提取轴向力，后续需要时参考 `axial_mag_pull-master/axial_mag_pull/axial_force_final.py`。

---

## 6. 采样点与气隙网格（转矩脉动评估关键）

| 设置 | 用途 | 风险 |
|---|---|---|
| 30 点 / 840 网格 | 快速趋势筛选 | 9槽8极模型主要齿槽成分是18次电频谐波，30点低于可靠分辨要求，可能混叠 |
| 120 点 / 960 网格 | 中等可信度 | 120点搭配840网格会弹出不对齐警告，需用960 |
| 180 点 / 1680 网格 | 最终候选复算 | 速度慢但精度高 |

**原则**：
1. 不要随意组合采样点数和网格点数
2. 先做单点验证，确认无交互弹窗
3. 所有结果必须记录实际的 Torque points 和 airgap mesh
4. 快速扫描的最佳点必须用高精度设置复算
5. 快速扫描结果只用于趋势判断，不直接当作最终脉动真值

---

## 7. 新模型仿真工作流（SOP）

1. 新模型 `.mot` 放 `models/` 目录，`git add` + 运行前先 commit
2. 确认模型基本信息：拓扑、槽极数、气隙、磁钢厚度、电流口径
3. 确认工况：磁钢温度（热态100°C / 冷态20°C）、RMS电流、转速
4. 用 `scripts/run_single.py` 跑一次空载+负载，验证能提取到全部核心指标
5. 验证通过后，用 `scripts/run_scan.py` 做参数扫描
6. 结果记录：时间戳 + 简要说明 + git 提交
7. 关键数值转录进入库文档

---

## 8. 图名/变量名探测技术（遇到未知输出时用）

1. **报错文案筛查**（无需求解，秒级）：`get_magnetic_graph_point(名, 0)` — "Graph name does not exist" = 不存在；"No points exist" = 存在但未求解
2. **图 ID 枚举**：graph 参数可传 int，求解后逐 ID 读波形按量级辨认
3. **权威清单**：GUI 内 Help → Graph Viewer（全部图名）；Help → Automation Parameter Names / F2（全部变量名）
4. **exe 字符串挖掘**：MotorCAD.exe 的 UTF-16 字符串含图名后缀、GUI 文案
5. Motor-CAD 消息日志（`<模型名>\MessageLogs\*.txt`）记录每次 pymotorcad 调用，但重复错误行会被抑制

---

## 9. 理论参考资料

当方案生成、参数初值估算、物理约束规则等需要理论支撑时，查阅以下资料：

| 资料 | 路径 | 适用场景 |
|---|---|---|
| 《轴向磁通永磁无刷电机（原书第2版）》Jacek F. Gieras | `书籍与论文/轴向磁通永磁无刷电机(原书第2版), Jacek F. Gieras.pdf.pdf` | 拓扑分类、电磁设计基础、热设计、机械设计 — **主要参考** |
| 《轴向磁场无刷同步电机理论与设计》邓秋玲 | `书籍与论文/轴向磁场无刷同步电机理论与设计-邓秋玲.pdf` | 国内工程实践、公式推导 — **补充参考** |
| axial_mag_pull 解析报告 | `axial_mag_pull-master/axial_mag_pull/轴向磁通电机轴向磁拉力计算与轴承选型校核报告V3.0-20260826.pdf` | 轴向磁拉力解析计算方法、轴承选型 |

**理论知识缺乏时的处理原则**：
- 优先在上述书籍中查找对应章节
- 找不到时，在 `docs/CONVERSATION_LOG.md` 中记录"理论待补充"标记
- 不基于猜测制定物理约束或参数初值

---

## 10. 项目纪律（硬性）

1. 每次运行仿真前 git commit
2. 结果与报告带时间戳+简要说明并 git 提交；报告版本化不覆盖
3. Motor-CAD 前台运行，跑完保持打开供人工检查
4. 生成物（output/、*.log、build/、dist/）不入库
5. 原始 .mot 只读，一切修改在时间戳副本上进行
6. 参数写入后必须回读校验，不一致标记 FAILED
7. 每个扫描点重新加载基线模型，防止参数污染
8. 对话与决策带时间戳记入 `docs/CONVERSATION_LOG.md`
9. 所有 .py / .ps1 源码纯 ASCII，中文用 Unicode 转义或放 Markdown
10. 仿真在子线程运行，不阻塞 GUI 主线程