Welcome back to HELIX — the Hybrid Envelope-multiparticle LInac eXplorer. In episode one we installed the code and ran a first beam. This time we tour the whole cockpit — every menu, every dialog, the status bar, the shortcuts, and the manual behind them. Our machine is a drift tube linac section taking protons from 3 to about 7 M e V.
Here is the interface with that machine loaded. A thin titlebar at the very top, the toolbar with the menus and Run buttons under it, the tabs, and a status bar that always shows the element count and total length — and, after a run, the final beam size and the losses. Let us take these strips one at a time, from the top.
The titlebar, enlarged in two halves. The brand, then the loaded lattice with its element count — dtl section dot dat, 38 elements. On the right, the Python version and platform, and a clock. Watch the seconds tick — this strip is live, and the label follows every lattice you open.
The File menu, enlarged on the right. New Project starts the guided wizard — also the toolbar's New button, or control N. Open, Save and Save As manage the lattice file itself. The project group bundles lattice, beam and solver settings into one file, with Open Recent remembering them. Set Calculation Directory chooses where run dumps land, then two exporters — TraceWin and open P M D. And Exit warns you first if anything is unsaved.
Open Lattice speaks more than TraceWin — the filter lists dot dat plus M A D X, M A D 8 and Elegant extensions, each routed to its own importer. Saving always writes TraceWin style dot dat, so HELIX never overwrites a M A D X source file.
The New Project wizard. A name and a location — a folder of that name is created and runs land inside it, so the whole project moves as one unit. Three starting points: a blank lattice with one editable drift, importing an existing dot dat — copied into the folder — or a bundled example: the FODO cell, the solenoid channel, or this very D T L section.
Watch the status bar as we save this session as a project — there is the confirmation. Every action gets visible feedback down there. File, Open Recent now lists the project, with Clear Recent Projects underneath. Projects also power session restore — the next launch reopens what you were working on, beam included.
Now the tabs. The Lattice tab is home. On the left the palette, every element type HELIX knows, ready to drag in. Next to it, the outline groups the loaded elements by type. The centre shows the machine two ways — a layout strip you can scrub, and the sequence view, the lattice file itself, line by line.
Click any element and the inspector opens on the right — here, one of the R F gaps. Every parameter is editable: the R F phase, the frequency, the error knobs, the alignment offsets and tilts. Change a number, press enter, and the next run uses it. Undo and redo cover every edit. And remember this for later: with an element selected, F 1 opens its manual chapter.
The Beam tab defines what you inject. Species, kinetic energy, bunch frequency, and current. Below that, the Twiss parameters and emittances that set the beam's size and divergence in each plane. If you have a particle file, load it here instead and HELIX tracks exactly those particles.
The Numerics tab holds the solver settings — integration steps per metre, the space charge model and its grid, and the field map handling. The defaults are sensible. When a result looks suspicious, come here and double the steps to check convergence.
The Matching tab turns knobs for you. Choose which element parameters are free, set targets — beam sizes, Twiss values, or a matched periodic cell — and HELIX adjusts the knobs to hit them. Matching gets its own episode later.
Four tabs run campaigns rather than single runs. Param Study scans parameters over ranges — the big sibling of the quick Parameter Scan dialog we will meet in the Tools menu. Error Study adds random misalignments to estimate tolerances. Failure Study switches elements off to see what survives. And Surrogates trains fast machine-learned stand-ins.
Time to run for real: 20 milliamps of current, 120000 macro particles, space charge on. The moment Run Multi particle is clicked, the pill turns RUNNING, Stop lights up red, and the s label becomes a live readout with a percent counter while the slider sweeps the machine. At the end, the status bar reports the run complete and names the file it auto-saved.
The same run again — but this time we pull the brake at about 40 percent. Stop cancels at the next element boundary, and the status bar confirms the run was stopped by you. No half-written results — the previous results stay. And between runs the slider is yours: scrub it, and the s position follows in the toolbar and status bar together.
The status bar up close. Left to right: the state pill, the lattice summary — 38 elements, 860 millimetres — your s position, and after our run the final beam size and the loss, with the version on the far right. Loss above 1 percent renders amber, and our rough hand-set optics lost about a third. Now watch — we edit a quadrupole length and the unsaved pill lights until the edit is undone. Then control S: the saved confirmation appears and clears itself after about six seconds. One honest caveat — the W segment is reserved and does not yet track live energy.
The Simulate menu. The two run entries mirror the toolbar buttons, with control R and control shift R as shortcuts. Backtrack Distribution reconstructs the beam upstream from an exit distribution — we run it next. And Multibunch, Pulse Study is the opt-in bunch-train mode for beam loading and long-pulse effects.
The Backtrack dialog. Pick the source — the final beam of the run we just did, or a measured exit-plane dot d s t file — then the element range and the field map inverse. R K 4 is the exact default. A tick undoes space charge with the Numerics settings, and the output box writes the reconstructed entrance distribution to a file.
And off it goes — the status bar announces the backward walk, exit of element 37 to the entrance of element 0, and the s cursor returns to zero as the survivors are tracked back. Lost particles cannot be resurrected — the caveat box spells out that the reconstruction covers surviving particles only.
Every run lands in the Results tab. Here we fire the envelope solver — done the moment the button is released, with the completion message naming the sigma values and the auto-saved file. Each tile is one quantity — sizes, emittances, energy, losses, Twiss, phase advance. Tiles with data show a preview curve; clicking one opens the full plot window.
The Energy plot for our D T L. Each step of the staircase is one R F gap kicking the protons — eight gaps, 3 M e V in, about 7 M e V out. Every plot popup shares the same controls: zoom, pan, toggle the lattice strip, and control S to export the data or the image.
Runs never vanish. Every completed run wrote two files into the calculation directory without being asked — a HELIX-native H D F 5 file and an open P M D companion, timestamped. This listing is from the session you are watching, together with the files from File, Export TraceWin output — partran 1 dot out and an envelope text file for TraceWin-side tooling.
The Tools menu — five power tools that work from any tab. The Assistant is the optional A I copilot with a full episode of its own later. The other four we open right now.
The Python console, live against this session. l g is the linac gen package, state is the app state, and lattice, beam config and results are always in scope. The element count — 38. The final beam size of the last run. The injection energy — 3 M e V. Expressions print their value; statements just run.
The two matrix viewers. Show Transfer Matrix multiplies the per-element linear maps over any range — pure linear transport — and reports the energy gain, 3 to about 7 M e V across the line. Show Sigma Matrix displays the measured second-moment matrix of the last run at every recorded step. One needs a lattice and beam, the other needs results.
Tools, Parameter Scan — the quick single-knob version. One element, one parameter, a range, envelope or multi particle, and Run scan plots the quantity you chose. It is non-modal, so the main window stays live. For multi-parameter campaigns with saved results, use the Param Study tab instead.
The Help menu. Documentation opens the full manual — built locally, so it works offline. Check for Updates asks GitHub for a newer release on demand, and the startup check is a toggle you can switch off. Nothing here ever updates the code without your explicit confirmation.
About HELIX — the one-screen summary of this build. The version at the top. Three engines: matrix, envelope, multi particle. Space charge analytical or particle in cell. Backends from plain C P U through CUDA to Apple Silicon, and TraceWin plus H D F 5 for I O.
Help, Documentation lands here — the HELIX manual, a local website with working search and a light-dark toggle in the header. The G U I section mirrors this tour, one chapter per tab plus overview, workflows and updates. Everything we cover on camera is written down here.
One chapter is worth pinning: G U I workflows, the cheat sheet that starts from the task. I want to load a TraceWin deck and run it. I want to match Twiss to a target. An alignment tolerance study, the G P U, backtracking — each one a numbered click path. When you forget where a feature lives, start here, not in the menus.
Context help closes the loop. Our R F gap is still selected — press F 1, and the status bar confirms HELIX opened the gap's manual chapter in the browser. This is that page: the gap model, its parameters, its conventions. With nothing selected, F 1 just asks you to pick an element first.
Updates — driven by hand here so you can see the shape of it. A few seconds after launch, HELIX quietly asks GitHub whether a newer release exists; silence means you are current, or offline. When one exists, this pill appears in the status bar and the Help entry turns bold with the tag. Nothing happens until you click and confirm.
The updates chapter spells out the contract. A clean clone of the official repository fast-forwards in place with a progress window. A copy with local changes just gets the release page — your edits are never touched. Dependencies are never installed automatically, and developer checkouts are left alone entirely.
One control for your eyes: the Font spinbox, 9 to 22 points. Watch the whole interface rescale together — titlebar, toolbar, tabs and status bar. Control plus and control minus do the same from the keyboard, control zero resets, and the size is remembered for the next launch.
The full shortcut list, straight from the source. Control N, new project. Control O, open lattice. Control S, save. Control R runs the envelope, control shift R runs multi particle. Control plus, minus and zero drive the font size. And F 1 opens the manual chapter for the selected element. They work from every tab — the toolbar owns them.
That is the whole cockpit — every menu, the wizard, projects, a run stopped mid-flight, backtracking, the console, the matrix viewers, auto-saves, updates, and the manual. From here the series goes deep, one tab per episode — the Lattice tab first, then Beam, Numerics, Matching, Results and the study tabs, with space charge and the assistant further on. See you there.