知识库 — 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 环境验证命令

# 验证 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 连接与实例管理

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 模型加载与保存

# 加载基线模型
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 参数写入与回读校验

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 求解

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

2.5 结果导出

# 导出电磁结果（分号分隔的 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 字段名匹配策略

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

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

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

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 网格	最终候选复算	速度慢但精度高

原则：

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

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

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

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

报错文案筛查（无需求解，秒级）：get_magnetic_graph_point(名, 0) — "Graph name does not exist" = 不存在；"No points exist" = 存在但未求解
图 ID 枚举：graph 参数可传 int，求解后逐 ID 读波形按量级辨认
权威清单：GUI 内 Help → Graph Viewer（全部图名）；Help → Automation Parameter Names / F2（全部变量名）
exe 字符串挖掘：MotorCAD.exe 的 UTF-16 字符串含图名后缀、GUI 文案
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. 项目纪律（硬性）

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

KNOWLEDGE_BASE.md 11 KB Cronologia Originale