Skip to content

Batch-mode CLI — overview

HELIX runs headless from the shell via python -m linac_gen. No GUI, no hand-written driver scripts — the CLI drives the very same Simulation / EnvelopeSolver / scan-pool engines the GUI uses, so a batch run is bit-identical to the equivalent GUI run.

python -m linac_gen <subcommand> …
Subcommand Purpose Page
run one headless simulation (envelope / mp / matrix) CLI: run
scan sweep one or more variables → CSV summary CLI: scan
batch a multi-run campaign from a JSON job file CLI: batch
study parameter study — per-run folders, resume, oat/zip/grid/random/lhs strategies CLI: study
twiss matched Twiss — whole-lattice or FODO-cell input match CLI: twiss
backtrack backward tracking — reconstruct an upstream distribution from a downstream state CLI: backtrack
mo multi-objective design — Pareto front over ADJUST knobs Multi-objective
failures element failure impact + recovery → CSV Failure studies
match the matcher — delegates to python -m linac_gen.matching Matching CLI
assist AI assistant chat (optional — local or cloud LLM; the rest of HELIX never needs it) Assistant
export write the lattice in another code's format — MAD-X SEQUENCE, the exact inverse of the MAD-X importer Exporting to MAD-X
orm orbit-response matrix — compare a measurement with the model, LOCO-style calibration of quads, trims and BPM gains, recalibrated-deck export CLI: orm
twini TraceWin project options file (.ini) — the converted beam, a decode report, or a .lgproj for the deck Importing TraceWin project settings

The input model

Every subcommand takes an input that is either:

  • a lattice file — .dat (TraceWin), .madx / .seq (MAD-X), .lat / .flat (MAD8), .lte (Elegant), or — through the optional lattix translator — .bmad (Bmad), .jl / .scibmad (SciBmad) and .pals.yaml / .pals.json (PALS); the beam then starts from BeamConfig defaults — or, with --tracewin-ini, from beam 1 of the deck's TraceWin .ini options file (Importing TraceWin project settings); or
  • a .lgproj project — beam and convergence settings are read from the file (it is the same project the GUI saves).

Command-line options then override individual scalars on top of that — the "configure once, override per run" model. The resolution priority for any setting is:

   command-line option   >   project (.lgproj) value  |  --tracewin-ini beam   >   built-in default

--tracewin-ini is for a bare lattice only: a project's saved beam always wins and the flag is refused with a .lgproj. An energy, frequency or species override on top of an .ini beam is warned about — emit_z/beta_z were converted at the .ini values and are not re-derived.

This is what makes parameter scans and campaigns possible: keep a project file as the baseline, and vary only what changes from the shell.

Three kinds of override

Mechanism Targets Example
Beam any BeamConfig field --current 5 · --beam emit_nx=0.3
Element any element parameter --set QF.gradient=8.5 · --set @12.angle=10
Convergence / PIC step density, grid, kernel, backend --nx 64 · --step1 100 · --sc green_kind=point (the single-push drift option comes from the project file's drift_single_push key)

An element selector is NAME.attr (the element whose .name is NAME) or @N.attr (the N-th element, 1-based, over lattice.elements).

Output

run writes a results file per the --format flag; scan and batch write a CSV summary. All formats are the same writers the GUI uses — see Reading results.

Exit codes

The process exit code lets shell scripts and CI branch on the outcome:

Code Meaning
0 success
1 the run / scan / batch failed, or a --fail-under-transmission threshold was breached
2 bad arguments, or a missing input file

Worked examples

The folder examples/batch_mode/ holds one self-contained, runnable case per feature (01_run_envelope … 09_batch), each with a commented run.sh. Run any of them from the repository root:

sh examples/batch_mode/01_run_envelope/run.sh

Cross-references

← From the GUI · Continue to CLI: run →