VM Accelerator Studio 使用指南¶
VM Accelerator Studio 是一套面向电子储存环的原生低代码设计工作站。你在 Studio 中建立和修改晶格、填写经审阅的物理输入、发起计算并检查证据；独立部署在 Linux 上的 vm-accelerator Engine 负责权威数值计算。两者分开，使设计文件、计算环境和结果来源都能被明确追踪。
系统由什么组成¶
flowchart LR
A[Studio 本机工作站<br/>项目、低代码编辑、任务与结果] -->|明确发起的 SSH 计算| B[vm-accelerator Engine<br/>验证项目并执行物理计算]
B -->|带身份与校验信息的结果| A
A --> C[本机已验证结果库]
A --> D[.vmaproj / 规范 JSON]| 部分 | 主要职责 | 不负责什么 |
|---|---|---|
| Studio | 项目与晶格编辑、工作流编排、结果可视化、证据复验、任务恢复 | 不在界面中另写一套物理算法，不猜测缺失输入 |
| Engine | 项目验证、光学、跟踪、平衡、接受度、Touschek、非线性和轨道修正计算 | 不替代工程设计评审或真实机器测量 |
.vmaproj |
保存权威项目、可继续编辑的草稿、Cell 布局和部分研究元数据 | 不是把普通 JSON 改了扩展名 |
| 本机结果库 | 保存并在打开时重新验证不可变计算证据 | 不自动把旧修订结果升级成当前结果 |
设计参考与特色¶
Studio 的使用方式参考了桌面 CAD/CAE 工作站和 Office Ribbon：常用命令按 Project、Design、Calculate、Results、History、View 分组，同时保持原生 Qt Widgets 界面，不依赖浏览器。物理计算以 Xsuite/Xtrack 为主要后端；部分关键路径使用 PyAT 作独立数值对照，Touschek 修正路线还保留了公式来源与交叉代码审计。规范 JSON、项目/物理修订标识和 SHA-256 贯穿项目、任务与结果，但日常使用不需要手工处理这些字段。
系统的几个鲜明特点是：
- 低代码但不低可信度：可以用表格、属性面板、Family 和 Cell 编辑晶格，同时所有计算仍必须通过 Engine 验证。
- 缺失就是缺失：新项目允许不完整并可保存，Studio 不会偷偷补一个 RF、电流、发射度或接受度。
- 结果绑定到精确修订：修改物理内容后，旧结果继续可看，但会显示为
STALE，不会冒充当前结果。 - 本地设计、按需远程计算：Studio 只在显式探测、计算、任务操作或启用的启动恢复中联系目标。
- 耐久任务可恢复：跟踪、Touschek、非线性和轨道修正任务可脱离界面运行，随后重连、取消或获取产物。
- 中英文即时切换：界面语言不会改写项目 JSON、单位、公式、标识符或证据字节。
结果应该怎样理解¶
当前所有可运行路线的最高声明都是 SCREENING（筛选）。这意味着结果适合设计探索、回归比较和发现明显问题，但不能单独证明：
- 机器可建造或可运行；
- 动力学孔径、局部动量接受度或寿命已达到机器级资格；
- 误差、校正、强耦合、集体效应、RF/辐射或工程容差已经全部纳入；
- 仿真与测量机器一致。
阅读结果时，优先看页面上的 Qualification、Validity、警告、适用边界和项目修订，而不是只看一个标量。
功能地图¶
| 想完成的任务 | 对应章节 |
|---|---|
| 安装、启动、语言和主题 | 安装与十分钟上手、界面与设置 |
| 新建/导入/保存/导出项目 | 项目、晶格与修订 |
| 元件、Family、Cell、环形图和修订审阅 | 项目、晶格与修订 |
| RF、辐射和平衡输入 | 物理输入 |
| SSH target、凭据、恢复和取消 | 连接 Engine |
| Twiss 光学与通用 tracking | 线性光学与持久跟踪 |
| 辐射切片、平衡、匹配分布和 LMA | 平衡计算链 |
| 流程编排、corrected/historical Touschek | Screening Study 与 Touschek |
| DA、FMA、loss 与 convergence | 非线性动力学 |
| 误差、BPM、Corrector、SVD 与 tolerance | 误差与轨道修正 |
| 本地结果、比较、证据和导出 | 结果、证据与导出 |
| Xsuite 与历史 YAML | 导入与历史迁移 |
| 版本矩阵、构建、CLI 和排错 | Engine 能力、命令行、故障排查 |
推荐阅读路径¶
第一次使用：先完成十分钟上手，再阅读项目、晶格与修订和连接 Engine。
要完成一条完整的 v0.2 计算链：阅读物理输入、平衡计算链和Screening Study。
Engine 管理员：直接查看Engine 能力与版本边界及命令行与构建参考。