Parameters: Inputs File

This documents how to use ImpactX with an input file (impactx input_file.in).

Tip

If you enjoy AI/LLM/agentic workflows, see our AI (LLM)-Assisted Input File Design section, too.

Tip

Input files use the AMReX ParmParse syntax. A parser) is used for the right-hand-side of all input parameters that consist of one or more integers or floats, so expressions like beam.kin_energy = "2.+1.", beam.lambdaY = beam.lambdaX and/or using user-defined constants are accepted.

Tracking Modes

algo.track (string; default: particles)

Mode that specifies how the beam is tracked:

• particles (default): symplectic particle tracking

• envelope: beam envelope (covariance matrix) tracking, through linearized transport maps

• reference_orbit: only tracking of the reference particle orbit

Note

Our current envelope tracking implements ideal transfer maps, assuming always zero misalignments (translations). Element rotations are handled. Support for translations errors, non-zero envelope means, and feed-down effects in envelope tracking is in development. Until then, translations errors set on elements are silently ignored.

Initial Beam Distributions

beam.npart (int)

Number of weighted simulation particles.

beam.units (string)

Currently, only static is supported.

beam.kin_energy (float; [MeV])

Beam kinetic energy.

beam.charge (float; [C])

Bunch charge.

beam.current (float; [A])

Beam current, used only if algo.space_charge = 2D.

beam.particle (string)

Particle type: electron, positron, proton, or Hminus. For other species, please use the Python API or open an issue.

Species Constants

if (species_name == "electron") {
    qe = -1.0;
    massE = m_e / MeV_inv_c2;
    g_anomaly = 0.00115965218062_prt;
} else if (species_name == "positron") {
    qe = 1.0;
    massE = m_e / MeV_inv_c2;
    g_anomaly = 0.00115965218062_prt;
} else if (species_name == "proton") {
    qe = 1.0;
    massE = m_p / MeV_inv_c2;
    g_anomaly = 1.7928473446_prt;
} else if (species_name == "Hminus") {
    qe = -1.0;
    massE = (m_p + 2.0_prt * m_e) / MeV_inv_c2;  // neglect ~14 eV/c^2 binding energy
    g_anomaly = 1.7928473446_prt;
}

beam.distribution (string)

Indicates the initial distribution type. For additional information, consult the documentation on Beam Distribution Input. For all except the thermal distribution we allow input in two forms (see the parameters below the list of distributions).

The following distributions are available:

• waterbag or waterbag_from_twiss for initial Waterbag distribution.

• kurth6d or kurth6d_from_twiss for initial 6D Kurth distribution.

• gaussian or gaussian_from_twiss for initial 6D Gaussian (normal) distribution.

  Optionally, the user may specify an independent cutoff in each phase plane (x,px), (y,py), and (t,pt). The cut is performed in normalized Courant-Snyder variables corresponding to the user-supplied second moments or Twiss functions. As a result, this is equivalent to a cut corresponding to the (linearized) action in each plane.

  Optional parameters:

  beam.cutX/Y/T (float; [dimensionless]; default: 0)

  Number of sigma at which to cut the distribution in (x,px) / (y,py) / (t,pt); 0 means no cut.

• kvdist or kvdist_from_twiss for initial K-V distribution in the transverse plane.

  The distribution is uniform in t and Gaussian in pt.

• kurth4d or kurth4d_from_twiss for initial 4D Kurth distribution in the transverse plane.

  The distribution is uniform in t and Gaussian in pt.

• semigaussian or semigaussian_from_twiss for initial Semi-Gaussian distribution.

  The distribution is uniform within a cylinder in (x,y,z) and Gaussian in momenta (px,py,pt).

• triangle or triangle_from_twiss a triangle distribution for laser-plasma acceleration related applications.

  A ramped, triangular current profile with a Gaussian energy spread (possibly correlated). The transverse distribution is a 4D waterbag.

• thermal for a 6D stationary thermal or bithermal distribution.

  This distribution type is described, for example in: R. D. Ryne et al., “A Test Suite of Space-Charge Problems for Code Benchmarking”, in Proc. EPAC2004, Lucerne, Switzerland. C. E. Mitchell et al., “ImpactX Modeling of Benchmark Tests for Space Charge Validation”, in Proc. HB2023, Geneva, Switzerland.

  Additional parameters:

  beam.k (float; [1/m])

  External focusing strength.

  beam.kT (float; [dimensionless])

  Temperature of core population \(= < p_x^2 > = < p_y^2 >\), where all momenta are normalized by the reference momentum.

  beam.kT_halo (float; [dimensionless]; default: kT)

  Temperature of halo population.

  beam.normalize (float; [dimensionless])

  Normalizing constant for core population.

  beam.normalize_halo (float; [dimensionless])

  Normalizing constant for halo population.

  beam.halo (float; [dimensionless])

  Fraction of charge in halo.

For all except the thermal distribution, the phase space ellipse is specified in one of two forms.

1. Parameters that describe the phase space ellipse and position-momentum correlations:

   beam.lambdaX/Y/T (float; [m])

   Phase space ellipse intersection with X / Y / T. The T value is normalized by multiplying with the speed of light c.

   beam.lambdaPx/Py/Pt (float; [rad])

   Phase space ellipse intersection with Px / Py / Pt.

   beam.muxpx/muypy/mutpt (float; [dimensionless]; default: 0)

   Correlation X-Px / Y-Py / T-Pt.

2. Courant-Snyder (Twiss) parameters. To enable input via Courant-Snyder (Twiss) parameters, add the suffix from_twiss to the name of the distribution. Use the following parameters to characterize it:

   beam.alphaX/Y/T (float; [dimensionless]; default: 0)

   CS / Twiss \(\alpha\) for X / Y / T.

   beam.betaX/Y/T (float; [m])

   CS / Twiss \(\beta\) for X / Y / T.

   beam.emittX/Y/T (float; [m*rad])

   Geometric (unnormalized) emittance \(\epsilon\) in X / Y / T.

Two additional (optional) sets of input parameters may be provided:

1. Parameters that describe the displacement of the beam centroid from the reference particle in phase space:

   beam.meanX/Y/T (float; [m])

   Mean value of the X / Y / T coordinate.

   beam.meanPx/Py/Pt (float; [rad])

   Mean value of the Px / Py / Pt coordinate.

2. Parameters that describe correlations between (x,pt), (px,pt), (y,pt), and (py,pt), described by a nonzero dispersion:

   beam.dispX/Y (float; [m])

   Beam-based horizontal / vertical dispersion.

   beam.dispPx/Py (float; [dimensionless])

   Derivative of beam-based horizontal / vertical dispersion.

beam.bucket_length (float; [m])

Length of the longitudinal particle domain (e.g., length of the RF bucket in z), optionally provided for the application of particle boundary conditions.

Initial Spin Distributions

The specification of an initial particle spin distribution is optional, and is required only if spin tracking is used. The default distribution type is the von Mises-Fisher distribution, uniquely determined by the input polarization vector. The polarization vector provided by the user must lie within the unit ball.

beam.polarization_x/y/z (float; [dimensionless])

Mean value of the spin vector x / y / z-component.

Lattice Elements

lattice.elements (list of strings; optional, default: no elements)

A list of names (one name per lattice element), in the order that they appear in the lattice.

lattice.periods (int; optional, default: 1)

The number of periods to repeat the lattice.

lattice.reverse (bool; optional, default: false)

Reverse the list of elements in the lattice. If lattice.reverse and lattice.periods both appear, then reverse is applied before periods.

lattice.nslice (int; optional, default: 1)

A positive integer specifying the number of slices used for the application of space charge in all elements; overwritten by the per-element nslice parameter.

<element_name>.type (string)

Indicates the element type for this lattice element. This should be one of the following.

aperture

aperture for a thin collimator element applying a transverse aperture boundary, e.g. for an element <aperture_name>.type = aperture. This requires these additional parameters:

<aperture_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical or rectangular).

<aperture_name>.repeat_x/y (float; [m])

