跳转至

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 Studio 1.1 release record covers native packages for macOS arm64, Linux x86_64, and Windows x86_64; actual downloads depend on the release channel. Before opening an artifact, verify it against dist/SHA256SUMS from the same release. A matching checksum proves byte identity, not code-signing, notarization, or site-policy approval.

1. Install a release package or build Studio

Studio 1.1 has the following native output formats; packages are built on their target OS rather than cross-compiled:

Platform Release outputs
macOS arm64 ZIP; a publisher may also produce a DMG
Linux x86_64 tar.gz, DEB, AppImage
Windows x86_64 Portable ZIP, MSI, NSIS installer

If the release channel does not provide an artifact for the current platform, build from source. 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 with an explicit offline policy 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. Normal startup is already network-idle: Studio does not authenticate, recover pending work, or reconcile remote registries at launch. --offline records the explicit offline intent for this review. Do not invoke a later Test, calculation, Reconnect, Recover, or remote-refresh action if the whole session must remain network-free.

3. Complete your first review

  1. Open Design → Lattice and inspect the dimensioned line and sequence table.
  2. Select a Quadrupole and inspect its complete SI parameter table in Properties. Length and k1 are visible together and changed cells are applied as one revision.
  3. Zoom with the mouse wheel; use Fit to restore the full line.
  4. Open Lattice Geometry. It reconstructs the 2D reference path from lengths and bend angles, reports any closure gap, and is explicitly 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, and keep the recommended managed-tunnel mode.
  3. Reopen the bundled v0.1 sample and choose Calculate → Evaluate Optics. Studio first opens Choose computation source; merely opening or cancelling it performs no network work.
  4. Select Accepted Engine and accept Check source. Only now does Studio inspect the SSH route, request any password, host-key confirmation, or Authenticator code in an in-application dialog, establish the private tunnel, and check Engine readiness. No terminal command is required.
  5. After the checks and route-specific validation succeed, Studio starts the calculation. Inspect Qx/Qy, chromaticity, beta/dispersion, Qualification, and revision identity.

Test SSH, Connect, and Test Engine remain available in Settings as separate explicit diagnostics; they are not required at startup and are not started by selecting a target.

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