# Motor-CAD 参数扫描与寻优知识库

版本：2026-08-26  
适用目录：`E:\aitestlocal\codex\tr`  
参考项目：`E:\aitestlocal\claude\motorcadopt`

## 1. 目标与适用范围

本知识库用于指导 Motor-CAD 模型的自动参数扫描、结果采集、GUI 工具维护和后续寻优。
当前主要模型为：

`MARS-9S8P_SSSR_Halbach_PCB-V1.0.mot`

已经实现或验证的扫描类型包括：

1. Halbach 中央磁块弧角单参数扫描；
2. 整体磁铁极弧单参数扫描；
3. 中央磁块弧角与槽口宽度的二维组合扫描；
4. 槽口变化时 PCB 铜线宽度的公式联动。

## 2. 已确认的 Motor-CAD 参数映射

| GUI 名称 | Motor-CAD 自动化变量 | 单位 | 基线值 | 说明 |
|---|---|---:|---:|---|
| Central Mag Arc [ED] | `MagnetCentralArc_HalbachRing` | EDeg | 120 | Halbach 中央磁块弧角，不等于整体极弧 |
| Magnet Arc [ED] | `Magnet_Arc_[ED]` | EDeg | 180 | 整体磁铁极弧 |
| Slot Opening | `Slot_Opening` | mm | 8 | 基线等于槽宽，属于完全开口槽 |
| Slot Width | `Slot_Width` | mm | 8 | Parallel Slot 模型的槽宽 |
| PCB 铜线宽 | `Copper_Width` | mm | 3.39 | 已与槽口联动公式核对 |
| 每电周期转矩点数 | `TorquePointsPerCycle` | points/cycle | 30 | 原模型值，速度快但存在混叠风险 |
| 气隙内部网格点 | `AirgapMeshPoints_mesh` | points | 840 | 与 surface 参数通常成对设置 |
| 气隙表面网格点 | `AirgapMeshPoints_layers` | points | 840 | 与 mesh 参数通常成对设置 |

关键区分：

- 扫描 `Central Mag Arc [ED]` 时必须写 `MagnetCentralArc_HalbachRing`。
- 扫描 `Magnet Arc [ED]` 时必须写 `Magnet_Arc_[ED]`。
- 两者代表不同的几何含义，不能混用。

## 3. 自动化连接与运行约束

### 3.1 Windows 原生环境

Motor-CAD 通过 Windows RPC/COM 风格接口驱动，必须使用 Windows 原生 Python。
WSL 或 Linux 环境不能连接本机 Motor-CAD 实例。

主要依赖：

```text
ansys-motorcad-core
tkinter
PyInstaller
```

### 3.2 前台可见

自动求解使用独立 Motor-CAD 实例，并调用：

```python
mc = pymotorcad.MotorCAD(open_new_instance=True, keep_instance_open=False)
mc.set_visible(True)
```

这样可以避免连接到正在被其它程序控制的 Motor-CAD 实例，同时保证用户能看到新实例。

### 3.3 多实例风险

`open_new_instance=False` 会尝试连接现有实例。机器上同时存在多个 Motor-CAD 时，可能连接到错误模型。
除非已通过进程和 RPC 端口明确识别目标实例，否则不要使用自动连接现有实例的方式运行批处理。

### 3.4 每点重新加载基线

每个扫描组合开始前必须执行：

```python
mc.load_from_file(model_path)
```

然后再写本点参数。这样可以避免上一点参数、求解开关或派生状态污染下一点。

扫描结束时也应重新加载基线模型，使 Motor-CAD 不停留在最后一个扫描值。

## 4. 参数写入规则

### 4.1 只修改明确授权的设计变量

单参数扫描只写该参数；求解采样点和网格属于数值设置，不是设计变量，应在结果清单中明确记录。

### 4.2 写入后必须回读

Motor-CAD 对不适用的参数有时会静默接受，因此每次写入都必须用 `get_variable` 回读并比较：

```python
mc.set_variable(variable, value)
applied = float(mc.get_variable(variable))
```

若不一致，当前点应标为 `FAILED`，不能继续把结果当作有效数据。

### 4.3 槽口与 PCB 铜线宽联动

槽口改变时，铜线宽按以下公式计算：

```text
Copper_Width = (Slot_Opening - clearance) / 2 / conductor_count
```

当前默认：

- `clearance = 0.2 mm`
- `conductor_count = 1`
- `/2` 表示槽两侧分配

