CLI: run

One headless tracking simulation. Loads a lattice or .lgproj project, applies overrides, runs an envelope / multi-particle / matrix simulation, and writes the results.

python -m linac_gen run <input> [options]

<input> is a .dat / .madx / .seq / .lat / .flat / .mad8 / .lte lattice (or, with the optional lattix translator, a .bmad / .jl / .pals.yaml one — see Importing Bmad, SciBmad and PALS lattices) or a .lgproj project.

Options

Mode & output

Option	Argument	Default	Meaning
--mode	envelope | mp | matrix	envelope	solver mode (see below)
--out	DIR	.	output directory
--format	hdf5 | openpmd | partran	hdf5	results file format
--write-dst	flag	off	also write the final distribution as a TraceWin .dst (multi-particle only)

Beam overrides

Option	Argument	Meaning
--tracewin-ini [INI]	flag or path	bare lattice only: start from beam 1 of the deck's TraceWin .ini options file (<deck>.ini next to it, or INI) — the overrides below still apply on top (an --energy/--freq/--species override is warned about: emit_z/beta_z are not re-derived); a .lgproj input refuses it, its saved beam wins. Importing TraceWin project settings
--energy	MeV	kinetic energy
--current	mA	beam current
--freq	MHz	beam frequency
--n-particles	int	macroparticle count
--species	proton | deuteron | H-	particle species
--beam	NAME=VALUE	any other BeamConfig field — repeatable (e.g. --beam emit_nx=0.3 --beam beta_x=4)

Element overrides

Option	Argument	Meaning
--set	ELEM.attr=VALUE	set one element parameter — repeatable. ELEM is a name or @N index

Convergence / PIC overrides

Option	Argument	Meaning
--nx	int	PIC grid size (nx=ny=nz)
--grid-extent	float	PIC grid extent, in σ
--step1	float	integration steps per metre
--step2	float	space-charge kicks per metre
--drift-single-push	on | off	push a field-free drift once when no space charge, sub-step diagnostics or phase fold sits between its sub-steps, losses located analytically (default: project value, else on; off = the sub-stepped walk of HELIX ≤ 1.9.1)
--rfq-solver	auto | cells | time_domain	RFQ model for mp runs: auto (time_domain whenever that solver can run the lattice and beam, else cells, with a notice saying why), cells (one RFQ_CELL at a time along z) or time_domain (the whole RFQ tracked in time through the 3-D field of its vanes: the RFQ_GEOM vane file, else vanes built from the RFQ_CELL cards; a case it cannot run is an error — see Time-domain RFQ solver); default: project value (rfq_solver), else auto
--rfq-td-steps	int ≥ 8	time-domain RFQ: leapfrog steps per RF period (default: project value rfq_td_steps_per_period, else 48)
--rfq-stats	accelerated | all	time-domain RFQ: accelerated (default) leaves the particles that leave the RFQ unaccelerated out of the statistics (they stay in the beam and the transmission); all counts every surviving particle (default: project value rfq_stats_accelerated, else accelerated)
--kernel	cic | tsc	PIC deposit kernel
--sc-method	name | list	a named space-charge method (list prints them and exits); naming the project's own method keeps the project's settings, another method starts from its own defaults
--backend	auto | cpu | gpu	compute backend
--sc	NAME=VALUE	any other SpaceChargeConfig field — repeatable
--env-solver	matrix | sacherer	envelope solver kind (default matrix)

Misc

Option	Argument	Default	Meaning
--seed	int	42	RNG seed for the particle distribution
--threads	N | all	$HELIX_THREADS, else $OMP_NUM_THREADS, else all	CPU threads for the space-charge FFT, field maps and charge deposition; results are identical for any number (CPU threads)
--action-scan	flag	off	record the halo action scan (particles outside the n·ε_rms ellipses, per step and plane) into the results file's action_scan/ group — mp mode and the hdf5 format only (otherwise ignored with a warning). The project's record_action_scan setting is not read: pass the flag
--fail-under-transmission	%	—	exit non-zero if final transmission falls below this
-q, --quiet	flag	off	suppress the run report

The three modes

• envelope — rms Σ-matrix tracking. Fast, no macroparticles. Writes the per-step envelope (σ, emittance, Twiss).
• mp — multi-particle PIC tracking. Builds a beam of n_particles macroparticles; space charge is included when the beam has current. Adds transmission, halo, snapshots; --write-dst dumps the final distribution.
• matrix — linear transfer-matrix tracking. Writes the 6×6 transfer matrix and the per-plane periodic Twiss to a text file.

Output files

The results file is named <input-stem>_results.<ext> in --out:

--format	Extension	Notes
hdf5	.h5	HELIX-native HDF5
openpmd	.opmd.h5	openPMD-beamphysics 1.1 — portable interchange
partran	.txt	TraceWin-style tab-separated ASCII

--write-dst additionally writes <input-stem>_final.dst, with the particles still in the beam and the current they carry, I × N_alive / N_launched, as TraceWin's own export after losses does. --mode matrix writes <input-stem>_matrix.txt.

Examples

# Envelope run of a project, results into ./out/
python -m linac_gen run cell.lgproj --mode envelope --out out/

# Multi-particle run; also dump the final .dst; fail if transmission < 90 %
python -m linac_gen run cell.lgproj --mode mp --n-particles 20000 \
    --write-dst --fail-under-transmission 90 --out out/

# Bare lattice — every parameter from the command line
python -m linac_gen run cell.dat --mode mp \
    --energy 800 --species H- --current 5 \
    --beam emit_nx=0.25 --set QF.gradient=8.5 \
    --nx 64 --kernel tsc --out out/

# Linear transfer matrix + Twiss
python -m linac_gen run cell.lgproj --mode matrix --out out/

# openPMD output
python -m linac_gen run cell.lgproj --format openpmd --out out/

Runnable versions are in examples/batch_mode/01_run_envelope … 05_run_output_formats.

Cross-references

• Batch-mode overview — the input / override model.
• CLI: scan — sweep a parameter instead of one run.
• Reading results — the output file formats.

← Batch-mode overview · Continue to CLI: scan →