跳转至

项目、晶格与修订

English · 上一章：界面与设置 · 下一章：物理输入

项目格式怎么选

格式 用途
.vmaproj Studio 原生工作文件；保存权威项目、可编辑草稿、Cell 布局、研究草稿和附加证据
studio-project/0.1 JSON 线性光学和通用 CPU 跟踪使用的规范交换项目
studio-project/0.2 JSON 平衡、匹配分布、LMA、Touschek、非线性和轨道修正使用的扩展项目

打开 JSON 是“导入”。按 Save 会要求创建 .vmaproj，不会覆盖源 JSON；Export Project JSON 才会明确导出当前规范交换文件。

.vmaproj 在打开时检查包结构和内容完整性。请不要把普通 JSON 改名为 .vmaproj，也不要用压缩软件直接改包内文件。

建立晶格

新项目从一个 START Marker 开始。在 Design → Lattice 中：

  1. 选择插入位置；未选择时按当前规则加入根序列。
  2. 点击 Add Element。
  3. 选择类型、Occurrence name、Family name 和物理长度。
  4. 在 Properties 中选参数并输入 SI 数值，点击 Apply to authoring draft。

可添加的类型包括 Marker/diagnostic、Drift、Quadrupole、Sextupole、Bend、RF cavity、Corrector、矩形和椭圆孔径。新建值是编写占位符，不是匹配后的设计。例如 Quadrupole 默认 k1=0 m⁻²，Bend 默认角度为 0，必须由你配置。

对已有 v0.2 项目，插入和复制被刻意限制：不能直接插入或复制 Bend/RF cavity，因为这会改变闭环或 RF 拓扑，需要尚未提供的专门事务。其他晶格修改会撤回旧的 supplied radiation slices，下一次平衡计算必须重新生成与新修订绑定的切片。

顺序、复制和删除

  • Up/Down：在根序列中移动选中实例。
  • Duplicate：产生新的稳定实例 ID，同时保留 Family 引用。
  • Delete：从根序列移除实例；可撤销。v0.2 会同时清理不再使用的 Family/孔径元数据。
  • Undo/Redo：作用于项目编辑；保存不会清空可见修订意义。

每次物理编辑都会形成新的项目内容和/或 physics revision。计算进行时，相关物理编辑会被阻止，避免结果与正在变化的输入交叉。

Family：一次修改同族元件

选择一个实例后点击 Edit Family。Studio 只在同族成员类型一致且共享相同参数时允许批量编辑。例如把 QF Family 的 k1 一次应用到全部成员。

Family 是设计数据关系，不意味着实际磁铁共用电源、校准曲线或误差。运行前仍需独立工程建模。

Cell：组织和复用连续结构

在序列表中用 Shift 或 Ctrl/Cmd 选择至少两个连续且未归组的实例，点击 Define Cell。随后可以：

  • Rename：只改 Studio 布局元数据，不改物理修订；
  • Ungroup：删除分组，不删除元件；
  • Duplicate Cell：复制连续块并创建新实例 ID；
  • Mirror-Copy Cell：只反转实例顺序。

Mirror 不会自动改变弯转角、多极场符号、Corrector kick、RF 相位、硬件极性或对准约定。v0.2 中含 Bend 或 RF cavity 的 Cell 不能复制。

线性和环形视图

线性视图中的水平位置和长度来自权威 SI 数据。缩放只改变显示，不改数值。环形视图按路径长度把序列投影成环，可导出 PDF、SVG 或 PNG；它是拓扑示意，不是 survey 后的隧道/磁铁几何。

修订审阅

v0.2 编辑后选择 Project → Review，比较当前状态与上一撤销点：

  • content SHA 和 physics revision；
  • 实例数、环周长、同步 RF、辐射模型和 Cell 数；
  • 新增、删除、重排和参数变化；
  • 项目元数据和 Cell 变化。

三类影响要区别对待：

  • PHYSICS REVISION CHANGED：旧计算不再属于当前物理修订；
  • PROJECT CONTENT CHANGED · PHYSICS IDENTITY UNCHANGED：仍需明确做证据协调，不能默认当作当前项目结果；
  • STUDIO LAYOUT ONLY：只有 Cell 布局变化，物理结果不失效。

一个可直接操作的 FODO 编辑例子

打开：

protocol/v0_3/fixtures/fodo-ring.studio-project.json
  1. 选一个 Quadrupole，记下 Family 和 k1。
  2. 用 Edit Family 将 k1 做一个小的、有记录的改动。
  3. 打开 Review Current Revision，确认 parameter change、content 和 physics revision 都发生变化。
  4. 观察旧结果在 Screening Results 中变成 STALE，而不是消失。
  5. 撤销修改，确认修订标识恢复。

这个例子只演示修订机制；不要把任意 k1 调整解释为已匹配光学。