默认槽口扫描 5.4–7.4 mm、步长 0.2 mm 时：

| Slot Opening (mm) | Copper Width (mm) |
|---:|---:|
| 5.4 | 2.6 |
| 5.6 | 2.7 |
| 5.8 | 2.8 |
| 6.0 | 2.9 |
| 6.2 | 3.0 |
| 6.4 | 3.1 |
| 6.6 | 3.2 |
| 6.8 | 3.3 |
| 7.0 | 3.4 |
| 7.2 | 3.5 |
| 7.4 | 3.6 |

二维扫描中推荐写入顺序：

1. `Slot_Opening`
2. `Copper_Width`
3. 磁铁弧角参数
4. 逐项回读验证
5. 执行磁场计算

## 5. 扫描矩阵

### 5.1 单参数扫描

端点均包含在扫描序列中。如果终点无法由整数个步长严格到达，程序会额外加入终点。

### 5.2 二参数扫描

总仿真数为两个参数水平数的乘积：

```text
N_total = N_parameter_1 x N_parameter_2
```

示例：

- Central Mag Arc：90–110 EDeg，步长 1，共 21 个水平；
- Slot Opening：5.4–7.4 mm，步长 0.2，共 11 个水平；
- 总仿真数：`21 x 11 = 231`。

按 30 点/840 网格的实际速度约 2.5–4.2 分钟/点估算，231 点可能需要约 10–16 小时。
GUI 必须在启动前显示组合总数和粗略时长，并要求再次确认。

## 6. 采样点与气隙网格

### 6.1 原模型快速设置

```text
TorquePointsPerCycle = 30
Airgap mesh/layers = 840
```

优点：速度快，适合初筛。  
风险：本机 9 槽 8 极模型的主要齿槽成分是 18 次电频谐波，30 点/电周期低于可靠分辨要求，
可能发生混叠，因此不能把 30 点扫描的绝对脉动值直接当作最终结论。

### 6.2 推荐设置

- 快速趋势扫描：30 点/840 网格；
- 中等可信度扫描：120 点，并采用与时间步对齐的气隙网格；
- 最终候选复算：180 点和更细、已验证收敛的网格。

已知坑：120 点搭配原始 840 网格时，Motor-CAD 会弹出网格与时间步不对齐警告，导致无人值守 RPC
批处理失败。Motor-CAD 曾建议改为 960；参考项目的高精度研究还使用过 1680。

原则：

1. 不要随意组合采样点数和网格点数；
2. 先做单点验证，确认无交互弹窗；
3. 所有结果必须记录实际的 Torque points 和 airgap mesh；
4. 快速扫描的最佳点必须用高精度设置复算。

## 7. 结果指标

GUI 与 CSV 应尽可能采集以下常用指标：

| 类别 | Motor-CAD 结果名称 |
|---|---|
| 转矩脉动 | `Torque Ripple (VW) [%]`、`Torque Ripple (VW)` |
| 平均转矩 | `Average torque (virtual work)` |
| 系统效率 | `System Efficiency` |
| 反电动势 | `Back EMF Line-Line Voltage (rms)` |
| 反电动势失真 | `Harmonic Distortion Back EMF Line-Line Voltage` |
| 总损耗 | `Total Losses (on load)` |
| 铜耗 | `Armature DC Copper Loss (on load)` |
| 磁钢损耗 | `Magnet Loss (on load)` |
| 定子铁耗 | `Stator iron Loss [total] (on load)` |
| 输入功率 | `Input Power` |
| 输出功率 | `Output Power`，导出名称可能带状态后缀 |
| 电磁功率 | `Electromagnetic Power`，导出名称可能带状态后缀 |
| 轴转速 | `Shaft Speed` |
| 空载转速 | `No load speed` |

结果导出文件使用分号分隔，不是普通逗号 CSV。相同指标可能在多个段落重复，优先取
`E-Magnetics`，再按 `Drive`、`Losses`、`Materials`、`Miscellaneous` 搜索。

## 8. 时间戳与可恢复性

每次 GUI 运行应创建独立目录：

```text
runs/YYYYMMDD_HHMMSS_mmm_<scan_name>/
```

目录内至少包含：

- `run_manifest_<timestamp>.json`：模型、参数范围、完整组合、数值设置和 Git 提交；
- `scan_results_<timestamp>.csv`：逐点汇总结果；
- `program_log_<timestamp>.log`：毫秒级时间戳日志；
- `raw/result_<index>_<values>_<timestamp>.csv`：每点 Motor-CAD 原始导出。

