Welcome to HELIX. In this opening episode you will install the code, verify it, learn the layout of the interface, create a project, and send a proton beam through a simple focusing lattice. No experience with accelerator codes is needed.
HELIX is a beam dynamics simulator for linear accelerators, developed at Fermi National Accelerator Laboratory for the P I P two superconducting linac. You describe the machine as a sequence of elements in the TraceWin lattice format, and HELIX tracks a beam through it three ways: a fast envelope solver, a multi-particle tracker with three dimensional space charge, and linear matrix tracking — on Windows, mac O S and Linux.
The manual's prerequisites table. Python three point ten or newer; NumPy, SciPy, H five P Y and matplotlib arrive automatically. PyTorch is required — surrogates and the Apple Silicon G P U path build on it. The rest — a C plus plus compiler for the fast kernels, CUDA with cupy, Py Q T six for the interface — is optional.
First, get the code. Clone it from the Accel Toolkit organisation on GitHub, or use the download zip button — the result is the same folder. Everything runs locally; nothing ever leaves your computer.
One command sets everything up — this is the real transcript of setup dot S H. It finds a Python of at least three point ten, builds a private virtual environment inside the repository — your system Python is never modified — installs everything, via U V when available, then smoke-tests the install and reports whether the fast C plus plus kernels were built. A missing compiler is not fatal — HELIX falls back to pure Python space charge, about twenty times slower — or use the switch on the last line for a hard error. Re-run it after any git pull — it updates in place.
On Windows, double click setup dot bat — it also pre-checks the two hundred sixty character path limit that can break the PyTorch install. On a Mac, setup dot command runs the same script and keeps the Terminal open, so any error stays readable. And with no Python at all, Windows users can run the bundled H E L I X dot E X E — verified with the dash dash smoke check shown here, from the manual.
Prefer full control? Clone, make a virtual environment, and install with the G U I and dev extras — about four hundred megabytes, all inside a dot venv. On a Mac, install the Xcode command line tools once so the kernels compile. The G P U extra is N V I D I A only — on Apple Silicon it is a deliberate no-op, since Metal ships through the bundled torch.
Verify in thirty seconds: ask the physics core for a three M E V proton, and the reference particle answers — beta «BETA», gamma «GAMMA» — captured live while building this video. Setup already ran a check like this for you; for certainty, the full test suite takes about three minutes.
Launch with run G U I dot S H. Its first line names the interpreter it picked — the first thing to check if a launch fails. It prefers the repository's dot venv, then U V, then plain python three. H E L I X dot command is the double-clickable Mac launcher, Windows has run G U I dot bat, and any platform can run the Python module directly.
The splash screen holds for about five seconds while Python imports torch and matplotlib. H E L I X stands for Hybrid Envelope multiparticle LInac eXplorer, and the card carries the developer credit and the date the code last changed. First launch is slowest; later ones reuse compiled files.
Four environment knobs. H E L I X PYTHON points the double-click launcher at a specific interpreter. Q T Q P A PLATFORM forces a Qt backend — cocoa on a stubborn Mac. LINAC GEN USE G P U set to c p u skips G P U initialisation. And offscreen runs the whole interface with no window — exactly how this series is filmed.
The main window — nine tabs, walked left to right. Beam defines the particles you inject. Lattice is the machine editor. Matching tunes elements to hit optics targets. Numerics holds the solver settings every run uses. Surrogates trains fast machine-learned models. Param Study scans parameters across runs. Error Study adds alignment and field errors. Failure Study asks what breaks when elements drop out. And Results holds every plot. Around them: title bar, toolbar, status bar. Every tab gets its own deep dive later in the series.
Four menus. File is the project life cycle: new, open and save for lattices and projects, the recent list, the calculation directory, and export to TraceWin or open P M D. Simulate mirrors the two Run buttons, plus backtracking and the multibunch pulse study. Tools opens the optional A I assistant, a Python console, the matrix viewers, and parameter scans. Help: documentation, update checks — with an optional check at startup — and the About box.
The status bar, magnified. The left pill is the run state — READY now, RUNNING while a simulation is in flight. Then the loaded lattice — none yet — the s position, the reference energy, the beam size, and the loss fraction. Transient confirmations appear beside them and fade. Worth knowing in advance: without working C plus plus kernels, HELIX prints exactly this warning at startup — everything still runs, on the slower pure Python path.
The shortcuts: control N, new project. Control O, open lattice. Control S, save. Control R, run envelope. Control shift R, run multi-particle. Control plus and minus rescale every font in the interface — the toolbar spinner tracks them — and control zero resets. F one is contextual help.
Control N opens the New Project wizard. We type a name — my first beam. Location points at a projects folder, and the hint spells out the contract: one folder per project, holding the lattice and a runs output directory, so the whole thing moves as one unit. Then the starting point: blank lattice, import an existing file — watch its row wake as the radio is chosen — or a bundled example. We take the F O D O cell.
The wizard also defends you. Names may use letters, digits, spaces, dots, hyphens and underscores. Type C O N and it refuses — a reserved device name on Windows, rejected on every platform. A trailing dot or space is refused too. The same gate blocks a missing, unwritable, or already-occupied location. Proper name back in, and accept.
One aside — a blank project is not empty. This is the deck it writes: a valid one-drift TraceWin file at one hundred sixty two point five megahertz — a one hundred millimetre drift with a fifteen millimetre aperture — immediately loadable, runnable and editable.
And the import path: by default the chosen file is copied into the project folder, keeping the project portable; untick the box to reference it in place. Bundled examples are always copied — your edits never touch the originals.
O K creates the folder, loads the lattice, and writes the project file — the status bar now counts «NELEM» elements and confirms the save. The project also joins File, Open Recent, which gains a clear entry as the list grows.
The Lattice tab, in four columns: element palette, outline tree, timeline with a type chip strip, and the inspector — with the Sequence listing underneath. The status bar counts «NELEM» elements over «LTOT». A F O D O line — the hello world of accelerator physics. The first quadrupole: fifty millimetres, plus five tesla per metre, twenty millimetre aperture. The next is minus five — defocusing — with two hundred millimetre drifts between, four periods over. Alternating focusing is how every large accelerator holds its beam together.
Press F one with nothing selected and the status bar answers: select a lattice element first. Select a quadrupole and press it again — opened, the quadrupole chapter. This page: the element's parameters and physics, straight from the manual. Every element type has a chapter, and most input fields carry hover tooltips too.
The Beam tab. On the left, the particle: species — proton, deuteron or H minus — kinetic energy, R F frequency and peak current, with derived beta and gamma updating live. We set a proton at one M E V, the deck's three hundred fifty two point two one megahertz, and current zero — space charge off. The middle column is the Twiss grid; in go the matched values for this cell from HELIX's own matcher: alpha x «AX», beta x «BX» millimetres per milliradian; in y, «AY» and «BY». Apply hands the beam to the solvers and regenerates the preview — four genuine density plots of the sampled distribution. The other buttons: redraw the preview, reset the defaults, or import a TraceWin D S T particle file.
Run. On «LTOTMM» millimetres of lattice the envelope solver is done in well under a second — watch the status bar: the endpoint arrives as sigma x «SXEND» millimetres, and the run is saved automatically. While a longer simulation is in flight, the pill reads RUNNING, the red Stop button arms — cancelling at the next element — and the toolbar slider doubles as a progress bar with a live percentage. Then Results: six K P I cards — end sigma x, y and z, emittance growth, transmission and loss. Sigma x and y and the «GROWTH» growth fill in; the rest stay dashed on an envelope run — transmission and loss are particle concepts. Below, a wall of cards, one per quantity, each with a live sparkline; cards fill only when the physics exists. Import Results reloads any saved run, and a click opens the full plot.
The R M S beam size plot, exactly as it opens: show aperture is ticked, so the twenty and thirty millimetre bores frame the picture and the beam is a thin ribbon through the middle — far from where a real machine would scrape. Untick it, and the axes zoom to the physics. Blue is horizontal, green is vertical, the strip above marks each quadrupole — and wherever one plane peaks, the other dips. That alternating ripple is the fingerprint of strong focusing, and you just computed it.
Two more tiles a first run already fills. Transverse Twiss: alpha and beta rippling with the cell's period — the beam size again, in optics language. And energy: kinetic energy dead flat at one M E V, gamma constant — no cavities — while the transmission panel underneath stays empty for an envelope run, for the same reason as the dashed K P I cards.
On disk it is all one folder. Straight after the wizard: the lattice copy and the project file. After the first run, a runs directory has joined them — the H D F five archive and its open P M D companion, saved automatically. The project file records that directory as a relative path, so the folder moves as one unit.
Nudge a quadrupole gradient through the undo-aware edit path, and the amber unsaved pill lights the moment memory differs from disk. Control S writes the lattice — saved, pill out. Save Project does the same for the project side: beam and settings. And closing with unsaved work always prompts first.
Come back tomorrow and HELIX reopens where you left off. This is a genuinely fresh window: on startup it found the last project and restored it — the status bar says so — lattice, beam and settings together. The restore is deliberately quiet; a missing or broken file is skipped, never a popup.
Help, then Documentation, opens the manual — the same one F one deep-links into. The installation chapter closes with the common issues list: the exact error texts you might meet, each with its fix — permission denied on the launcher, a missing Py Q T six, a splash with no main window, the mac O S lib omp clash.
And that is the whole loop: install, verify, launch, create a project, load a lattice, define a matched beam, run, and read the plots — with everything saved and restorable in one folder. Ahead: the full interface tour, every tab in depth, space charge, matching, and the voice assistant. The manual is one keypress away. See you there.