Skip to content

GUI workflows

Task-oriented quick reference: "I want to do X, where do I click?"

"I want to load a TraceWin .dat and run it"

  1. Lattice tab → Open… (or File → Open Lattice…, Ctrl+O) → pick .dat.
  2. Beam tab → set energy, current, distribution → Apply.
  3. Numerics tab → leave defaults for first run.
  4. Toolbar → click Run Envelope (fast σ-only pass) or Run Multi-particle.
  5. Results tab → click any tile.

"I have a TraceWin project (.dat + .ini) and want its beam in HELIX"

TraceWin keeps the input beam you typed into its Main/Beam panels in <project>.ini, next to the deck. Three routes; all three end with the beam in the Beam tab as the session beam, the project marked dirty, and every conversion warning in the console.

Route A — open the deck and say yes (a TraceWin project folder, first look):

  1. File → Open Lattice… (Ctrl+O) → pick <project>.dat.
  2. HELIX finds <project>.ini next to it and asks Import its beam into the Beam tab? This replaces the current beam settings. Click Yes. (No keeps whatever beam you had — nothing is read silently, and opening a .lgproj never asks.)
  3. Beam tab → check species, energy, frequency, current, particle count, ε and Twiss. alpha_z already has HELIX's sign. A LEBT project (no longitudinal emittance) arrives with Continuous beam ticked; set the DC energy spread yourself.
  4. Set what the file does not carry — distribution type, cut-off, centroids — then Apply if you changed anything.
  5. File → Save Project so the .lgproj carries the beam; from now on open the project, not the deck.

Route B — the deck is already open, or the .ini lives elsewhere:

  1. Beam tab → Import TraceWin .ini… → pick the file (any name, any folder).
  2. Read the status line next to the button (species, energy, frequency, current, particle count, and a warning count) and the console.
  3. Continue with steps 4–5 of route A.

Route C — a new HELIX project from a TraceWin deck:

  1. File → New Project… (Ctrl+N) → name and location → Import an existing lattice → browse to <project>.dat.
  2. The checkbox Also import the beam from the TraceWin .ini next to the deck lights up when a sibling .ini exists; tick it. With Copy the lattice into the project folder the .ini is copied alongside.
  3. OK — the project opens with the imported beam and its .lgproj is already written.

When something does not fit: a user-defined particle in the file (an ion, a My_particle slot) has no HELIX species — the import keeps the species selected in the Beam tab and says so in the console; pick the right one first. A value outside a field's range is clamped and reported. The PICNIC mesh sizes are recorded in the project file but not applied — HELIX's space-charge grid is set on the Numerics tab. For a second TraceWin input beam, or a deck whose .ini you want to use for one headless run only, use the CLI (twini --beam 2, --tracewin-ini): see Importing TraceWin project settings.

"I want to match Twiss to a target"

The matcher's variables and constraints come exclusively from ADJUST_* / SET_* cards in the .dat — there is no GUI entry for them. The realistic flow:

  1. Load lattice (see above).
  2. Add a Marker at the target s (Lattice tab → + Add… → Marker).
  3. Save the lattice (Ctrl+S), then add the matching cards to the .dat in a text editor: ADJUST cards on the quads you want to tune and a SET_TWISS (or other SET_*) card at the target — see SET / ADJUST cards for the syntax.
  4. Reload the lattice (Lattice tab → Reload).
  5. Matching tab → Match; watch the live convergence dialog.
  6. Apply to commit the matched values, then Save the matched .dat (or use Save matched .dat to export a copy).
  7. Verify with Run Envelope and the Results tab.

"I want to run an alignment-tolerance study"

  1. Load lattice.
  2. Error Study tab → Element errors → add dx, dy errors at QUAD_* with σ = 0.2 mm.
  3. Set n_seeds = 50 (or more for production).
  4. Click Run study.
  5. Results tab → Error-study ensemble tile.

"I want to see what's happening at element X"

  1. Lattice tab → click element X in the timeline or listing.
  2. Inspector on the right shows all parameters.
  3. (Optional) Add a Marker before/after for a snapshot — or set Numerics tab → Snapshot every N for periodic dumps.
  4. After running: Results tab → PHASE SPACE · DIAGNOSTICS → Phase space (4-panel) tile shows the full phase-space at the snapshot.

