跳转至

Xsuite 导入与历史实验迁移

English · 上一章：结果与证据 · 下一章：Engine 能力

Xsuite Line 结构导入

vm-accelerator-studio-import-xsuite 把 resolved Xsuite Line JSON 投影成 .vmaproj，同时打包：规范 v0.2 结构项目、导入证据和源文件精确字节。必须提供独立获得的 expected SHA-256；不匹配时不会产生输出。

./build/dev/vm-accelerator-studio-import-xsuite \
  --input resolved-line.json \
  --output imported-ring.vmaproj \
  --project-id imported-ring \
  --display-name "Imported ring structural projection" \
  --expected-sha256 <reviewed-source-sha256> \
  --project-json imported-ring.studio-project.json \
  --evidence-json imported-ring.import-evidence.json

可投影 Marker、Drift、FirstOrderTaylorMap（仅保长度，矩阵留在源证据）、Quadrupole、Sextupole、Bend、零 Multipole 和 inactive Cavity。非零 relative multipole、active RF、未知类型和坏矩阵会被拒绝。

这是结构浏览和受限编辑，不是 Xsuite 计算等价导入。特别是 FirstOrderTaylorMap 被几何等效为 drift，因此必须保持 calculationEquivalentToXsuiteSource=false。要重跑 Xsuite 光学/跟踪仍需原始源或未来无损表示。

Historical Experiment Migration

通过 File → Import → Open historical migration catalog… 打开受审阅的 historical-studio-migration-audit/0.2 catalog。工作区支持：

  • 按 tier、Studio status、feature、重复组和全文搜索筛选；
  • 在 unique contents（按 SHA 合并）和 all file instances 之间切换；
  • 将 catalog 中的 logical source 映射到本机目录；
  • 精确复验文件大小和 SHA；
  • 只读查看原 YAML；
  • 将验证证据附加到已保存 .vmaproj；
  • 作为 side-reference 开始手工重建；
  • 把历史 intent/evidence 送入 Screening Study banner。

Historical Migration

一个映射与附加例子

假设 catalog 路径以 ssmb-new-steps/... 开头，本机源码根是 /data/ssmb-new-steps：

  1. 打开 catalog，点击 Map Sources。
  2. 把 logical source ssmb-new-steps 映射到 /data/ssmb-new-steps。
  3. 选择记录并点击 Verify Selected。
  4. 只有状态为 verified 且 hash/size 精确匹配时，才能附加。
  5. 打开或保存当前项目为 .vmaproj，点击 Attach Evidence。
  6. Studio 原子保存、重开并再次验证包；项目 physics revision 不变。

映射只保存在本机设置，不写入 catalog 或项目。绝对/穿越路径、..、符号链接逃逸、缺失或 hash mismatch 都会 fail closed。

三种迁移方式

  • Bounded migration：catalog 已证明能安全映射的有限结构/输入；
  • Structural project + external experiment：保留结构，外部实验语义仍在历史系统；
  • Evidence/manual reconstruction：只附加原始证据，由用户在当前项目中显式重建。

Studio 不会从文件名或旧标量推断环周长、harmonic、beam、RF 或 lattice，也不会把历史 GPU 工作改称 CPU、把 DA/FMA 改称普通 tracking，或把历史结果提升为当前 physics revision。

为什么历史页面的 Import Xsuite 可能禁用

审计目录可能只提供一个 Xsuite 逻辑路径，却没有独立 expected SHA。由本地文件自己计算出的 hash 不是独立审阅证据，所以按钮保持禁用。获得受审阅 SHA 后，应使用上面的独立命令行结构 importer。