跳转至

安装与十分钟上手

English · 上一章：简介 · 下一章：界面与设置

本章用仓库自带的项目完成一次不联网的浏览，再说明如何连接 Engine。当前仓库提供源码构建流程，未提供独立安装包。

1. 构建 Studio

macOS 或 Linux：

./scripts/build.sh

脚本会检查 C++ 编译器、CMake、Ninja、Qt 6 和 Protobuf，运行测试并做一次离线启动检查。macOS 的自动安装需要 Homebrew；Linux 支持常见的 apt-get、dnf、pacman 和 zypper。

Windows x64（PowerShell）：

.\scripts\windows\build-and-test.ps1

若你只想先检查环境：

./scripts/build.sh --check-only

.\scripts\windows\build-and-test.ps1 -CheckOnly

更多依赖和构建变体见命令行与构建参考。构建 Studio 不会安装或启动 Engine。

2. 离线启动并打开示例

macOS：

./build/dev/vm-accelerator-studio.app/Contents/MacOS/vm-accelerator-studio \
  --offline --language zh-CN \
  protocol/v0_1/fixtures/minimum-electron-ring.canonical.studio-project.json

Linux：

./build/dev/vm-accelerator-studio --offline --language zh-CN \
  protocol/v0_1/fixtures/minimum-electron-ring.canonical.studio-project.json

Windows：

.\build\windows-msvc-debug\vm-accelerator-studio.exe --offline --language zh-CN `
  protocol\v0_1\fixtures\minimum-electron-ring.canonical.studio-project.json

这个示例有 86 个有序实例，适合熟悉界面。--offline 会关闭启动时的任务恢复和自动远端对账；只要不主动点击探测或计算，就不会联系 Engine。

3. 完成第一次浏览

  1. 在 Design → Lattice 查看线性晶格图和下方序列表。
  2. 单击一个 Quadrupole，在 Properties 面板查看长度和 k1 等 SI 参数。
  3. 使用鼠标滚轮缩放，点击 Fit 恢复全图。
  4. 点击 Circular Lattice。它按路径长度画出环形拓扑，不是隧道或磁铁的测量几何。
  5. 关闭环形视图，选择两个相邻实例，尝试 Define Cell。Cell 是 Studio 的组织工具，不会把折叠结构发给 Engine。
  6. 点击 Undo 撤销刚才的修改。
  7. 使用 Save As 保存成 my-first-ring.vmaproj。打开 JSON 后的第一次保存不会覆盖原 JSON。

4. 新建一个项目，理解“可保存但未就绪”

选择 Project → New，填写：

字段 示例
Project name My 3 GeV ring
Stable project ID my-3gev-ring
Electron reference energy 3 GeV total

新项目只有一个 START Marker，RF 关闭，束流、孔径和动量接受度都缺失。这是正常状态。先保存为 .vmaproj，然后通过 Add Element 建立晶格。只有当前草稿通过结构和闭环检查后，规范 Engine JSON、光学和跟踪按钮才会启用。

5. 第一次远程计算

你需要 Engine 管理员提供 SSH 别名和 Engine 可执行文件路径。然后：

  1. 打开 Edit/Preferences → Settings → Execution targets。
  2. 新增目标，例如显示名 Accepted Engine、SSH 别名 ubuntu-big、可执行文件 /opt/vm-accelerator/bin/vm-accelerator-engine。
  3. 先点 Test SSH，再点 Test v0.1 Engine。前者成功只证明登录和远程命令可用。
  4. 选中目标，打开上面的 v0.1 示例，点击 Calculate → Evaluate Optics。
  5. 成功后在 Optics Result 中查看 Qx/Qy、色品和 β/色散图，并检查 Qualification 与修订标识。

如果需要从平衡一路运行到局部接受度，请改用：

protocol/v0_3/fixtures/fodo-ring.studio-project.json

然后进入 Calculate → Screening Study，按平衡计算链中的步骤运行。示例 fixture 是回归和上手材料，不是可建造机器方案。

十分钟后的下一步