Horizontal / vertical period for repeated aperture masking (inactive by default).

<aperture_name>.shift_odd_x (bool)

For hexagonal/triangular mask patterns: horizontal shift of every 2nd (odd) vertical period by repeat_x / 2. Use alignment offsets dx, dy to move the whole mask as needed.

<aperture_name>.shape (string; default: rectangular)

Shape of the aperture boundary: rectangular (default) or elliptical.

<aperture_name>.action (string; default: transmit)

Action of the aperture domain: transmit (default) or absorb.

<aperture_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<aperture_name>.rotation (float; [degree])

Rotation error in the transverse plane.

beam_monitor

beam_monitor a beam monitor, writing all beam particles at fixed s to openPMD files, e.g. for an element <monitor_name>.type = beam_monitor. If the same element name is used multiple times, then an output series is created with multiple outputs.

<monitor_name>.name (string; default: <monitor_name>)

The output series name to use. By default, output is created under <diag.file_prefix>/openPMD/<monitor_name>.<backend>.

<monitor_name>.backend (string; default: default)

I/O backend for openPMD data dumps. bp4/bp5 is the ADIOS2 I/O library, h5 is the HDF5 format, and json is a simple text format. json only works with serial/single-rank jobs. By default, the first available backend in the order given above is taken.

<monitor_name>.encoding (string; default: g)

openPMD iteration encoding: (v)ariable based, (f)ile based, (g)roup based (default) variable based is an experimental feature with ADIOS2.

<monitor_name>.period_sample_intervals (int; default: 1)

For periodic lattice, only output every Nth period (turn). By default, diagnostics are returned every cycle.

<monitor_name>.nonlinear_lens_invariants (bool; default: false)

Compute and output the invariants H and I within the nonlinear magnetic insert element (see: nonlinear_lens). Invariants associated with the nonlinear magnetic insert described by V. Danilov and S. Nagaitsev, PRSTAB 13, 084002 (2010), Sect. V.A.

<monitor_name>.alpha (float; [dimensionless])

Twiss alpha of the bare linear lattice at the location of output for the nonlinear IOTA invariants H and I. Horizontal and vertical values must be equal.

<monitor_name>.beta (float; [m])

Twiss beta of the bare linear lattice at the location of output for the nonlinear IOTA invariants H and I. Horizontal and vertical values must be equal.

<monitor_name>.tn (float; [dimensionless])

Dimensionless strength of the IOTA nonlinear magnetic insert element used for computing H and I.

<monitor_name>.cn (float; [m^(1/2)])

Scale factor of the IOTA nonlinear magnetic insert element used for computing H and I.

buncher

buncher for a short RF cavity (linear) bunching element, e.g. for an element <buncher_name>.type = buncher. This requires these additional parameters:

<buncher_name>.V (float; [dimensionless])

Normalized voltage drop across the cavity = (maximum voltage drop in Volts) / (speed of light in m/s * magnetic rigidity in T-m).

<buncher_name>.k (float; [1/m])

The RF wavenumber = 2*pi/(RF wavelength in m).

<buncher_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<buncher_name>.rotation (float; [degree])

Rotation error in the transverse plane.

cfbend

cfbend for a combined function bending magnet, e.g. for an element <cfbend_name>.type = cfbend. This requires these additional parameters:

<cfbend_name>.ds (float; [m])

The segment length.

<cfbend_name>.rc (float; [m])

The bend radius.

<cfbend_name>.k (float; [1/m²])

The quadrupole strength = (magnetic field gradient in T/m) / (magnetic rigidity in T-m).

• k > 0 horizontal focusing

• k < 0 horizontal defocusing

<cfbend_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<cfbend_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<cfbend_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<cfbend_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

cfbend_exact

A thick combined-function dipole magnet using the exact relativistic Hamiltonian, including all kinematic nonlinearities. The user must provide arrays containing normal and skew multipole coefficients, which can be specified up to decapole order. The multipole coefficients are defined in the curvilinear coordinate system defined by the nominal reference trajectory. For definitions of the coordinate system and (curvilinear) multipole coefficients we follow:

20. Zolkin, Phys. Rev. Accel. Beams 20, 043501 (2017), DOI:10.1103/PhysRevAccelBeams.20.043501

The coefficients must appear in the following sequence:

dipole, quadrupole, sextupole, octupole, etc…

Particle tracking is performed using symplectic integration based on the Hamiltonian splitting \(H = H_1 + H_2\). Here \(H_1\) is the exact nonlinear Hamiltonian for a sector bend (including the kinematic square root), and \(H_2\) is the term containing the vector potential, which is a superposition of multipole contributions.

The vector potential is obtained from Table XI of the above-cited reference.

This element is defined via <cfbend_exact_name>.type = cfbend_exact and requires these additional parameters:

<cfbend_exact_name>.ds (float; [m])

The segment length.

<cfbend_exact_name>.k_normal (array of float)

Array of normal multipole coefficients (in meters^(-m) OR in T/meters^(m-1) for \(m=1,2,3,...\)).

<cfbend_exact_name>.k_skew (array of float)

Array of skew multipole coefficients (in meters^(-m) OR in T/meters^(m-1) for \(m=1,2,3,...\)).

<cfbend_exact_name>.unit (int; default: 0)

Specification of units for the multipole coefficients. By default, the multipole coefficients are normalized by magnetic rigidity. Use unit=1 to specify using SI units.

<cfbend_exact_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<cfbend_exact_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<cfbend_exact_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<cfbend_exact_name>.int_order (int; default: 2)

The order used for symplectic integration (2, 4, or 6).

<cfbend_exact_name>.mapsteps (int; default: 10)

Number of integration steps per slice used for symplectic integration.

<cfbend_exact_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

constf

constf for a constant focusing element, e.g. for an element <constf_name>.type = constf. This requires these additional parameters:

<constf_name>.ds (float; [m])

The segment length.

<constf_name>.kx (float; [1/m])

The horizontal focusing strength.

<constf_name>.ky (float; [1/m])

The vertical focusing strength.

<constf_name>.kt (float; [1/m])

The longitudinal focusing strength.

<constf_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<constf_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<constf_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<constf_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

dipedge

dipedge for dipole edge focusing. The model here is based on:

11. Hwang and S. Y. Lee, “Dipole fringe field map for compact synchrotrons,” Phys. Rev. Accel. Beams 18, 122401 (2015)

as represented in the explicit, symplectic form provided in:

3. Mitchell and K. Hwang, “Explicit symplectic representations of nonlinear dipole fringe field maps,” in Proc. NAPAC2025, TUP040, Sacramento, CA, 2025

Here, g denotes the magnetic gap, which is a length scale that sets the rate of decay of the fringe field. The values K0 - K6 denote dimensionless field integrals, describing the shape of the fringe field, as defined in eqs. (28-34) of the first reference above. In particular, K2 is the well-known fringe field parameter denoted FINT in MAD-X. The default values of the field integrals K0 - K6 are those given in eq. (52), corresponding to a tanh (i.e. logistic) field profile.

If model = "linear", then the linearized map is used. This model is identical to:

• 11. 12. Brown, SLAC Report No. 75 (1982)

when expanded to first order in g/rc (gap / radius of curvature).

By comparison, note that the MAD-X DIPEDGE element uses as input the half-gap HGAP = g/2, and sets the default value FINT = 0 (while the corresponding default value of K2 is set to 1).

Note that the nonlinear model includes a nonzero horizontal translation (depending on the field integral values) that is present even for a particle that begins on the ideal “hard-edge” reference trajectory.

For a beam, this will result in a centroid offset that will produce centroid oscillations in the downstream beamline. In practice, this can be avoided by aligning the downstream elements with the true horizontal position (after including the effect of the fringe field). To model this correction, we allow two options in the dipedge model:

• the option modify_ref_part = False (default), in which the shift due to the fringe field is applied to each beam particle phase space vector but not to the reference particle phase space vector – this model makes sense if the shift due to the fringe field is not considered in the baseline design, so that downstream elements are aligned with the “idealized” reference trajectory