每个点完成后立即写 CSV 并刷新文件，不能等整批完成后一次性保存。失败点记录错误并继续下一点。

## 9. GUI 与 EXE 版本

| 版本/程序 | 功能 |
|---|---|
| `MotorCADParameterScanV2` | 单参数扫描，稳定的三行设置布局 |
| `MotorCADParameterScanV3` | Central Mag Arc × Slot Opening 二维扫描，带 Copper Width 联动 |
| `MotorCADMagnetArcScan` | V2 单参数布局，扫描整体 `Magnet_Arc_[ED]` |

单参数 V2 布局要求：

1. 第一行：模型路径；
2. 第二行：参数、Start、Stop、Step；
3. 第三行：Torque points、Airgap mesh；
4. 每项必须拥有独立的标签和输入框，不得复用同一 Grid 列导致控件覆盖。

## 10. Git 与源码规则

### 10.1 源码字符集

所有 `.py` 和 `.ps1` 脚本必须只包含 ASCII 字符。中文说明放在 Markdown 文档中，不能写进脚本注释、
窗口标题、帮助文本或日志模板。

建议检查：

```powershell
rg -n "[^\x00-\x7F]" --glob '*.py' --glob '*.ps1' .
```

### 10.2 运行前必须提交

每次实际启动 Motor-CAD 求解前：

1. 必须存在 Git 提交；
2. 所有已跟踪文件必须无未提交修改；
3. 运行清单必须记录当前短提交号；
4. 未跟踪的模型结果目录不应自动加入提交或删除。

GUI 的 Git preflight 若失败，必须拒绝启动求解。

## 11. 常见故障与处理

| 现象 | 原因 | 处理 |
|---|---|---|
| 连接成功但控制了错误窗口 | 同时运行多个 Motor-CAD，自动连接命中错误实例 | 新建独立实例并设为可见 |
| RPC 在计算开始时报 Warning/Error | Motor-CAD 弹出交互警告 | 先做单点验证；修正网格/时间步组合 |
| 参数写成功但几何不变 | 参数不适用于当前机型，Motor-CAD 静默接受 | 回读只是最低要求；存疑参数还要截图或结果对照验证 |
| 扫描点之间结果异常累积 | 未重新加载基线 | 每点先 `load_from_file` |
| GUI 看不到 Step 输入框 | Grid 列发生标签与输入框覆盖 | 使用 V2 三行布局，每组控件放独立 Frame |
| 长时间任务中途丢失全部结果 | 批次结束才保存 | 每点立即追加 CSV、写日志并 flush |
| 30 点结果看似更优 | 18 次谐波混叠 | 只用于趋势筛选，高精度复算确认 |
| Git 报 dubious ownership | 仓库所有者与运行账户不同 | 每条命令使用 `git -c safe.directory=E:/aitestlocal/codex/tr ...` |

## 12. 推荐寻优流程

1. 确认模型、设计变量和真实自动化变量名；
2. 检查所有脚本为纯 ASCII；
3. 提交 Git，并确认已跟踪工作区干净；
4. 用 1–2 个点验证前台实例、参数回读、结果字段和无弹窗运行；
5. 使用 30 点/840 网格做粗筛；
6. 根据趋势缩小参数区间，而不是盲目扩大二维全网格；
7. 在候选区域用更小步长加密；
8. 用 180 点和收敛网格复算最佳候选；
9. 同时检查 Torque Ripple、Tavg、效率、损耗、反电动势和转速，不只看单一目标；
10. 保存参数、原始结果、汇总表、日志、Git 提交和简单分析。

## 13. 当前工程结论

- `Central Mag Arc [ED]` 与 `Magnet Arc [ED]` 是两个不同参数，工具和结果命名必须明确区分。
- 9 槽 8 极模型的脉动评估对采样点数和气隙网格非常敏感。
- 原模型 30 点设置适合快速筛选，不适合直接宣称最终脉动真值。
- 槽口从完全开口状态收窄是重要设计方向，但改变槽口时必须同步处理 PCB 铜线宽几何。
- 二维全网格很容易达到数百次仿真；应优先粗筛、缩小区域、再加密和高精度复算。
- 可靠的自动化不仅要“能跑”，还必须具备前台可见、参数回读、逐点落盘、时间戳、失败续跑和 Git 可追溯性。