跳转至

Install and Ten-Minute Quickstart

简体中文 · Previous: Introduction · Next: Interface and settings

This chapter opens a bundled project without network access, then shows where to connect an Engine. The repository currently provides a source build, not a standalone installer.

1. Build Studio

On macOS or Linux:

./scripts/build.sh

The driver checks the compiler, CMake, Ninja, Qt 6, and Protobuf, runs tests, and performs an offline smoke launch. Automatic installation on macOS requires Homebrew. Linux supports common apt-get, dnf, pacman, and zypper systems.

On Windows x64, from PowerShell:

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

To check the environment before building:

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

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

See CLI and build reference for dependencies and variants. Building Studio does not install or start the Engine.

2. Start offline and open a sample

macOS:

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

Linux:

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

Windows:

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

The sample has 86 ordered occurrences. --offline disables startup recovery and automatic remote reconciliation. It will not contact an Engine unless you explicitly start a probe or calculation.

3. Complete your first review

  1. Open Design → Lattice and inspect the dimensioned line and sequence table.
  2. Select a Quadrupole and inspect its SI length and k1 in Properties.
  3. Zoom with the mouse wheel; use Fit to restore the full line.
  4. Open Circular Lattice. It is a path-length topology, not surveyed tunnel geometry.
  5. Select two adjacent occurrences and try Define Cell. A Cell is a Studio organization feature; Engine still receives the fully expanded sequence.
  6. Use Undo to revert the change.
  7. Use Save As to create my-first-ring.vmaproj. Saving an imported JSON never overwrites the source JSON.

4. Create a project and understand “saveable but not ready”

Choose Project → New and enter:

Field Example
Project name My 3 GeV ring
Stable project ID my-3gev-ring
Electron reference energy 3 GeV total

The project contains only a START marker. RF is off and beam, aperture, momentum acceptance, and a closed lattice are absent. This is intentional. Save the .vmaproj, then build the line with Add Element. Canonical Engine JSON, optics, and tracking become available only when the current draft passes the structure and closure gates.

5. Run a first remote calculation

Ask the Engine operator for an SSH alias and Engine executable path, then:

  1. Open Settings → Execution targets.
  2. Add a target such as Accepted Engine, host ubuntu-big, executable /opt/vm-accelerator/bin/vm-accelerator-engine.
  3. Run Test SSH, followed by Test v0.1 Engine. SSH success proves only authentication and remote command execution.
  4. Select the target, reopen the bundled v0.1 sample, and choose Calculate → Evaluate Optics.
  5. Inspect Qx/Qy, chromaticity, beta/dispersion, Qualification, and revision identity.

For the equilibrium-to-local-acceptance chain, open:

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

Then use Calculate → Screening Study and follow the equilibrium chain guide. Bundled fixtures are learning and regression material, not buildable machine designs.

Where to go next