A bonus appendix to the HELIX tutorial series. The thirteen episodes showed you how: every tab, every run, every plot. This one shows you where to look things up. HELIX ships with a written manual, a complete reference site: every element, every configuration knob, every command and every diagnostic, with worked examples and validated benchmarks. A few minutes here will save you hours later, because the manual answers the questions the videos raise.
This is the front door. The manual is published on the project's GitHub Pages, and it builds locally from the repository with M K docs, which is exactly how these frames were captured, offline. Below the hero, eight tiles route to the most-used parts: Quick start, Elements, Space charge, Matching, the G U I workbench, the A I assistant, Validation, and Error studies. Under the tiles, two paragraphs say what HELIX is and what the manual promises: the reference for every element, knob, command and diagnostic.
Scroll down and the manual asks who you are. Three tracks, side by side in one tabbed block. TraceWin users get the quick start, the migration checklist, the keyword cheatsheet and the parity page, in that order. Linac newcomers get the introduction, coordinates and units, a first F O D O lattice, and the glossary. HELIX developers get the data model, the Python A P I, the contributing guide and the physics references. One manual, three doors.
Three navigation systems, always on screen. The top row of tabs is the parts of the book. Read it left to right once: Home, Tutorials, Getting Started, Concepts, Elements, Beam, Space charge, Running, Matching, Errors and tolerances, Diagnostics, G U I, Worked examples, Validation, M L Surrogates, A I Assistant, Multibunch, and Appendices. Click Elements and the left column becomes the chapters of that part, one per element. The right column is the table of contents of the open page, and its highlight follows you as you scroll. Scroll back up, even slightly, and a Back to top pill appears; one click returns you to the head of the page.
Search is the fastest route to anything: element names, keywords, error directives, algorithm names. Type hofmann and the results rank as you type: six matching documents, the Diagnostics chapter on the Hofmann stability chart first, then the Results tab page that hosts it. The index is compiled into the site itself, so this works offline, straight off your disk. The share icon beside the query gives a link that reopens this exact search. Pick the top result, and every occurrence of the term is highlighted on the page you land on.
Every element in the lattice language has its own chapter, and the Elements overview is the catalogue: pick by use case, from field-free propagation to overlapping field maps, and each row links to its chapter. Open Quadrupole and you meet the anatomy every element chapter shares. First, a T L D R card for people who already know the physics: the TraceWin keyword beside the HELIX class, units side by side, and the sign conventions. Then a tutorial for newcomers, with a complete runnable example, here a single F O D O cell, and a copy button in the corner of the code block. Then the A P I reference for developers: the full constructor signature with every default, a parameter table, the properties, and the source file with its line number. And a See also list to the neighbouring chapters.
The manual's callouts are a small language of their own, and the front page defines it. Boxes titled T L D R cards open every element and major-feature chapter. Tutorial boxes mark the narrative walkthroughs, and promise that every code block is runnable against the current install. A P I reference boxes hold the Python signatures and parameter tables. And the Caveats box is the important one: it marks known issues, deferred features, and convention differences against TraceWin, IMPACT-X and other codes.
Here is a caveat in the wild, from the migration appendix. The longitudinal alpha flips sign relative to TraceWin, because HELIX's phase coordinate runs the opposite way. The box says exactly what to do, negate alpha z while beta z and the emittance carry over, gives the worked example, and describes the symptom you would see if you got it wrong. When the manual warns you, it names the exact difference.
Beyond reference pages, the manual has cookbooks. The matching recipes are ordered from the smallest possible problem upward. Recipe one matches a single quadrupole. Two: emittance minimisation with C M A E S and a least-squares polish. Three: sequential scan with a seed-exit threshold. Four: the multi-particle cost solver for physics-accurate matching. Five: cancellation, where clicking Stop keeps the best solution found so far. Six: parallel C M A E S on a heavy lattice. Seven: guarding against beam loss with the min transmission card. Each recipe is written three times, as Python, as a command line, and as the G U I workflow the Matching tab episode showed. And recipe eight is a decision table: which optimiser fits which problem shape.
Before trusting any code, read its validation chapter. The TraceWin parity page opens with a coverage matrix, element by element: parser, tracker, and how closely each matched, from bit-exact linear matrices down to the R F Q cell rows at the bottom. Then the error directives, with what each one does and does not do. Then the validation residuals at five milliamps with space charge, section by section, and the end of machine values printed as numbers rather than adjectives: sigma x 3.69 millimetres in HELIX against 3.55 in TraceWin, sigma y 4.71 against 4.94. And finally, what's known to differ: the sigma phi reporting convention, a factor of about four because HELIX reports at the local cavity frequency rather than the bunch frequency, and a P I C kernel calibration offset of about three percent. Each one explained, not hidden.
Parity is one of four validation chapters. PIP two validation is the full linac against TraceWin partran, the reference benchmark. Known limitations is the list of what HELIX deliberately does not do, what is parsed but not honoured, and the calibration biases. And the convergence checklist is a printable one-pager to run through before you report any result as converged.
The appendices are the working toolbox. Appendix B is the page TraceWin users keep open: every keyword the parser recognises, grouped as header and control cards, element cards, diagnostics, error directives, matching directives, the recognised no-op markers, the HELIX extensions hidden in comments, and, just as important, the section headed Deferred, not honoured: the cards the parser reads but the physics ignores. Appendix E is the porting checklist: what just works, conventions and units, what is different, and what you must set outside the dot dat file. Appendix C is the glossary, every domain term defined, A to Z. And Appendix D is troubleshooting: install failures, sigmas that blow up at the L E B T entrance, the three percent and factor-of-four TraceWin disagreements, hangs, blank windows. Paste your error message into search, or scan this page.
The assistant episode showed it live; this chapter is its written contract. Backends: cloud by A P I key, the keyless subscription path through the Claude agent S D K, or fully local. What it can do, and what it will refuse. The audit trail and replay. Using your Claude subscription through the M C P server. The G U I section, the longest on the page, documents the panel control by control. And the voice section: offline, push to talk, with the natural kokoro voice as an option. The voice reading this sentence is that same one.
The loop closes on the manual's own Tutorials page. All thirteen episodes as cards, each with its poster frame, a one-paragraph summary, the running time, and a link to its caption file. The videos stream from the project's tutorials release on GitHub, where they and the captions can also be downloaded. Watch an episode for the tour, then read the matching chapter for the numbers.
Two palettes. The dark slate you have been looking at matches the workbench. One click on the header icon switches to light, and one more switches back. The choice is remembered by your browser, and it works offline like everything else here.
Manual, videos and repository are one project, and each links to the other two. Every page carries the repository link in its header. At the foot of the front page, how to build the manual yourself: pip install the docs extras, then M K docs serve, and it appears on a local port. One more script regenerates every figure, and another re-runs every code snippet in the manual. If you change HELIX, this is how the manual keeps up.
That is the tour. Search first; the index knows every keyword. Trust the validation pages, and keep Appendix B open beside your dot dat files. The video series is complete, but the manual is where the project keeps talking: new features land there, and on the tutorials page, as they ship. Thank you for watching.