pcb-afm-simulation-system/torqrippswap-master/torqrippswap

使用任意 AI 编程工具维护 Motor-CAD 扫描项目

本文面向使用 Claude Code、Codex CLI、Cursor、GitHub Copilot、Kiro、Cline、Continue 或其它 AI 编程工具的开发者。目标是让新的 AI 助手在不了解历史对话的情况下，也能安全维护、构建和运行 本项目。

1. 项目用途

本项目使用 Ansys Motor-CAD 的 Python 自动化接口进行参数扫描，并提供 Windows GUI/EXE：

• 设置模型文件；
• 设置参数范围和步长；
• 启动独立、前台可见的 Motor-CAD 实例；
• 实时显示进度和仿真结果；
• 保存带详细时间戳的汇总 CSV、原始结果和程序日志；
• 在每个扫描点重新加载基线模型，避免参数累积污染。

2. AI 开始工作前必须阅读

让 AI 按顺序阅读：

1. MOTORCAD_SCAN_KNOWLEDGE_BASE.md
2. README_Central_Mag_Arc扫描.md
3. motorcad_scan_gui.py
4. scan_central_mag_arc.py
5. 与任务对应的参数配置 JSON
6. E:\aitestlocal\claude\motorcadopt\CLAUDE.md
7. E:\aitestlocal\claude\motorcadopt\TORQUE_RIPPLE_ANALYSIS.md

其中 MOTORCAD_SCAN_KNOWLEDGE_BASE.md 是本项目的主要知识入口，包含参数映射、求解设置、 运行约束、结果指标和已知 Motor-CAD 陷阱。

3. 可直接复制给 AI 的首次提示词

请先完整阅读 MOTORCAD_SCAN_KNOWLEDGE_BASE.md 和 README_AI_TOOLS.md，再检查当前 Git 状态。
这是 Windows 原生 Motor-CAD 自动化项目。所有 .py 和 .ps1 源码必须只含 ASCII 字符。
任何实际 Motor-CAD 求解启动前，必须先有 Git 提交，并确保所有已跟踪文件无未提交修改。
Motor-CAD 必须使用独立、前台可见的实例，不能抢占其它程序正在使用的实例。
不要猜 Motor-CAD 变量名；先从 .mot、已有参数表或探测结果确认，写入后必须回读校验。
每个扫描点开始前重新加载基线模型，每点完成后立即保存 CSV 和日志。
先说明你检查到的事实和计划，再进行修改。

4. 环境要求

4.1 操作系统

• Windows 10 或 Windows 11；
• 已安装与模型兼容的 Ansys Motor-CAD；
• 使用 Windows 原生 Python，不能使用 WSL Python。

4.2 Python 依赖

python -m pip install ansys-motorcad-core pyinstaller

Tkinter 通常随 Windows Python 安装。验证：

python -c "import tkinter; import ansys.motorcad.core; print('OK')"

4.3 Git

本机可能出现仓库所有权保护错误。不要修改全局 Git 配置，使用每条命令的局部配置：

git -c safe.directory=E:/aitestlocal/codex/tr status

5. 硬性工程约束

5.1 脚本必须是纯 ASCII

所有 .py 和 .ps1 文件只能包含 ASCII 字符。中文说明写在 Markdown 文件中。

检查命令：

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

如果命令输出任何行，先修正，再构建或运行。

5.2 运行前必须提交 Git

实际启动 Motor-CAD 求解前必须满足：

git -c safe.directory=E:/aitestlocal/codex/tr rev-parse --verify HEAD
git -c safe.directory=E:/aitestlocal/codex/tr status --porcelain --untracked-files=no

第二条命令必须没有输出。GUI 内置 Git preflight，不满足时应拒绝启动扫描。

5.3 不影响其它 Motor-CAD 实例

如果其它程序正在使用 Motor-CAD，不要使用模糊的“连接已有实例”方式。扫描程序应创建独立实例：

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

5.4 参数必须验证

不能只调用 set_variable。必须回读：

mc.set_variable(variable, value)
applied = mc.get_variable(variable)

回读不一致时将该点标记为 FAILED，保存错误并继续下一点。

6. 当前关键参数

用户界面名称	Motor-CAD 变量	说明
Central Mag Arc [ED]	MagnetCentralArc_HalbachRing	Halbach 中央磁块弧角
Magnet Arc [ED]	Magnet_Arc_[ED]	整体磁铁极弧
Slot Opening	Slot_Opening	槽口宽度
Copper Width	Copper_Width	PCB 铜线宽度

Central Mag Arc [ED] 和 Magnet Arc [ED] 不是同一个参数，禁止混用。

7. 主要程序和配置

