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
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

The input model

Every subcommand takes an input that is either:

  • a lattice file — .dat (TraceWin) or .madx / .seq (MAD-X); the beam then starts from BeamConfig defaults; 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   >   built-in default

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

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 →