HELIX User Manual¶

HELIX¶

Hybrid Envelope-multiparticle LInac eXplorer

⚡ Quick startload a deck, run, plot — 10 minutes 🧩 Elementsevery card the lattice language knows 🌀 Space charge3-D PIC, kernels, convergence 🎛️ Matchingseven optimisers, matched Twiss 🖥️ GUI workbenchtabs, plots, error studies 🤖 AI copilotvoice, tools, guided tour ✅ Validationbenchmarks against TraceWin 🎲 Error studiesMonte-Carlo, correction

HELIX is an open-source Python toolkit for end-to-end simulation of charged-particle linear accelerators. It combines a TraceWin-compatible lattice language, a fast envelope solver, a multi-particle tracker with a 3-D particle-in-cell space-charge solver, and a complete GUI workbench into one tool.

This manual is the comprehensive reference: every element, every configuration knob, every command, every diagnostic, with worked examples and validated benchmarks.

Choose your track¶

The manual is structured to serve three audiences in parallel:

TraceWin userLinac newcomerHELIX developer

You already know your way around a .dat file and partran output. The fastest entry points:

Quick start — load a .dat, run, plot. 10 minutes.
Migrating from TraceWin — porting checklist, gotchas.
Keyword cheatsheet — every TraceWin keyword ↔ HELIX class on one page.
TraceWin parity — what matches, what's known to differ.

No prior linac experience required, just Python literacy. Recommended path:

Introduction — what is a linac, what does HELIX do.
Coordinates & units — the 6-D phase space we work in.
Basic FODO — your first lattice, end-to-end.
Glossary — every domain term defined.

Extending the code, adding elements, debugging physics.

Data model — Lattice, Beam, ReferenceParticle internals.
Python API — Simulation, Tracker, EnvelopeSolver entry points.
Contributing — coding conventions, test discipline, PR flow.
Physics references — every paper cited by the codebase.

What's in the manual¶

Part	Content
I. Getting Started	Install, quick start, first run
II. Concepts	Coordinates, data model, tracking modes
III. Elements	17 element types, each with TL;DR + tutorial + API ref
IV. Beam	Distributions, Twiss, BeamConfig, file I/O
V. Space charge	Models, PIC, kernels, DC mode, convergence
VI. Running	Python API, `.dat` reference, results, GUI, batch-mode CLI
VII. Matching	SET / ADJUST cards, matching engine, recipes
VIII. Errors	Tolerance studies, alignment, RF jitter
IX. Diagnostics	Recorder, emittances, halo, stripping
X. GUI	Tab-by-tab tour, workflows
XI. Worked examples	9 end-to-end walkthroughs
XII. Validation	TraceWin parity, PIP-II benchmark
XIII. ML Surrogates	Train MLP drop-ins for field maps; GUI / CLI / API
Appendices	References, keyword cheatsheet, glossary, troubleshooting, TraceWin migration, contributing

Conventions used in this manual¶

TL;DR cards

Every element and major-feature chapter starts with a one-paragraph summary card — for readers who already know the territory and just want the HELIX-specific facts.

Tutorials

The middle section of each chapter is a narrative walkthrough. All code blocks are runnable; copy them into a Python REPL or a .py file and they will execute against the current HELIX install.

API reference

The end of each chapter has the Python signature and parameter table — for developers reading code or extending HELIX.

Caveats

Boxed callouts mark known issues, deferred features, or convention differences vs. TraceWin / IMPACT-X / other codes.

Building this manual locally¶

# from repo root
pip install -e ".[docs]"
mkdocs serve --config-file docs/mkdocs.yml
# → http://127.0.0.1:8000/

To regenerate every figure from scratch:

python docs/manual/_build/regen_plots.py

To verify every code snippet still runs:

python docs/manual/_build/verify_snippets.py

HELIX is developed at Fermi National Accelerator Laboratory and collaborating institutions. See Contributing for how to participate.