"I want to start a new project"

  1. File → New Project… (Ctrl+N, or the toolbar New button).
  2. Pick a name and a location — a folder <name>/ is created there.
  3. Choose the starting point: a blank lattice (one editable drift), import an existing .dat (copied into the folder by default so the project stays portable; when a TraceWin <deck>.ini sits next to it, a checkbox also imports that project's beam — see Beam tab), or a bundled example (FODO cell, solenoid channel, DTL section).
  4. The project opens immediately; simulation outputs land in <name>/runs/, so the whole folder can be moved, archived or version-controlled as one unit. File → Save Project updates the same .lgproj from then on.

"I want to compare two simulations"

  1. Run simulation 1 → File → Save Project As… sim1.lgproj.
  2. Modify whatever you want changed → Run simulation 2 → File → Save Project As… sim2.lgproj.
  3. Open both projects in two HELIX windows side by side.
  4. Tile-by-tile visual comparison.

(A built-in diff/overlay is on the roadmap.)

"I want to use the GPU"

  1. Numerics tab → PIC backend → gpu (or auto; the combo also offers cuda and mps to pin a specific device type).
  2. Run as usual.

If the GPU isn't available you'll see a console warning; HELIX falls back to CPU.

"I want to run a multi-particle simulation through the differentiable PIC"

  1. Numerics tab → SC engine → torch.
  2. (Grid mode and DC kernel grey out — expected. PIC backend cuda or gpu runs the kick on an NVIDIA GPU — not yet tested on one.)
  3. Toolbar → click Run Multi-particle.

The torch backend matches the default numpy PIC numerically and, in a forward run, about as fast. Pick it when you need an autograd- differentiable kick (e.g. chaining the simulation into a gradient- based optimiser); for ordinary forward runs leave SC engine on numpy, which also has fixed grids, continuous beams and bunch-train images. See Differentiable PIC.

"I want to match through non-linear PIC space charge"

  1. Load a lattice with ADJUST_* + SET_TWISS / SET_SIZE cards. The lattice must be all-linear (drift / quad / solenoid / dipole / edge — no RF or field maps).
  2. Matching tab → Algorithm → gradient.
  3. Tick Space charge.
  4. Click Match.
  5. Apply or Save matched .dat when done.

This is the only HELIX matcher that solves through non-linear PIC space charge. See Gradient algorithm.

"I want to reconstruct the input beam from an exit distribution"

  1. Either run a forward multi-particle simulation first (its final beam becomes selectable as the source), or have an exit-plane .dst at hand (measured or exported).
  2. Toolbar Simulate → Backtrack Distribution…
  3. Pick the source, the element range (defaults: full lattice), the field-map inverse (rk4, the exact default — round trips close at ~1e-13), and optionally tick space charge (uses the Numerics-tab SC settings) or set an output .dst for the reconstructed entrance distribution.
  4. Click OK — progress appears on the toolbar; Stop aborts at the next element boundary.
  5. The Results tab then shows the backward walk reversed to increasing s: index 0 is the reconstructed entrance. Losses cannot be undone — the reconstruction covers survivors only.

CLI equivalent: python -m linac_gen backtrack.

"I want to know which failures this linac tolerates"

Save the lattice, then Tools → Reliability Study…: pick the quick preset, point the circuit map at a circuits.json (or generate one from the deck and edit it), give leg C an error budget (or take the Error Study tab's entries), choose the worker count and Start. The Run tab follows the legs; the Results tab lists every fault case worst first, the compensations and their rule verdict, the seeds, the availability and the foil scenarios, and the report. Select a compensation and Apply compensator settings to put its settings on the session lattice as one undoable edit. The same campaign can be exported to another machine and imported back with the CLI (Export job… / Import results… in the window, or python -m linac_gen reliability export / import); Resume… shows any campaign folder in the window. See Reliability Study window.

Cross-references

← Results tab · Continue to Worked examples → Basic FODO →