• the option modify_ref_part = True in which the shift due to the fringe field is applied to the reference particle phase space vector, but not to the beam particle phase space vector – this model makes sense if the shift due to the fringe field is considered as part of the baseline design, so that downstream elements are aligned with the “shifted” reference trajectory

This element is defined via <dipedge_name>.type = dipedge and requires these additional parameters:

<dipedge_name>.psi (float; [rad])

The pole face rotation angle.

<dipedge_name>.rc (float; [m])

The bend radius.

<dipedge_name>.g (float; [m])

The full magnetic gap size.

<dipedge_name>.R (float; [m]; default: 1)

Scale length for the field integrals.

<dipedge_name>.K0 (float; [dimensionless]; default: pi**2/6)

Normalized field integral for fringe field.

<dipedge_name>.K1 (float; [dimensionless]; default: 0)

Normalized field integral for fringe field.

<dipedge_name>.K2 (float; [dimensionless]; default: 1)

Normalized field integral for fringe field (FINT).

<dipedge_name>.K3 (float; [dimensionless]; default: 1/6)

Normalized field integral for fringe field.

<dipedge_name>.K4 (float; [dimensionless]; default: 0)

Normalized field integral for fringe field.

<dipedge_name>.K5 (float; [dimensionless]; default: 0)

Normalized field integral for fringe field.

<dipedge_name>.K6 (float; [dimensionless]; default: 0)

Normalized field integral for fringe field.

<dipedge_name>.model (string; default: linear)

The fringe field model: linear (default) or nonlinear.

<dipedge_name>.location (string; default: entry)

The fringe field edge location: entry (default) or exit.

<dipedge_name>.modify_ref_part (bool; default: false)

Apply fringe field to the reference particle, true or false (default).

<dipedge_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<dipedge_name>.rotation (float; [degree])

Rotation error in the transverse plane.

drift

drift for a free drift, e.g. for an element <drift_name>.type = drift. This requires these additional parameters:

<drift_name>.ds (float; [m])

The segment length.

<drift_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<drift_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<drift_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<drift_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

drift_chromatic

drift_chromatic for a free drift, with chromatic effects included, e.g. for an element <drift_chromatic_name>.type = drift_chromatic. The Hamiltonian is expanded through second order in the transverse variables (x,px,y,py), with the exact pt dependence retained. This requires these additional parameters:

<drift_chromatic_name>.ds (float; [m])

The segment length.

<drift_chromatic_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<drift_chromatic_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<drift_chromatic_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<drift_chromatic_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

drift_exact

drift_exact for a free drift, using the exact nonlinear map, e.g. for an element <drift_exact_name>.type = drift_exact. This requires these additional parameters:

<drift_exact_name>.ds (float; [m])

The segment length.

<drift_exact_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<drift_exact_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<drift_exact_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<drift_exact_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

kicker

kicker for a thin transverse kicker, e.g. for an element <kicker_name>.type = kicker. This requires these additional parameters:

<kicker_name>.xkick/ykick (float; [dimensionless OR T-m])

The horizontal / vertical kick strength.

<kicker_name>.unit (string; default: dimensionless)

Specification of units: dimensionless (default, in units of the magnetic rigidity of the reference particle) or T-m.

<kicker_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<kicker_name>.rotation (float; [degree])

Rotation error in the transverse plane.

line

line a sub-lattice (line) of elements to append to the lattice, e.g. for an element <line_name>.type = line.

<line_name>.elements (list of strings; optional, default: no elements)

A list of names (one name per lattice element), in the order that they appear in the lattice.

<line_name>.reverse (bool; optional, default: false)

Reverse the list of elements in the line before appending to the lattice.

<line_name>.repeat (int; optional, default: 1)

Repeat the line multiple times before appending to the lattice. Note: If <line_name>.reverse and <line_name>.repeat both appear, then reverse is applied before repeat.

linear_map

linear_map for a custom, linear transport matrix.

The matrix elements \(R(i,j)\) are indexed beginning with 1, so that \(i,j=1,2,3,4,5,6\). The transport matrix \(R\) is defaulted to the identity matrix, so only matrix entries that differ from that need to be specified.

The matrix \(R\) multiplies the phase space vector \((x,px,y,py,t,pt)\), where coordinates \((x,y,t)\) have units of m and momenta \((px,py,pt)\) are dimensionless. So, for example, \(R(1,1)\) is dimensionless, and \(R(1,2)\) has units of m.

The internal tracking methods used by ImpactX are symplectic. However, if a user-defined linear map \(R\) is provided, it is up to the user to ensure that the matrix \(R\) is symplectic. Otherwise, this condition may be violated.

This element is defined via <linear_map_name>.type = linear_map and requires these additional parameters:

<linear_map_name>.R(i,j) (float)

Matrix entries: a 1-indexed, 6x6, linear transport map to multiply with the phase space vector \((x,p_x,y,p_y,t,p_t)\).

<linear_map_name>.ds (float; [m]; default: 0)

Length associated with a user-defined linear element.

<linear_map_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<linear_map_name>.rotation (float; [degree])

Rotation error in the transverse plane.

multipole

multipole for a thin multipole element, e.g. for an element <multipole_name>.type = multipole. This requires these additional parameters:

<multipole_name>.multipole (int; [dimensionless])

Order of multipole: (m = 1) dipole, (m = 2) quadrupole, (m = 3) sextupole, etc.

<multipole_name>.k_normal (float)

Integrated normal multipole coefficient (MAD-X convention), in meters^(-m+1) = ds * 1/(magnetic rigidity in T-m) * (derivative of order \(m-1\) of \(B_y\) with respect to \(x\)).

<multipole_name>.k_skew (float)

Integrated skew multipole strength (MAD-X convention), in 1/meters^(-m+1).

<multipole_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<multipole_name>.rotation (float; [degree])

Rotation error in the transverse plane.

multipole_exact

multipole_exact for a thick multipole magnet using the exact relativistic Hamiltonian, including all kinematic nonlinearities. The user must provide arrays containing normal and skew multipole coefficients, which can be specified up to arbitrarily high order. The fields are assumed to be uniform along the longitudinal beamline coordinate (hard-edge model). The coefficients must appear in the following sequence:

dipole, quadrupole, sextupole, octupole, etc…

(Note: Dipole coefficients are currently ignored, and will be supported in a separate combined-function dipole element.)

Particle tracking is performed using symplectic integration based on the Hamiltonian splitting \(H = H_1 + H_2\). Here \(H_1\) is the nonlinear Hamiltonian for a drift (including the kinematic square root), and \(H_2\) is the term containing the vector potential, which is a superposition of multipole contributions.

This element is defined via <multipole_exact_name>.type = multipole_exact and requires these additional parameters:

<multipole_exact_name>.ds (float; [m])

The segment length.

<multipole_exact_name>.k_normal (array of float)

Array of normal multipole coefficients (in meters^(-m) OR in T/meters^(m-1) for \(m=1,2,3,...\)).

<multipole_exact_name>.k_skew (array of float)

Array of skew multipole coefficients (in meters^(-m) OR in T/meters^(m-1) for \(m=1,2,3,...\)).

<multipole_exact_name>.unit (int; default: 0)

Specification of units for the multipole coefficients. By default, the multipole coefficients are normalized by magnetic rigidity. Use unit=1 to specify using SI units.

<multipole_exact_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<multipole_exact_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<multipole_exact_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<multipole_exact_name>.int_order (int; default: 2)

The order used for symplectic integration (2, 4, or 6).

<multipole_exact_name>.mapsteps (int; default: 10)

Number of integration steps per slice used for symplectic integration.

<multipole_exact_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

nonlinear_lens

nonlinear_lens for a thin IOTA nonlinear lens element, e.g. for an element <nonlinear_lens_name>.type = nonlinear_lens. This requires these additional parameters:

<nonlinear_lens_name>.knll (float; [m])

