VM Accelerator Studio User Guide¶
简体中文 · Install and ten-minute quickstart
VM Accelerator Studio is a native low-code workstation for electron storage rings. Use Studio to
build and revise a lattice, enter reviewed physics inputs, start calculations, and inspect their
evidence. A separately deployed Linux vm-accelerator Engine is authoritative for numerical
physics. Keeping the two separate makes the design input, compute environment, and result origin
explicit and traceable.
What the system contains¶
flowchart LR
A[Local Studio workstation<br/>projects, authoring, tasks, results] -->|explicit SSH calculation| B[vm-accelerator Engine<br/>validation and physics]
B -->|identity- and hash-bound results| A
A --> C[Local verified result stores]
A --> D[.vmaproj / canonical JSON]| Part | Primary responsibility | What it does not do |
|---|---|---|
| Studio | Project/lattice authoring, workflow orchestration, visualization, evidence replay, recovery | It does not reimplement Engine physics or guess missing inputs |
| Engine | Project validation and optics, tracking, equilibrium, acceptance, Touschek, nonlinear, and orbit calculations | It does not replace engineering review or machine measurement |
.vmaproj |
Authoritative project, recoverable drafts, Cell layout, and selected study metadata/evidence | It is not renamed JSON |
| Local stores | Immutable results reverified whenever reopened | They never promote an old revision to the current revision |
Inspirations and distinguishing features¶
Studio follows the working style of desktop CAD/CAE tools and an Office-style Ribbon: common actions are grouped under Project, Design, Calculate, Results, History, and View, while the entire interface remains native Qt Widgets rather than a browser. Physics routes primarily use Xsuite/Xtrack; selected critical routes include independent PyAT numerical comparisons, and the corrected Touschek route retains formula-source and cross-code audit evidence. Canonical JSON, project/physics identities, and SHA-256 connect projects, jobs, and results without requiring a normal user to edit those fields.
Key characteristics include:
- Low-code without lowering the evidence bar. Edit through tables, properties, Families, and Cells, while Engine validation remains mandatory.
- Missing means missing. An incomplete project can be saved; Studio does not invent RF, current, emittance, aperture, or acceptance.
- Exact revision binding. A physical edit makes older results
STALE; they remain readable but cannot masquerade as current. - Local design, explicit remote compute. Studio contacts a target only for a probe, calculation, task operation, or enabled startup recovery.
- Recoverable durable work. Tracking, corrected Touschek, nonlinear, and orbit jobs can keep running after the UI disconnects.
- Live English/Chinese switching. Localization never rewrites canonical JSON, units, formulas, identifiers, hashes, or Engine evidence bytes.
How to interpret results¶
The highest claim made by every current numerical route is SCREENING. Results are useful for design exploration, regression comparison, and detecting obvious failures. By themselves they do not establish that a machine is buildable or operable, that machine DA/LMA/lifetime is qualified, that every error/correction/collective/RF/radiation/tolerance effect is included, or that a model matches a measured machine.
Read Qualification, Validity, warnings, applicability, and project revision before focusing on a headline scalar.
Feature map¶
| Goal | Chapter |
|---|---|
| Install, launch, language, and theme | Quickstart, Interface |
| Create/import/save/export a project | Projects, lattices, and revisions |
| Elements, Families, Cells, circular view, revision review | Projects, lattices, and revisions |
| RF, radiation, and equilibrium inputs | Physics inputs |
| SSH targets, credentials, recovery, cancellation | Engine connection |
| Twiss optics and generic tracking | Linear optics and durable tracking |
| Radiation slices, equilibrium, matched distribution, LMA | Equilibrium chain |
| Orchestration and corrected/historical Touschek | Screening Study and Touschek |
| DA, FMA, losses, convergence | Nonlinear dynamics |
| Errors, BPMs, correctors, SVD, tolerance | Errors and orbit correction |
| Local results, comparison, evidence, export | Results and evidence |
| Xsuite and historical YAML | Import and migration |
| Version matrix, build, CLI, troubleshooting | Engine capabilities, CLI, Troubleshooting |
Suggested paths through this guide¶
First-time users should complete the ten-minute quickstart, then read Projects, lattices, and revisions and Connect and manage an Engine.
For a complete v0.2 calculation chain, continue with Physics inputs, Equilibrium, matched distribution, and LMA, and Screening Study and Touschek.
Engine operators can go directly to Engine capabilities and version boundaries and CLI and build reference.