Running from the GUI¶

The HELIX desktop app exposes the same workflows as the Python API (Simulation.run() / Simulation.run_envelope()) plus matching, error studies, and orbit correction — all without writing code. This chapter is the short "how do I just run a simulation" walkthrough. For a full tour of every tab and panel see GUI overview.

Launching¶

In a Python environment with the linac_gen_gui package installed (or via the bundled .exe):

# From source (Linux / macOS / WSL):
PYTHONPATH=/path/to/Linac_Gen:/path/to/Linac_Gen/gui \
    python3 -m linac_gen_gui.interphase

# Windows .exe build:
HELIX.exe

The window opens on the Beam tab.

Path A — envelope or multi-particle run¶

The simplest "track a beam through a lattice and look at the σ plots" workflow.

Lattice tab with the correction-demo lattice loaded

Lattice tab — toolbar (top), outline tree + filter (left), sequential lattice listing + element timeline (centre), inspector (right). The "Correct orbit" button sits in the toolbar between Undo/Redo and the summary text.

Lattice tab → Open… (or File → Open Lattice…, Ctrl+O). The filter accepts TraceWin .dat and MAD-X .madx / .seq files; projects open separately via File → Open Project…. The element timeline + outline tree populate.
Beam tab → set species, kinetic energy, RF frequency, current, distribution, and Twiss / emittance values. Hit Apply to commit — nothing else commits the form (no Tab-off), though the first Run pulls the form automatically if you haven't applied anything yet.

Beam tab — three fixed groups (Particle · Energy · RF · Current, Twiss — X / Y / Z, Centroid · Mismatch · Derived) and the four-panel initial-phase-space preview at the bottom. 3. Numerics tab (optional) → adjust integration step density, PIC grid resolution, or solver backend if the defaults don't fit your case. Most users skip this. 4. Toolbar → Run Envelope (Ctrl+R) for the fast σ-only pass, or Run Multi-particle (Ctrl+Shift+R) for the full macroparticle ensemble (with PIC space charge if a SpaceChargeConfig is configured). 5. Results tab → centroid / σ-x / σ-y / emittance / phase-space plots populate. The tab's only button is Import Results… (reload a saved run); saving figures or data happens per popup — open a card and press Ctrl+S or right-click for "Save plot…".

Results tab — KPI strip across the top (σ_x / σ_y / σ_z end, ε_x growth, transmission, loss); below that the result cards (RMS σ, geometric / normalised / 6-D emittances, Twiss, phase advance, tune depression, divergence, halo). Click any card to open the full-size plot; cards stay open side-by-side for comparison.

While a run is in flight the toolbar's s-label doubles as the progress readout — s = 3400 / 18957 mm · 18% — and the slider sweeps the lattice in real s (there is no elapsed-time display). Stop on the toolbar cancels a running worker cleanly without corrupting the partial recorder.

Path B — TraceWin matching (SET / ADJUST cards)¶

When the loaded .dat carries SET_* and ADJUST_* matching directives (or you've added them programmatically), the Matching tab picks them up automatically.

Load a lattice with SET_* / ADJUST_* cards (or use one of the worked examples in examples/matching/).
Matching tab → pick the algorithm and options in the Auto-Adjust panel. The variables, constraints, and bounds come from the .dat cards and are read-only in the GUI — to change a bound, edit the ADJUST card and reload. The Variables / Constraints tables are empty until a match has run.
Match → the matcher runs in the background and writes the converged values back onto the lattice. The default algorithm least_squares solves the system with Levenberg–Marquardt via SciPy; six others are available (differential_evolution, dual_annealing, gradient, cmaes, sequential_scan, bayesopt). The status line shows iteration count and baseline → final cost; the tables fill with per-variable values and per-constraint residuals.
After matching: Run Envelope to verify the σ trace meets your design intent. See Matching → Recipes for canonical patterns (achromat, beta-bumping, Twiss matching).

Path C — Monte-Carlo error study¶

Plant random errors per seed, track each, aggregate the ensemble.

Error Study tab with a quad-dx spec ready to add and the
Orbit-correction group enabled

Error Study tab — element / beam-error forms at the top, list of registered errors below, the Orbit-correction group (with Method / n_iter / Tolerance / BPM-noise) in the middle, the Run group with n_seeds + progress bar at the bottom.

Lattice + Beam tabs → set up the deterministic baseline.
Error Study tab → element form → register one or more error specs. Pick target type (Quadrupole / Cavity / Bend / Solenoid), name pattern, parameter, distribution, σ or half-width, cutoff. Add element error. Repeat for as many specs as you want; register beam-input errors via the second form.
(Optional) Orbit correction group → tick Apply orbit correction after errors to run a correction pass per seed between error injection and tracking. See Errors → Orbit correction.
Run study → set n_seeds (start with 20-50) and hit go. Progress bar advances per seed.
Results tab → ensemble plots (mean ± σ envelope, per-seed centroid spread, transmission histogram).

Path D — Standalone orbit correction¶

A one-shot fix-up for a lattice that has steerers + BPMs (or ADJUST_STEERER + DIAG_POSITION cards).

Lattice tab → Open… the lattice.
Beam tab → confirm beam settings.
Lattice tab → Correct orbit toolbar button.
Summary dialog reports the chosen method, the correction status, RMS-orbit at the first / final pass, per-pass transmission, and per-steerer kicks. Steerer bx_l / by_l are mutated in place; subsequent envelope / MP runs use the corrected values. A pass that loses the beam (Status: beam_lost) applies no kicks — a warning names the element where the transmission reached 0 % (see the dead-beam contract).

Full walkthrough + example numbers in Errors → Orbit correction → Path A.

Saving / restoring projects¶

A HELIX project (.lgproj) is a self-describing JSON snapshot of every user-settable GUI value (beam config, convergence config, correction settings, error specs) plus a path reference to the loaded lattice.

File → Save Project… writes a .lgproj next to your .dat.
File → Open Project… restores the entire GUI state in one click.
Auto-restore: on launch the GUI re-opens the most recent project if there is one, falling back to the last bare lattice otherwise (silently — no popup if it's missing). A project carries its own lattice reference, so the two never load together.

Automatic result dumps¶

Every completed run auto-writes two files into the calculation directory (File → Set Calculation Directory…):

<timestamp>_<run_type>.h5 — HELIX-native HDF5 schema.
<timestamp>_<run_type>.opmd.h5 — openPMD-1.1 (interop).

Either file can be reloaded later via the Results tab's Import Results… button.

Stopping / canceling¶

Long runs (multi-particle + 3-D PIC on a 256-m lattice) can take many minutes. Stop on the toolbar interrupts the worker thread between elements; the partial recorder is discarded and the results tab reverts to the previous run. Closing the window also cancels any active worker.

Runs with the window in the background (macOS)¶

macOS puts an app whose window is not in front into App Nap: its threads drop to a low scheduling priority and a computation gets fewer cores (measured: priority 4 instead of 46 within about 35 s, and 1.5 to 2.9 of 3 cores). While HELIX computes — a run, a study, a scan, a match, an ORM fit or any other job that keeps at least half a core busy — it tells macOS that user-initiated work is in progress, which keeps it out of App Nap at full speed. The hold ends a few seconds after the work stops; the Mac may still go to sleep as usual. Runs from the command line are not affected by App Nap.