跳转至

项目、晶格与修订

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，也不要用压缩软件直接改包内文件。

每次保存都会把当前规范项目快照按 SHA-256 放入本机内容寻址对象库，并在 .vmaproj 中只写入轻量修订索引。计算完成后，索引记录精确计算输入摘要、上游产物和输出对象。相同字节只保存一次；修改 lattice 后旧结果成为 STALE，但其旧修订和证据不会被删除。

普通 Save 不把大数组复制进工作文件。需要迁移或归档时，使用 File → Pack Project with Indexed Results… 另存一个自包含 .vmaproj。便携包没有固定的 256 MiB 格式上限，但仍受本机内存、Qt 字节数组、文件系统和可用磁盘空间限制。

打开便携包时，其中的对象会恢复到本机对象库。之后执行普通 Save，会把项目写回轻量工作形态；需要再次迁移时重新使用 Pack 生成独立的自包含副本。

建立晶格

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

  1. 选择插入位置；未选择时按当前规则加入根序列。
  2. 点击 Add Element。
  3. 选择类型、Occurrence name、Family name，并在同一窗口填写该类型的全部初始 SI 参数； 适用时包括 k1、k2、弯转角、踢角、RF 数值或孔径尺寸。
  4. 后续选择实例时，Properties 会同时列出它的全部参数。直接修改需要变化的单元格， 然后把所有修改作为一个修订应用。

可添加的类型包括 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 数据；序列表与悬停提示还会显示每个实例的物理参数。 缩放只改变显示，不改数值。Lattice Geometry 根据每个元件的 length_m 和弯铁的 angle_rad 积分二维参考轨迹：非弯元件为直线，有限长弯铁为恒曲率圆弧；视图会显示起终 方向和闭合间隙。可用滚轮或 − / + 放大缩小，按住鼠标左键、中键或右键拖动平移，短按 左键选择元件，用 适应 恢复完整轨迹。 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 调整解释为已匹配光学。