文件	用途
motorcad_scan_gui.py	GUI 主程序
scan_central_mag_arc.py	单参数扫描、结果解析和分析基础代码
scan_parameters.json	二参数扫描配置
scan_parameters_magnet_arc.json	Magnet Arc 单参数配置
build_gui_exe.ps1	PyInstaller 通用构建脚本
package_magnet_arc_v2.ps1	Magnet Arc V2 单参数包生成脚本
MOTORCAD_SCAN_KNOWLEDGE_BASE.md	项目知识库

8. 构建 EXE

构建前先提交所有已跟踪修改：

git -c safe.directory=E:/aitestlocal/codex/tr add -- <files>
git -c safe.directory=E:/aitestlocal/codex/tr commit -m "Describe the change"

构建通用 GUI：

powershell.exe -NoLogo -ExecutionPolicy Bypass -File .\build_gui_exe.ps1 -AppName MotorCADParameterScanV3

生成 Magnet Arc 单参数 V2 包：

powershell.exe -NoLogo -ExecutionPolicy Bypass -File .\package_magnet_arc_v2.ps1

输出位于：

dist/<AppName>/<AppName>.exe

不要覆盖仍在运行的旧版 EXE 目录。需要修改布局或逻辑时使用新的应用名，例如 V4。

9. 运行方法

1. 启动对应 EXE；
2. Browse 选择 .mot 模型；
3. 检查扫描参数、起点、终点和步长；
4. 检查 Torque points 和 Airgap mesh；
5. 二参数扫描时确认两个水平数量的乘积；
6. 点击 Start；
7. 确认弹窗中的总仿真数和预计耗时；
8. 观察前台 Motor-CAD 和 GUI 进度；
9. 需要停止时使用 Stop after current point，不要强制结束当前求解。

10. 输出文件

每次运行创建：

runs/YYYYMMDD_HHMMSS_mmm_<scan_name>/

主要文件：

• run_manifest_<timestamp>.json：完整运行配置和 Git 提交；
• scan_results_<timestamp>.csv：汇总结果；
• program_log_<timestamp>.log：详细时间戳日志；
• raw/result_*.csv：每个扫描点的原始 Motor-CAD 导出结果。

分析问题时，AI 应先读取 manifest 和 log，再读取汇总 CSV，最后只打开相关的 raw 文件。

11. 结果指标

程序当前关注：

• Torque Ripple，百分比和 Nm；
• Average torque (virtual work)；
• System Efficiency；
• Back EMF 及 THD；
• Total Losses；
• DC copper loss；
• Magnet loss；
• Stator iron loss；
• Input、Output 和 Electromagnetic Power；
• Shaft speed 和 No-load speed。

Motor-CAD 导出文件使用分号分隔，同一指标可能在多个段落重复或带状态后缀。不要用普通逗号 CSV 解析器直接读取原始结果。

12. 修改或增加扫描参数

AI 不得凭记忆猜变量名。推荐流程：

1. 在 .mot 文件中搜索 GUI 名称附近的候选变量；
2. 查询 motorcadopt/results/mot_params_relevant.csv；
3. 用单点脚本写入并回读；
4. 必要时保存几何截图，确认参数确实改变模型；
5. 将已验证映射加入配置和知识库；
6. 添加范围检查；
7. 用 1–2 点 dry run 或真实单点验证；
8. 提交 Git 后才允许完整扫描。

13. 给 AI 的具体任务模板

增加单参数扫描

请在不影响现有 EXE 的前提下，增加 <GUI 参数名> 单参数扫描。
先从 .mot 和已验证参数表确认 Motor-CAD 自动化变量名，不要猜。
沿用 V2 三行布局：模型；参数与 Start/Stop/Step；Torque points/Airgap mesh。
所有 .py/.ps1 只能包含 ASCII。写入后回读校验，每点重新加载基线，每点立即保存结果。
修改完成后运行静态检查，提交 Git，再用新的应用名构建 EXE。不要启动完整仿真。

增加二参数扫描

请将参数 A 和参数 B 做笛卡尔积扫描，总数量必须显示为 NA x NB。
启动前显示组合总数和预计时长并要求确认。
每个点重新加载基线，按依赖顺序写参数并逐个回读。
结果 CSV 必须同时记录 A、B、所有联动值、求解设置和 Git 提交。
保留旧版 EXE，构建新的版本目录。

分析扫描结果

请先读取最新 runs 目录中的 manifest、log 和 scan_results CSV。
检查失败点、参数写入、Torque points、airgap mesh 和 Git 提交。
按 Torque Ripple 排序，同时施加 Tavg、效率、损耗和转速约束。
快速扫描只用于趋势判断，给出需要用 180 点和收敛网格复算的候选列表。

14. 提交前检查清单

• 阅读知识库；
• 确认真实 Motor-CAD 参数名；
• 不影响其它 Motor-CAD 实例；
• .py、.ps1 纯 ASCII；
• Python 编译检查通过；
• JSON 能正常解析；
• Git diff 无空白错误；
• 已跟踪修改已提交；
• EXE 使用新目录构建；
• GUI 启动测试不自动开始求解；
• 完整扫描前先做单点验证。