Welcome back. This deep dive covers the Lattice tab completely: navigation, editing, and the tools. A real orbit correction, the R F Q vane swap, a live parameter scan, and the safety net around Save. Our machine is the drift tube linac from the tour.
The Lattice tab is home base. Everything HELIX simulates starts from what you see here. Four columns, left to right: the element palette, the outline tree, the centre column with the timeline and the listing, and the inspector, with the lattice toolbar above. We will walk through each in turn.
Open reads four formats: TraceWin dot dat, MAD X dot madx or dot seq, MAD eight dot lat or dot flat, and Elegant dot L T E; the extension picks the parser. Save writes the lattice back, Save As writes a copy, and Reload re parses the file from disk. And the summary, always visible: thirty eight elements, total length eight hundred sixty millimetres.
The palette lists every type HELIX knows, in five labelled families: magnets, cavities, drifts and passives, then the SET and ADJUST command cards, and an OTHER shelf for the foil. Thirty nine cards in all. Double click to append, or drag one into the machine. The field map cards ask for an external field file first.
This overview page is the element catalog: a pick by use case table, one row per type. Below it, the taxonomy. Every element is one of four kinds: closed form matrix elements, zero length kicks, substepped field maps, and passive markers. Right clicking any element in the G U I opens its chapter directly.
The outline groups the machine by name prefix, the text before the first dot or underscore; on an auto named deck that coincides with type. On a named machine it becomes section grouping, and groups over forty entries start collapsed. The FREQ entry wears a small gear, the badge of a command card. Clicking any entry selects that element everywhere.
Above the tree is a filter box. Type a few letters and the tree narrows to matching elements. Here we typed gap, and only the eight R F gaps remain. This is how you find one element in a machine with two thousand of them. Clearing the box restores the full tree.
The centre column: type chips with per family counts, and the timeline, the machine to scale. Every rectangle is an element, colour coded: purple solenoids, cyan quadrupoles, and the thin bright lines are R F gaps, zero length cards drawn with a minimum width so they never vanish. Drifts render half height and dimmed. The small amber squares are validation badges. Click to select: the selected quadrupole gets a white outline.
The chips are not just counters. Click one, and the timeline dims everything else. Only the quadrupoles stay lit, and the focusing pattern is suddenly obvious. Chips combine: add the gaps, and both families glow. An empty selection means show everything.
Hold control and scroll to zoom the strip, up to ten times, down to a quarter; reset brings the whole machine back. The cyan vertical line is the s cursor, shared application state: when a results view moves it, this strip follows. Here we sweep it along the machine.
Shift click adds bars to a multi selection, each with a soft halo. These three drifts are now one unit: delete removes all of them as a single command, delete three elements, and the listing shortens. One control Z brings all three back. Grouped edits stay grouped on the undo stack.
HELIX re validates after every edit. Four advisory rules: apertures that are not positive, negative lengths, zero length on elements that should have one, and R F elements with no frequency upstream. This deck's gap cards are zero length by construction, so they already wear badges. Now watch: we zero the quadrupole's length, the bar collapses, and a badge appears instantly. Undo clears it. Badges never block a save.
Below, the Sequence view: the machine as a list, in beam order. Each row shows index, position in millimetres, the TraceWin keyword, and arguments that adapt per type: a quad shows length, gradient, aperture; a gap shows voltage, phase, frequency. Rows carry the timeline's family colours, and the listing follows your selection from anywhere.
Rows in the outline drag and drop, and the tree translates the drop into a move of the flat lattice. A quadrupole moves down the machine: the listing renumbers, the timeline redraws. A move is a command like any other; control Z puts it back.
The second tab of the listing is Breakdown. Instead of beam order, it summarises the machine per element type. How many of each, their total length, and the share of the machine they occupy. It is the quickest sanity check that an imported file contains what you expect.
The inspector is where elements are edited; its colour swatch matches the timeline. For a quadrupole: length, gradient, aperture, gradient error, skew angle, and g three to g six, the higher order gradients. Then alignment, and an honesty note: only the offsets in x and y and the tilt about z act on the beam in tracking. Offset in z, pitch, and yaw are stored and saved, but not used in tracking.
Editing is direct: click a field, type, enter. The gradient goes from eight to nine tesla per metre and the sequence view updates immediately. Every change is a command on a bus: undo reverts it, redo applies it again, and the status bar names every edit. Spin boxes adapt their decimals so tiny kicks are never truncated. Nothing touches disk until you press Save.
The Add button, or the Insert key, opens this dialog. Every type is in the combo, and the form is built from the same schema the inspector uses: switch the type and the fields change with it, each with its units. We name ours Q DEMO, accept, and the new quadrupole lands after the current selection, already selected for editing. We will undo it shortly.
Or drag a card straight onto the timeline. While you drag, a cyan line tracks the nearest insertion gap. Release, and the element is inserted at exactly that index, here a steerer, with the status bar confirming the position. We undo that too: nothing here is more than one control Z from safety.
The rest of the loop. Duplicate clones the selection after itself, control D. Delete removes it, the delete key. Undo and redo walk the stack, control Z, control Y. Copy, cut and paste, control C, X and V, use an internal clipboard of deep copies: copy this solenoid, select the end marker, paste, and a fresh copy appears there.
Right click the timeline or outline for the edit menu: insert before or after, duplicate, delete, and the clipboard actions. Paste needs something on the clipboard first. Right click a row in the outline or listing for one more entry: open the manual for this type.
Here is that manual. The question mark in the inspector header opens the chapter for the selected type, rendered from the markdown source, and it stays on top while you edit underneath. Every chapter has the same shape: a T L D R table against the TraceWin card, a tutorial, and the full A P I reference.
The inspector adapts to every type. An aperture gets a shape dropdown, rectangular, circular, pepperpot and four more; we flip this one to pepperpot. A marker gets two checkboxes: trigger a beam snapshot, or serve as a beam position monitor. A steerer is two numbers, the integrated field in x and y, in tesla metres. And R F elements carry an error block: voltage error, phase offset, frequency offset.
Command cards are elements too. We drop in a SET TWISS card: it sits in the machine like any magnet but carries beam commands instead of fields. In the outline it wears the gear. The inspector builds its editor automatically from the card's own parameters, keyword read only at the top.
ADJUST cards get the same treatment, plus one convention: the flags list. Zero skips a parameter, one adjusts it, two couples it to the previous one. The Matching episode uses these cards in anger.
Now the tools, on the correction demo deck. Six F O D O cells, four steerer and B P M pairs. First, sabotage: this quadrupole moves half a millimetre sideways. Correct orbit tracks the beam in a background worker; the button becomes Cancel correction and the G U I stays live. The report: method one to one, four pairs, and an R M S orbit error under zero point zero four millimetres after a single pass. The kicks arrive as one undoable command, and the lattice is flagged as fitted, so plain Save reroutes to Save As. One undo removes every kick, a second removes the sabotage.
B P M targets loads a measured orbit: plain text, one x y pair per monitor, nan leaves a plane free. Our DIAG POSITION cards carry explicit operands, shown in the inspector's diagnostic matching block. Load the file: the status bar confirms four rows, runtime only, never saved into the dot dat. A new inspector row appears, the file override, which wins over the deck values. Loading is not an undoable edit; reload the lattice to clear it.
One button remains, RfqCell to VaneRFQ, for R F Q work. This deck holds one hundred ninety nine cell cards, each a thin bar. The button asks for a dot vane file, the same geometry Toutatis uses, and a field model. One click, and the cells become a single vane R F Q element spanning the machine; the status bar reports the swap. If you never touch R F Qs, you never need this, and that is fine.
The consolidated element keeps the whole cell chain, the listing reports one hundred ninety nine cells, and the inspector lets you switch field model any time: two term, eight term, full eight term, or the two Laplace solvers.
One more tool, from the Tools menu: Parameter Scan. Pick any element and numeric parameter, here quadrupole three's gradient, a range, six to ten tesla per metre in nine points, and a mode, envelope or multi particle. The output list is deep: R M S sizes, normalised and eigen emittances, the four D invariant, transmission, growth ratios, and two multi particle only halo metrics. Run. Nine envelope points land in under a second: more gradient, smaller horizontal beam, twelve point one down to eleven point six millimetres.
The guarantee that makes scanning safe: when the scan ends, the parameter snaps back to nominal. The lattice is never left modified, the inspector shows the gradient back at exactly eight, and the dialog is non modal, so leave it open and keep working.
Nearly done. Save writes the lattice back; Reload is the fastest way back to the file on disk. Watch the bottom edge: one gradient edit, and the amber unsaved dot lights in the status bar beside the edit's own message. Lattice edits and project settings are separate flags. Try to open another file or quit now, and HELIX asks first.
Show Details itemizes what is at risk, one line per edit: our quadrupole, gradient eight to nine. Two more protections. A lattice carrying fitted values reroutes plain Save to Save As, suggesting a dot matched dot dat name. And a lattice imported from MAD X, MAD eight or Elegant is never written back to its source: HELIX writes TraceWin format only, so Save becomes Save As.
Everything here is written down in the manual's Lattice tab chapter: the layout, the shortcuts, the editing rules, orbit correction and B P M targets, the formats, and the exact saving rules. The element catalog goes deeper on every type we touched, one press of the question mark away.
That is the entire Lattice tab, for real this time. Next, the Beam tab in the same depth: species, energy, current, emittance, and the distributions behind every run. See you there.