Integrated strength of the lens segment (MAD-X convention) = dimensionless lens strength * c parameter**2 * length / Twiss beta.

<nonlinear_lens_name>.cnll (float; [m])

Distance of the singularities from the origin (MAD-X convention) = c parameter * sqrt(Twiss beta).

<nonlinear_lens_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<nonlinear_lens_name>.rotation (float; [degree])

Rotation error in the transverse plane.

plane_xyrotation

plane_xyrotation for a rotation in the x-y plane (i.e., about the reference velocity vector), e.g. for an element <plane_xyrotation_name>.type = plane_xyrotation. This requires these additional parameters:

<plane_xyrotation_name>.angle (float; [degree])

Nominal angle of rotation.

<plane_xyrotation_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<plane_xyrotation_name>.rotation (float; [degree])

Rotation error in the transverse plane.

plasma_lens_chromatic

plasma_lens_chromatic for an active cylindrically-symmetric plasma lens, with chromatic effects included, e.g. for an element <plasma_lens_chromatic_name>.type = plasma_lens_chromatic. The Hamiltonian is expanded through second order in the transverse variables \((x,p_x,y,p_y)\), with the exact \(p_t\) dependence retained. This requires these additional parameters:

<plasma_lens_chromatic_name>.ds (float; [m])

The segment length.

<plasma_lens_chromatic_name>.k (float; [1/m² OR T/m])

The plasma lens focusing strength = (azimuthal magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if unit = 0,

OR = azimuthal magnetic field gradient in T/m - if unit = 1.

<plasma_lens_chromatic_name>.unit (int; default: 0)

Specification of units.

<plasma_lens_chromatic_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<plasma_lens_chromatic_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<plasma_lens_chromatic_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<plasma_lens_chromatic_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

polygon_aperture

polygon_aperture for a thin collimator element applying a transverse polygon aperture boundary defined by \((x,y)\) coordinates and optional radius below which all particles are transmitted, e.g. for an element <polygon_aperture_name>.type = polygon_aperture. The vertices must define a closed curve and be ordered in the counter-clockwise direction. The first and last vertices must be identical. These parameters define the element:

<polygon_aperture_name>.vertices_x/y (array of float; [m])

Array of horizontal / vertical locations of aperture vertices.

<polygon_aperture_name>.min_radius2 (float; [m²]; default: 0)

Optional minimum radius-squared of a circle fully inscribed within the polygon. Particles with radius-squared less than this value are transmitted by the aperture and the polygon calculation is skipped.

<polygon_aperture_name>.repeat_x/y (float; [m])

Horizontal / vertical period for repeated aperture masking (inactive by default).

<polygon_aperture_name>.shift_odd_x (bool)

For hexagonal/triangular mask patterns: horizontal shift of every 2nd (odd) vertical period by repeat_x / 2. Use alignment offsets dx, dy to move the whole mask as needed.

<polygon_aperture_name>.action (string; default: transmit)

Action of the aperture domain: transmit (default) or absorb.

<polygon_aperture_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<polygon_aperture_name>.rotation (float; [degree])

Rotation error in the transverse plane.

prot

prot for an exact pole-face rotation in the x-z plane, e.g. for an element <prot_name>.type = prot. This requires these additional parameters:

<prot_name>.phi_in (float; [degree])

Angle of the reference particle with respect to the longitudinal (z) axis in the original frame.

<prot_name>.phi_out (float; [degree])

Angle of the reference particle with respect to the longitudinal (z) axis in the rotated frame.

quad

quad for a quadrupole, e.g. for an element <quad_name>.type = quad. This requires these additional parameters:

<quad_name>.ds (float; [m])

The segment length.

<quad_name>.k (float; [1/m²])

The quadrupole strength = (magnetic field gradient in T/m) / (magnetic rigidity in T-m).

• k > 0 horizontal focusing

• k < 0 horizontal defocusing

<quad_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<quad_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<quad_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<quad_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

quad_chromatic

quad_chromatic for a Quadrupole magnet, with chromatic effects included, e.g. for an element <quad_chromatic_name>.type = quad_chromatic. The Hamiltonian is expanded through second order in the transverse variables \((x,p_x,y,p_y)\), with the exact \(p_t\) dependence retained. This requires these additional parameters:

<quad_chromatic_name>.ds (float; [m])

The segment length.

<quad_chromatic_name>.k (float; [1/m² OR T/m])

The quadrupole strength = (magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if unit = 0,

OR = magnetic field gradient in T/m - if unit = 1.

• k > 0 horizontal focusing

• k < 0 horizontal defocusing

<quad_chromatic_name>.unit (int; default: 0)

Specification of units.

<quad_chromatic_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<quad_chromatic_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<quad_chromatic_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<quad_chromatic_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

quad_exact

quad_exact for a Quadrupole magnet using the exact relativistic Hamiltonian, including all kinematic nonlinearities. Particle tracking is performed using symplectic integration based on the Hamiltonian splitting \(H = H_1 + H_2\). Here \(H_1\) is the Hamiltonian for a linear quadrupole (containing all terms quadratic in the phase space variables), and \(H_2\) is the remainder (including the kinematic square root). This suggested splitting appears for example in:

• 4. 12. Bruhwiler et al, in Proc. of EPAC 98, pp. 1171-1173 (1998).

• 5. Forest, J. Phys. A: Math. Gen. 39, 5321 (2006).

This element is defined via <quad_exact_name>.type = quad_exact and requires these additional parameters:

<quad_exact_name>.ds (float; [m])

The segment length.

<quad_exact_name>.k (float; [1/m² OR T/m])

The quadrupole strength = (magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if unit = 0,

OR = magnetic field gradient in T/m - if unit = 1.

• k > 0 horizontal focusing

• k < 0 horizontal defocusing

<quad_exact_name>.unit (int; default: 0)

Specification of units.

<quad_exact_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<quad_exact_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<quad_exact_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<quad_exact_name>.int_order (int; default: 2)

The order used for symplectic integration (2, 4, or 6).

<quad_exact_name>.mapsteps (int; default: 10)

Number of integration steps per slice used for symplectic integration.

<quad_exact_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

quadrupole_softedge

quadrupole_softedge for a soft-edge quadrupole. See Models of Soft-Edge Elements.

The units used for the on-axis quadrupole gradient are the same as those used for the quadrupole strength k in the element Quad. For example, if the values used to describe the on-axis profile (as specified in cos_coefficients, sin_coefficients) attain a peak on-axis value of 1, then the parameter gscale, which multiplies this profile, specifies the peak value of the quadrupole field gradient on-axis, divided by the magnetic rigidity. In this case, gscale has units of inverse meters squared.

This element is defined via <quadrupole_softedge_name>.type = quadrupole_softedge and requires these additional parameters:

<quadrupole_softedge_name>.ds (float; [m])

The segment length.

<quadrupole_softedge_name>.gscale (float; [1/m²])

Scaling factor for on-axis magnetic field gradient.

<quadrupole_softedge_name>.cos_coefficients (array of float; optional)

Cos coefficients in Fourier expansion of the on-axis field gradient. Default is a tanh fringe field model from MaryLie 3.0.

<quadrupole_softedge_name>.sin_coefficients (array of float; optional)

Sin coefficients in Fourier expansion of the on-axis field gradient. Default is a tanh fringe field model from MaryLie 3.0.

<quadrupole_softedge_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<quadrupole_softedge_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<quadrupole_softedge_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<quadrupole_softedge_name>.mapsteps (int; default: 10)

Number of integration steps per slice used for map and reference particle push in applied fields.

<quadrupole_softedge_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

quadedge

quadedge for quadrupole edge focusing. This is a nonlinear symplectic map (derived from a third-order Lie generator), representing the effect of quadrupole entry or exit fringe fields in the hard-edge limit. This is an explicit symplectification of the Lie map that appears in eq (28) of: E. Forest and J. Milutinovic, Nucl. Instrum. and Methods in Phys. Res. A 269, 474-482 (1988). This element is defined via <quadedge_name>.type = quadedge and requires these additional parameters:

<quadedge_name>.k (float; [1/m² OR T/m])

The quadrupole strength = (magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if unit = 0,

OR = magnetic field gradient in T/m - if unit = 1.

• k > 0 horizontal focusing

• k < 0 horizontal defocusing

<quadedge_name>.unit (int; default: 0)

Specification of units.

<quadedge_name>.flag (string; default: entry)

Specification of edge location: entry (default) or exit.

<quadedge_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<quadedge_name>.rotation (float; [degree])

Rotation error in the transverse plane.

rfcavity

rfcavity a radiofrequency cavity. See Models of Soft-Edge Elements.

The units used for the on-axis longitudinal electric field are described in the documentation of escale below. For example, if the values used to describe the on-axis electric field (as specified in cos_coefficients, sin_coefficients, or gradient_on_axis) attain a peak on-axis value of 1, then the parameter escale, which multiplies this profile, specifies the peak value of the longitudinal electric field gradient on-axis, divided by particle rest energy. In this case, escale has units of inverse meters.

This element is defined via <rfcavity_name>.type = rfcavity and requires these additional parameters:

<rfcavity_name>.ds (float; [m])

The segment length.

<rfcavity_name>.escale (float; [1/m])

Scaling factor for on-axis RF electric field = (peak on-axis electric field Ez in MV/m) / (particle rest energy in MeV).

<rfcavity_name>.freq (float; [Hz])

RF frequency.

<rfcavity_name>.phase (float; [degree])

RF driven phase.

<rfcavity_name>.cos_coefficients (array of float; optional)

Cosine coefficients in Fourier expansion of on-axis electric field Ez. Default is a 9-cell TESLA superconducting cavity model from DOI:10.1103/PhysRevSTAB.3.092001.

<rfcavity_name>.sin_coefficients (array of float; optional)

Sine coefficients in Fourier expansion of on-axis electric field Ez. Default is a 9-cell TESLA superconducting cavity model from DOI:10.1103/PhysRevSTAB.3.092001.

<rfcavity_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<rfcavity_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<rfcavity_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<rfcavity_name>.mapsteps (int; default: 10)

Number of integration steps per slice used for map and reference particle push in applied fields.

<rfcavity_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

sbend

sbend for a bending magnet, e.g. for an element <sbend_name>.type = sbend. This requires these additional parameters:

<sbend_name>.ds (float; [m])

The segment length.

<sbend_name>.rc (float; [m])

The bend radius.

<sbend_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<sbend_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<sbend_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<sbend_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

sbend_exact

sbend_exact for a bending magnet using the exact nonlinear map for the bend body. The map corresponds to the map described in: D. L. Bruhwiler et al., in Proc. of EPAC 98, pp. 1171-1173 (1998), E. Forest et al., Part. Accel. 45, pp. 65-94 (1994). The model consists of a uniform bending field B_y with a hard edge. Pole faces are normal to the entry and exit velocity of the reference particle. This element is defined via <sbend_exact_name>.type = sbend_exact and requires these additional parameters:

<sbend_exact_name>.ds (float; [m])

The segment length.

<sbend_exact_name>.phi (float; [degree])

The bend angle.

<sbend_exact_name>.B (float; [T]; default: 0)

The bend magnetic field; when B = 0 (default), the reference bending radius is defined by r0 = length / (angle in rad), corresponding to a magnetic field of B = rigidity / r0; otherwise the reference bending radius is defined by r0 = rigidity / B.

<sbend_exact_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<sbend_exact_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<sbend_exact_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<sbend_exact_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

shortrf

shortrf for a short RF cavity element, e.g. for an element <shortrf_name>.type = shortrf. This requires these additional parameters:

<shortrf_name>.V (float; [dimensionless])

Normalized voltage drop across the cavity = (maximum energy gain in MeV) / (particle rest energy in MeV).

<shortrf_name>.freq (float; [Hz])

The RF frequency.

<shortrf_name>.phase (float; [degree])

The synchronous RF phase.

• phase = 0: maximum energy gain (on-crest)

• phase = -90 deg: zero energy gain for bunching

• phase = 90 deg: zero energy gain for debunching

<shortrf_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<shortrf_name>.rotation (float; [degree])

Rotation error in the transverse plane.

solenoid

solenoid for an ideal hard-edge solenoid magnet, e.g. for an element <solenoid_name>.type = solenoid. This requires these additional parameters:

<solenoid_name>.ds (float; [m])

The segment length.

<solenoid_name>.ks (float; [1/m])

Solenoid strength in m^(-1) (MADX convention) = (magnetic field Bz in T) / (rigidity in T-m).

<solenoid_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<solenoid_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<solenoid_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<solenoid_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

solenoid_softedge

solenoid_softedge for a soft-edge solenoid. See Models of Soft-Edge Elements.

The units used for the on-axis longitudinal magnetic field data are determined by the parameter unit. For example, if the values used to describe the on-axis profile (as specified in cos_coefficients, sin_coefficients, or field_on_axis) attain a peak on-axis value of 1, then the parameter bscale, which multiplies this profile, specifies the peak value of the longitudinal magnetic field gradient on-axis. If unit=0, this is normalized by the magnetic rigidity.

This element is defined via <solenoid_softedge_name>.type = solenoid_softedge and requires these additional parameters:

<solenoid_softedge_name>.ds (float; [m])

The segment length.

<solenoid_softedge_name>.bscale (float; [1/m])

Scaling factor for on-axis longitudinal magnetic field = (magnetic field Bz in T) / (magnetic rigidity in T-m) - if unit = 0,

OR = magnetic field Bz in T - if unit = 1.

<solenoid_softedge_name>.cos_coefficients (array of float; optional)

Cos coefficients in Fourier expansion of the on-axis magnetic field Bz. Default is a thin-shell model from DOI:10.1016/J.NIMA.2022.166706.

<solenoid_softedge_name>.sin_coefficients (array of float; optional)

Sin coefficients in Fourier expansion of the on-axis magnetic field Bz. Default is a thin-shell model from DOI:10.1016/J.NIMA.2022.166706.

<solenoid_softedge_name>.unit (int; default: 0)

Specification of units.

<solenoid_softedge_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<solenoid_softedge_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<solenoid_softedge_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<solenoid_softedge_name>.mapsteps (int; default: 10)

Number of integration steps per slice used for map and reference particle push in applied fields.

<solenoid_softedge_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

source

source for a particle source, e.g. for an element <source_name>.type = source. Typically at the beginning of a beam line.

Currently, this only supports openPMD files from our beam_monitor.

In MPI-parallel runs, reading the particles in the source file is distributed over all MPI ranks: each of the \(N\) ranks reads a different contiguous chunk of \(1/N\)-th of the particles, independent of their position. When ImpactX needs to sort particles spatially, it will redistribute them over MPI ranks automatically during tracking.

<source_name>.distribution (string)

Distribution type of particles in the source. Currently, only openPMD is supported.

<source_name>.openpmd_path (string)

Path to the openPMD series.

<source_name>.active_once (bool; default: true)

Inject particles only for the first lattice period.

spin_map

spin_map for a custom, user-specified spin map that acts on the spin 3-vector \((s_x,s_y,s_z)\).

Spin maps are specified in the Lie-algebraic form:

\[\vec{s}_f = M(\zeta)\vec{s}_i,\quad\quad M(\zeta)=e^{v\cdot L}e^{A\Delta\zeta\cdot L}.\]

Here \(v\) is a 3-vector that defines the axis and angle of rotation at the phase space design point, and \(A\) is a 3x6 matrix that defines the spin-orbit coupling for particles not on the design orbit. Also, \(\Delta\zeta=(x,p_x,y,p_y,t,p_t)\) denotes the 6-vector of phase space variables as deviations from the design orbit. The quantities \(L_x\), \(L_y\), and \(L_z\) are standard 3x3 matrices that define a basis for the Lie algebra \(so(3)\).

The vector components \(v(i)\) and the matrix elements \(A(i,j)\) are indexed beginning with 1, so that \(i=1,2,3\) and \(j=1,2,3,4,5,6\). The vector \(v\) and the matrix \(A\) are defaulted to zero, so only entries that differ from zero need to be specified.

The matrix \(A\) multiplies the phase space vector \((x,p_x,y,p_y,t,p_t)\), where coordinates \((x,y,t)\) have units of m and momenta \((p_x,p_y,p_t)\) are dimensionless. The three components output are dimensionless. So, for example, \(A(1,1)\) has units of 1/m, and \(A(1,2)\) is dimensionless. All three components of \(v\) are dimensionless.

This element is defined via <spin_map_name>.type = spin_map and requires these additional parameters:

<spin_map_name>.v(i) (float)

Vector entries: a 1-indexed, 3x1, axis-angle vector that defines the spin rotation at the phase space design point.

<spin_map_name>.A(i,j) (float)

Matrix entries: a 1-indexed, 3x6, spin-orbit coupling matrix to multiply with the phase space vector \((x,p_x,y,p_y,t,p_t)\) that defines the spin rotation for off-design particles.

<spin_map_name>.ds (float; [m]; default: 0)

Length associated with a user-defined spin map element.

<spin_map_name>.dx/dy (float; [m]; default: 0)

Horizontal / vertical translation error (not used, defaults to 0).

<spin_map_name>.rotation (float; [degree]; default: 0)

Rotation error in the transverse plane (not used, defaults to 0).

tapered_pl

tapered_pl for a thin nonlinear plasma lens with transverse (horizontal) taper.

\[B_x = g \left( y + \frac{xy}{D_x} \right), \quad \quad B_y = -g \left(x + \frac{x^2 + y^2}{2 D_x} \right)\]

where \(g\) is the (linear) field gradient in T/m and \(D_x\) is the targeted horizontal dispersion in m.

This element is defined via <tapered_pl_name>.type = tapered_pl and requires these additional parameters:

<tapered_pl_name>.k (float; [1/m OR T])

The integrated plasma lens focusing strength = (length in m) * (magnetic field gradient \(g\) in T/m) / (magnetic rigidity in T-m) - if unit = 0,

OR = (length in m) * (magnetic field gradient \(g\) in T/m) - if unit = 1.

<tapered_pl_name>.unit (int; default: 0)

Specification of units.

<tapered_pl_name>.taper (float; [1/m])

Horizontal taper parameter = 1 / (target horizontal dispersion \(D_x\) in m).

<tapered_pl_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<tapered_pl_name>.rotation (float; [degree])

Rotation error in the transverse plane.

thin_dipole

thin_dipole for a thin dipole element, e.g. for an element <thin_dipole_name>.type = thin_dipole. This requires these additional parameters:

<thin_dipole_name>.theta (float; [degree])

Dipole bend angle.

<thin_dipole_name>.rc (float; [m])

Effective radius of curvature.

<thin_dipole_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<thin_dipole_name>.rotation (float; [degree])

Rotation error in the transverse plane.

uniform_acc_chromatic

uniform_acc_chromatic for a region of uniform acceleration, with chromatic effects included, e.g. for an element <uniform_acc_chromatic_name>.type = uniform_acc_chromatic. The Hamiltonian is expanded through second order in the transverse variables (x,px,y,py), with the exact pt dependence retained. This requires these additional parameters:

<uniform_acc_chromatic_name>.ds (float; [m])

The segment length.

<uniform_acc_chromatic_name>.ez (float; [1/m])

The electric field strength = (particle charge in C * electric field Ez in V/m) / (particle mass in kg * (speed of light in m/s)^2).

<uniform_acc_chromatic_name>.bz (float; [1/m])

The magnetic field strength = (particle charge in C * magnetic field Bz in T) / (particle mass in kg * speed of light in m/s).

<uniform_acc_chromatic_name>.dx/dy (float; [m])

Horizontal / vertical translation error.

<uniform_acc_chromatic_name>.rotation (float; [degree])

Rotation error in the transverse plane.

<uniform_acc_chromatic_name>.aperture_x/y (float; [m])

Horizontal / vertical half-aperture (elliptical).

<uniform_acc_chromatic_name>.nslice (int; default: 1)

Number of slices used for the application of space charge.

Collective Effects

Space Charge

Space charge kicks are applied in between slices of thick lattice elements. See there nslice option on lattice elements for slicing.

algo.space_charge (string; optional, default: false)

The physical model of space charge used.

ImpactX uses an AMReX grid of boxes to organize and parallelize space charge simulation domain. These boxes also contain a field mesh, if space charge calculations are enabled.

Options:

• false (default): space charge effects are not calculated.

• 2D: Space charge forces are computed in the plane (x,y) transverse to the reference particle velocity, assuming the beam is long and unbunched.

• 2p5D: Space charge forces are computed in the plane (x,y) transverse to the reference particle velocity, while the transverse space charge kicks are weighted by the longitudinal line density determined by charge deposition (2.5D model). Longitudinal space charge kicks are determined by the derivative of the line charge density.

  This model is supported only in particle tracking mode (when algo.track = particles).

  This model supports the following sub-options:

  algo.space_charge.num_longitudinal_bins (int; default: 100)

  The number of bins for longitudinal line density deposition.

  algo.space_charge.apply_longitudinal_kick (bool; default: true)

  Enable or disable the longitudinal space charge kick.

• 3D: Space charge forces are computed in three dimensions, assuming the beam is bunched.

  When running in envelope mode (when algo.track = envelope), this model currently assumes that <xy> = <yt> = <tx> = 0.

• Gauss3D: Calculate 3D space charge forces as if the beam was a Gaussian distribution.

• Gauss2p5D: Calculate 2.5D space charge forces as if the beam was a transverse Gaussian distribution.

  These models are supported only in particle tracking mode (when algo.track = particles). Ref.: J. Qiang, “Two-and-a-half dimensional symplectic space-charge solver”, LBNL Report Number: LBNL-2001674 (2025). (This reference describes both 3D and 2.5D models.)

  This model supports the following sub-option:

  algo.space_charge.gauss_nint (int; default: 101)

  Number of steps for computing the integrals (Eqs. 45-47 in the above paper).

  algo.space_charge.gauss_taylor_delta (float; default: 0.01)

  Initial integral region to avoid divergence of integrand at 0.

  algo.space_charge.gauss_long_scale (float; default: in-situ \(1.103 \cdot \gamma \cdot \sigma_z\))

  Longitudinal space charge scale for the Gauss2p5D space charge model. This is an approximation that only influences the longitudinal momentum (pt) kick. If not set, it defaults to \(1.103 \cdot \gamma \cdot \sigma_z\), estimated in-situ from the current reduced beam characteristics (with \(\sigma_z\) the RMS bunch length), which is a typical value when comparing to a 3D model. This value minimizes the L2-norm of the error in the on-axis field Ez in the case of a long 3D Gaussian bunch. In a perfectly conducting pipe with a long bunch, where the bunch length in the rest frame is significantly larger than the pipe radius, it is recommended to set the longitudinal scale length to the pipe radius in the input file.

  algo.space_charge.gauss_charge_z_bins (int; default: 129)

  Number of bins for longitudinal line density deposition.

amr.n_cell (3 integers; optional, default: 1 blocking_factor per MPI process)

The number of grid points along each direction (on the coarsest level).

amr.max_level (int; default: 0)

When using mesh refinement, the number of refinement levels that will be used.

Use 0 in order to disable mesh refinement.

amr.ref_ratio (int; default: 2)

When using mesh refinement, this is the refinement ratio per level. With this option, all directions are fined by the same ratio.

amr.ref_ratio_vect (3 integers)

Set per refined level (for x,y,z). When using mesh refinement, this can be used to set the refinement ratio per direction and level, relative to the previous level.

Example: for three levels, a value of 2 2 4 8 8 16 refines the first level by 2-fold in x and y and 4-fold in z compared to the coarsest level (level 0/mother grid); compared to the first level, the second level is refined 8-fold in x and y and 16-fold in z.

Note

Particles that move outside the simulation domain are removed.

geometry.dynamic_size (bool; optional, default: true)

Use dynamic (true) resizing of the field mesh, via geometry.prob_relative, or static sizing (false), via geometry.prob_lo / geometry.prob_hi.

geometry.prob_relative (array of float; [dimensionless]; optional, default: 3.0 1.0 1.0 ...)

A positive float array with amr.max_level entries. By default, we dynamically extract the minimum and maximum of the particle positions in the beam. The field mesh spans, per direction, multiple times the maximum physical extent of beam particles, as given by this factor. The beam minimum and maximum extent are symmetrically padded by the mesh. For instance, 1.2 means the mesh will span 10% above and 10% below the beam; 1.0 means the beam is exactly covered with the mesh.

geometry.prob_lo/hi (3 floats; [m]; optional)

Required if geometry.dynamic_size is false. The extent of the full simulation domain relative to the reference particle position. This can be used to explicitly size the simulation box and ignore geometry.prob_relative.

This box is rectangular, and thus its extent is given here by the coordinates of the lower corner (geometry.prob_lo) and upper corner (geometry.prob_hi). The first axis of the coordinates is x and the last is z.

algo.particle_shape (int)

Allowed values: 1, 2, or 3. The order of the shape factors (splines) for the macro-particles along all spatial directions: 1 for linear, 2 for quadratic, 3 for cubic. Low-order shape factors result in faster simulations, but may lead to more noisy results. High-order shape factors are computationally more expensive, but may increase the overall accuracy of the results. For production runs it is generally safer to use high-order shape factors, such as cubic order.

algo.poisson_solver (string; optional, default: fft)

The numerical solver to solve the Poisson equation when calculating space charge effects. Currently, the multigrid solver supports only 3D space charge. The fft solver supports either 2D or 3D space charge. An additional 2.5D solver will be added in the near future.

Options:

• fft: Poisson’s equation is solved using an Integrated Green Function method (which requires FFT calculations).

  See these references for more details Qiang et al. (2006) (+ Erratum). This requires the compilation flag -DImpactX_FFT=ON. If mesh refinement (MR) is enabled, this FFT solver is used only on the coarsest level and a multi-grid solver is used on refined levels. The boundary conditions are assumed to be open.

• multigrid: Poisson’s equation is solved using an iterative multigrid (MLMG) solver.

  See the AMReX documentation for details of the MLMG solver. Field boundaries for MLMG space charge calculation are located at the outer ends of the field mesh. For the MLMG solver, we assume Dirichlet boundary conditions with zero potential (a mirror charge). Thus, to emulate open boundaries, consider adding enough vacuum padding to the beam.

Multigrid-specific numerical options:

algo.mlmg_relative_tolerance (float; optional, default: 1.e-7 (DP) / 1.e-4 (SP))

The relative precision with which the electrostatic space-charge fields should be calculated. More specifically, the space-charge fields are computed with an iterative Multi-Level Multi-Grid (MLMG) solver. This solver can fail to reach the default precision within a reasonable time.

algo.mlmg_absolute_tolerance (float; optional, default: 0)

A value of 0 means: ignored. The absolute tolerance with which the space-charge fields should be calculated in units of V/m^2. More specifically, the acceptable residual with which the solution can be considered converged. In general this should be left as the default, but in cases where the simulation state changes very little between steps it can occur that the initial guess for the MLMG solver is so close to the converged value that it fails to improve that solution sufficiently to reach the algo.mlmg_relative_tolerance value.

algo.mlmg_max_iters (int; optional, default: 100)

Maximum number of iterations used for MLMG solver for space-charge fields calculation. In case if MLMG converges but fails to reach the desired self_fields_required_precision, this parameter may be increased.

algo.mlmg_verbosity (int; optional, default: 1)

The verbosity used for MLMG solver for space-charge fields calculation. Currently MLMG solver looks for verbosity levels from 0-5. A higher number results in more verbose output.

Coherent Synchrotron Radiation (CSR)

CSR effects are included in the simulation for bend lattice elements such as Sbend and CFbend. These effects are critical in accurately modeling the wakefields generated due to the interaction of particles with the synchrotron radiation field generated by the beam during bending. Currently, this is the 1D ultrarelativistic steady-state wakefield model (eq. 19 of E. L. Saldin et al., NIMA 398, p. 373-394 (1997), DOI:10.1016/S0168-9002(97)00822-X).

algo.csr (bool; optional, default: false)

Whether to calculate CSR effects. CSR calculations involve several steps, including charge deposition, wakefield generation, and convolution, all of which are handled within the CSR bending process.

algo.csr_bins (int; optional, default: 150)

The number of bins used for the CSR calculations along the longitudinal direction. Increasing the number of bins can lead to more accurate wakefield resolution at the cost of higher computational expense.

Note

CSR effects are only calculated for lattice elements that include bending, such as Sbend, ExactSbend and CFbend.

CSR effects require the compilation flag -DImpactX_FFT=ON.

Incoherent Synchrotron Radiation (ISR)

ISR effects are included in the simulation for bend lattice elements such as Sbend and CFbend, and are especially important for electron or positron bunches at high energy. The effects of ISR include radiation reaction due to the stochastic emission of synchrotron radiation, resulting in mean energy loss and quantum excitation of the bunch. The model is based on:

F. Niel et al., Phys. Rev. E 97, 043209 (2018), DOI:10.1103/PhysRevE.97.043209

However, a Taylor expansion is used to evaluate the dependence on the quantum parameter \(\chi\). When algo.isr_order = 1, the model is equivalent to that described in:

J. M. Jowett, “Introductory Statistical Mechanics for Electron Storage Rings”, AIP Conf. Proc. 153, 864-970 (1987), DOI:10.1063/1.36374

algo.isr (bool; optional, default: false)

Whether to calculate ISR effects.

algo.isr_order (int; optional, default: 1)

The number of terms retained in the Taylor series for the functions \(g(\chi)\) and \(h(\chi)\) appearing in equations (25) and (41) describing quantum effects.

algo.isr_on_ref_part (bool; optional, default: false)

Flag specifying whether ISR is to be applied to the reference particle. When algo.isr_on_ref_part = false, the reference particle does not lose energy due to radiation, and the mean energy of the beam particles will decrease. This option is natural if the lattice optics, magnet settings, etc. are chosen without accounting for radiative energy loss. When algo.isr_on_ref_part = true, the reference particle does lose energy due to radiation, and little centroid evolution is expected in the beam particles. This option is natural if the lattice optics, magnet settings, etc. are chosen to account for radiative energy loss.

Note

ISR effects are only calculated for lattice elements that include bending, such as Sbend, ExactSbend and CFbend.

Particle Boundary Condition

The application of a non-trivial boundary condition for particles is currently supported only in the longitudinal direction (the local direction of motion as defined by the reference particle). For systems involving bunches that are long relative to the local size of the RF bucket, it is often necessary to capture the effect of particle slippage between adjacent buckets. To handle this effectively without tracking multiple bunches, a periodic particle boundary condition can be applied.

algo.particle_bc (string; optional, default: open)

The type of particle boundary condition to be applied to the longitudinal coordinate, based on the value of parameter beam.bucket_length. Options:

• open (default): no action is applied at the boundary.

• periodic: each particle’s longitudinal coordinate is treated modulo the value beam.bucket_length (phase wrapping).

• absorbing: a particle whose longitudinal coordinate falls outside the boundary is declared lost.

• reflecting: a particle whose longitudinal coordinate crosses the boundary is reflected about the boundary, with reversed longitudinal momentum.

  Note

  The implementation works through linear order in the phase space variables. If you have the need for a more precise implementation of reflecting boundaries, please open an issue.

Spin Tracking

Spin tracking is performed by updating the particle spin 3-vector in the presence of each element’s electromagnetic fields, using methods based on the Thomas-BMT equation. By construction, all spin tracking methods rely on pushing particles using spin maps that lie in SO(3). The algorithm implemented for each element is consistent with the algorithm used for pushing the phase space vector.

Currently, the implementation of spin tracking is a work in progress, and this feature is not yet supported.

algo.spin (bool; optional, default: false)

Whether to track particle spin.

Spin tracking uses the gyromagnetic anomaly of the reference particle, which is set together with the particle species (see beam.particle).

Math parser and user-defined constants

The AMReX parser is used for the right-hand-side of all input parameters that consist of one or more integers or floats. Thus, expressions like beam.alphaY = beam.alphaX and/or using user-defined constants or simple math operations are accepted.

Note that when multiple values are expected, the expressions are space delimited. For integer input values, the expressions are evaluated as real numbers and the final result rounded to the nearest integer. See this section of the AMReX documentation for a complete list of functions supported by the math parser.

ImpactX constants

ImpactX will provide a few pre-defined constants, that can be used for any parameter that consists of one or more floats.

q_e	elementary charge
m_e	electron mass
m_p	proton mass
m_u	unified atomic mass unit (Dalton)
epsilon0	vacuum permittivity
mu0	vacuum permeability
clight	speed of light
pi	math constant pi

User-defined constants

Users can define their own constants in the input file. These constants can be used for any parameter that consists of one or more integers or floats. User-defined constant names can contain only letters, numbers and the character _. The name of each constant has to begin with a letter. The following names are used by ImpactX, and cannot be used as user-defined constants: x, y, z, t, X, Y, Z, T. The values of the constants can include the predefined ImpactX constants listed above as well as other user-defined constants. For example:

• my_constants.my_alpha = 3.0

• my_constants.my_beta = 12.e-6

• my_constants.abc = 1.23e10

Coordinates

Besides, for profiles that depend on spatial coordinates, the parser will interpret some variables as spatial coordinates. These are specified in the input parameter, i.e., field_function(x,y,z) or field_function(X,Y,T).

The parser reads python-style expressions between double quotes, for instance "a0*x**2 * (1-y*1.e2) * (x>0)" is a valid expression where a0 is a user-defined constant (see above) and x and y are spatial coordinates. The names are case sensitive. The factor (x>0) is 1 where x>0 and 0 where x<=0. It allows the user to define functions by intervals. Alternatively the expression above can be written as if(x>0, a0*x**2 * (1-y*1.e2), 0).

Diagnostics and output

diag.enable (bool; optional, default: true)

Enable or disable diagnostics generally. Disabling this is mostly used for benchmarking.

This option is ignored for the openPMD output elements (remove them from the lattice to disable).

diag.slice_step_diagnostics (bool; optional, default: false)

By default, diagnostics are computed and written at the beginning and end of the simulation. Enabling this flag will write diagnostics at every step and slice step.

diag.file_prefix (string; optional, default: diags)

Root directory for diagnostic output. By default, diagnostics are written in the folder diags/.

Set to an empty string or . to write diagnostics in the current working directory.

If a directory at diag.file_prefix already exists when a simulation starts, ImpactX renames it to <diag.file_prefix>.old.<suffix> to preserve prior results. This is skipped when diag.file_prefix resolves to the current working directory, the root directory, or an ancestor of the current working directory; in those cases new output is written alongside existing files.

diag.file_min_digits (int; optional, default: 6)

The minimum number of digits used for the step number appended to the diagnostic file names.

diag.backend (string; default: default)

Diagnostics for particles lost in apertures, stored as <diag.file_prefix>/openPMD/particles_lost.* at the end of the simulation. See the beam_monitor element for backend values.

diag.eigenemittances (bool; optional, default: false)

If this flag is enabled, the 3 eigenemittances of the 6D beam distribution are computed and written as diagnostics. This flag is disabled by default to reduce computational cost.

Checkpoints and restart

Note

Future version of ImpactX will support checkpoints/restart. This is not yet implemented.

Intervals parser

Note

TODO :-)

ImpactX can parse time step interval expressions of the form start:stop:period, e.g. 1:2:3, 4::, 5:6, :, ::10. A comma is used as a separator between groups of intervals, which we call slices. The resulting time steps are the union set of all given slices. White spaces are ignored. A single slice can have 0, 1 or 2 colons :, just as numpy slices, but with inclusive upper bound for stop.

• For 0 colon the given value is the period

• For 1 colon the given string is of the type start:stop

• For 2 colons the given string is of the type start:stop:period

Any value that is not given is set to default. Default is 0 for the start, std::numeric_limits<int>::max() for the stop and 1 for the period. For the 1 and 2 colon syntax, actually having values in the string is optional (this means that ::5, 100 ::10 and 100 : are all valid syntaxes).

All values can be expressions that will be parsed in the same way as other integer input parameters.

Examples

• something_intervals = 50 -> do something at timesteps 0, 50, 100, 150, etc. (equivalent to something_intervals = ::50)

• something_intervals = 300:600:100 -> do something at timesteps 300, 400, 500 and 600.

• something_intervals = 300::50 -> do something at timesteps 300, 350, 400, 450, etc.

• something_intervals = 105:108,205:208 -> do something at timesteps 105, 106, 107, 108, 205, 206, 207 and 208. (equivalent to something_intervals = 105 : 108 : , 205 : 208 :)

• something_intervals = : or something_intervals = :: -> do something at every timestep.

• something_intervals = 167:167,253:253,275:425:50 do something at timesteps 167, 253, 275, 325, 375 and 425.

This is essentially the python slicing syntax except that the stop is inclusive (0:100 contains 100) and that no colon means that the given value is the period.

Note that if a given period is zero or negative, the corresponding slice is disregarded. For example, something_intervals = -1 deactivates something and something_intervals = ::-1,100:1000:25 is equivalent to something_intervals = 100:1000:25.

Overall simulation parameters

amrex.abort_on_out_of_gpu_memory (0 or 1; default: 1 (true))

When running on GPUs, memory that does not fit on the device will be automatically swapped to host memory when this option is set to 0. This will cause severe performance drops. Note that even with this set to 1 ImpactX will not catch all out-of-memory events yet when operating close to maximum device memory. Please also see the documentation in AMReX.

amrex.the_arena_is_managed (0 or 1; default: 0 (false))

When running on GPUs, device memory that is accessed from the host will automatically be transferred with managed memory. This is useful for convenience during development, but has sometimes severe performance and memory footprint implications if relied on (and sometimes vendor bugs). For all regular ImpactX operations, we therefore do explicit memory transfers without the need for managed memory. Please also see the documentation in AMReX.

amrex.omp_threads (system, nosmt or positive int; default: nosmt)

An integer number can be set in lieu of the OMP_NUM_THREADS environment variable to control the number of OpenMP threads to use for the OMP compute backend on CPUs. By default, we use the nosmt option, which overwrites the OpenMP default of spawning one thread per logical CPU core, and instead only spawns a number of threads equal to the number of physical CPU cores on the machine. If set, the environment variable OMP_NUM_THREADS takes precedence over system and nosmt, but not over integer numbers set in this option.

amrex.abort_on_unused_inputs (0 or 1; default: 0 (false))

When set to 1, this option causes the simulation to fail after its completion if there were unused parameters. It is mainly intended for continuous integration and automated testing to check that all tests and inputs are adapted to API changes.

impactx.always_warn_immediately (0 or 1; default: 0 (false))

If set to 1, ImpactX immediately prints every warning message as soon as it is generated. It is mainly intended for debug purposes, in case a simulation crashes before a global warning report can be printed.

impactx.abort_on_warning_threshold (string; optional)

Allowed values: low, medium or high. Optional threshold to abort as soon as a warning is raised. If the threshold is set, warning messages with priority greater than or equal to the threshold trigger an immediate abort. It is mainly intended for debug purposes, and is best used with impactx.always_warn_immediately = 1. For more information on the warning logger, see this section of the WarpX documentation.

impactx.verbose (int; optional, default: 1)

Controls how much information is printed to the terminal, when running ImpactX. Use 0 for silent; higher is more verbose.