Multipole

This module describes the PASS general multipole element Multipole, used to simulate the motion of charged particles in an arbitrary-order multipole magnet. Unlike single-order elements such as the quadrupole, sextupole, and octupole, the multipole uses knl / ksl arrays to simultaneously support arbitrary-order (including mixed-order) multipole components, suitable for field error injection, combined multipole elements, higher-order multipoles, and other scenarios.

The PASS multipole supports both thick element (length > 0) and thin lens (length = 0) modes. The thick element uses the exact drift-kick-drift (DKD-exact) symplectic integration scheme, supporting both uniform (2nd-order) and yoshida4 (4th-order) symplectic integrators. The kick uses Horner nested evaluation.

Registration name: multipole
Key features:
- Supports arbitrary-order multipole components (knl / ksl arrays, maximum order determined by array length)
- Supports normal components (knl) and skew components (ksl) and their combinations
- Supports thin lens mode (length = 0, applies only a multipole kick)
- Supports thick lens mode (length > 0, DKD-exact symplectic integration)
- Supports uniform (2nd-order leapfrog) and yoshida4 (4th-order Yoshida composition) integrators
- Horner nested evaluation, vectorized implementation, no per-particle branching
- Zero field (all knl / ksl components zero) automatically degenerates to a pure drift
- Supports aperture check
- Single-order degeneration is particle-by-particle consistent with quadrupole/sextupole/octupole

The fields below configure PASS.para.schema.elements.MultipoleItem. The key in Sequence.add(name, item) supplies the element name; it is not a configuration-model field.

Interface Parameters

Python configuration field	JSON key	Type	Unit	Default	Description
`s`	`S (m)`	`float`	m	`Required`	Longitudinal position of the element exit or zero-length action point.
`length`	`Length (m)`	`float`	m	`0.0`	Magnet length, \(= 0\) for thin lens
`knl`	`KiL`	`list[float]`	—	`[]`	Normal component integrated strength array \([K_{0L}, K_{1L}, \ldots]\)
`ksl`	`KiSL`	`list[float]`	—	`[]`	Skew component integrated strength array \([K_{0sL}, K_{1sL}, \ldots]\)
`fringe`	`FRINGE`	`int`	—	`0`	MAD-X bit selector; 2 enables intrinsic multipole end maps and 4 enables quadrupole F1/F2.
`frngmax`	`FRNGMAX`	`int`	—	`2`	Maximum included pole order: 2 = quadrupole, 3 = sextupole, 4 = octupole.
`kill_ent_fringe`	`KILL_ENT_FRINGE`	`bool`	—	`False`	Disable all enabled fringe maps at the physical entrance.
`kill_exi_fringe`	`KILL_EXI_FRINGE`	`bool`	—	`False`	Disable all enabled fringe maps at the physical exit.
`num_slices`	`Num slices`	`int`	1	`1`	Number of slices for thick lens
`integrator`	`Integrator`	`str`	—	`'adaptive'`	Integrator, options: `adaptive` (default `uniform`), `uniform`, `yoshida4`
`aperture_type`	`Aperture type`	`str`	—	`'off'`	Aperture type
`aperture_value`	`Aperture value`	`list`	m / rad	`[]`	Aperture parameter values

Note

The knl and ksl arrays do not need to have the same length; the shorter array is automatically zero-padded. The maximum order \(N\) is determined by the longer array length (\(N = \max(\text{len}) - 1\)).

For time-dependent normal and skew strengths, set is_ramping=True and ramping_file="magnet_ramp.tfs" (JSON: Is ramping and Ramping file). See Magnet ramping for the TFS columns, units and entrance sampling. Each nonempty bunch samples once at entry; its strengths remain fixed over the entire element. Runtime nominal strengths retain the last executed bunch entrance values, with field errors kept separate. The same page documents update_strengths.

Fringe maps are applied once at each physical end, using the enabled total normal/skew strengths. See Physical entrance and exit fringe maps for the selector, order cutoff, zero-length restrictions and MAD-X/PTC comparison conventions.

Usage Examples

Thin Lens Multipole (Field Error Injection)

{
    "MPE1": {
        "S (m)": 10.0,
        "Command": "multipole",
        "Length (m)": 0.0,
        "KiL": [0.0, 0.0, 0.001, 0.0005],
        "KiSL": [0.0, 0.0, 0.0003, 0.0001],
        "Aperture type": "off"
    }
}

Zero-length multipole with 2nd and 3rd order field error components. Used to simulate the effect of magnet installation errors or manufacturing errors on the beam.

Thick Lens Multipole (Combined Element)

{
    "MP1": {
        "S (m)": 20.0,
        "Command": "multipole",
        "Length (m)": 0.5,
        "KiL": [0.0, 0.3, 5.0, 200.0],
        "KiSL": [0.0, 0.0, 0.0, 0.0],
        "Num slices": 5,
        "Integrator": "yoshida4",
        "Aperture type": "off"
    }
}

Thick lens combined multipole with simultaneous quadrupole, sextupole, and octupole normal components, 5 slices, 4th-order symplectic integration.

Single-Order Multipole (Equivalent to Octupole)

{
    "MP2": {
        "S (m)": 30.0,
        "Command": "multipole",
        "Length (m)": 0.0,
        "KiL": [0.0, 0.0, 0.0, 500.0],
        "KiSL": [0.0, 0.0, 0.0, 200.0],
        "Aperture type": "off"
    }
}

Contains only the 3rd-order component (knl=[0,0,0,500], ksl=[0,0,0,200]), equivalent to a normal+skew octupole thin lens. Particle-by-particle consistent with the Octupole element.

Higher-Order Multipole (Decapole)

{
    "MP3": {
        "S (m)": 40.0,
        "Command": "multipole",
        "Length (m)": 0.0,
        "KiL": [0.0, 0.0, 0.0, 0.0, 10000.0],
        "KiSL": [0.0, 0.0, 0.0, 0.0, 0.0],
        "Aperture type": "off"
    }
}

4th-order multipole (decapole), knl=[0,0,0,0,10000]. Dedicated elements only support up to octupole (3rd order); the multipole supports arbitrary order.

Coordinate Convention

Use the continuous longitudinal coordinate in Longitudinal coordinate and reference time. \(T_b\) is the ideal reference particle passage time at this position, not a measured bunch-centroid time. The local-map symbols \(\beta_0\) and \(P_0\) refer to the current bunch reference. \(p_x=P_x/P_0\) is normalized momentum, not a trajectory slope.

PASS uses normalized curvilinear coordinates. The six-dimensional phase-space variables are \((x, p_x, y, p_y, z, \delta)\):

Variable	Symbol	Definition
`x`	\(x\)	Horizontal offset (relative to the reference orbit)
`px`	\(p_x\)	Normalized horizontal momentum, \(p_x = P_x / P_0\)
`y`	\(y\)	Vertical offset
`py`	\(p_y\)	Normalized vertical momentum, \(p_y = P_y / P_0\)
`z`	\(\zeta\)	Longitudinal coordinate, \(z=\zeta=\beta_b c(T_b-t_i)\)
`dp`	\(\delta\)	Relative momentum deviation, \(\delta = P / P_0 - 1\)

where \(P_0\) is the reference particle momentum, \(\beta_0 = v_0 / c\) is the reference particle normalized velocity, \(s\) is the arc length along the reference orbit, and \(t\) is time.

The longitudinal momentum component is defined as:

\[p_z = \sqrt{(1+\delta)^2 - p_x^2 - p_y^2}\]

Charge-to-mass ratio factor:

\[\chi = \frac{q}{q_0} \cdot \frac{m_0}{m}\]

For a beam of identical particle species, \(\chi = 1\).

Multipole Field and Normalized Strength

The magnetic field of a general multipole magnet is expanded as a Taylor series in the transverse plane. In complex notation:

\[B_y + i B_x = \frac{P_0}{q_0} \sum_{n=0}^{N} \frac{K_n}{n!} (x + i y)^n\]

where \(K_n\) is the \(n\)-th order normalized multipole strength (unit \(\text{m}^{-n-1}\)), \(N\) is the maximum order, and \(1/n!\) is the natural coefficient of the Taylor expansion.

Expanding the first few orders:

Order \(n\)	\(n!\)	Element Type	Field Expression
0	1	Dipole	\(B_y + i B_x = \frac{P_0}{q_0} K_0\)
1	1	Quadrupole	\(B_y + i B_x = \frac{P_0}{q_0} K_1 (x + i y)\)
2	2	Sextupole	\(B_y + i B_x = \frac{P_0}{q_0} \frac{K_2}{2} (x + i y)^2\)
3	6	Octupole	\(B_y + i B_x = \frac{P_0}{q_0} \frac{K_3}{6} (x + i y)^3\)

The normalized integrated strength is defined as:

\[K_{nL} = K_n \cdot L, \qquad K_{nsL} = K_{ns} \cdot L\]

where \(L\) is the magnet length, \(K_{nL}\) is the normal component, and \(K_{nsL}\) is the skew component. In PASS, the user specifies \([K_{0L}, K_{1L}, K_{2L}, \ldots]\) through the knl array and \([K_{0sL}, K_{1sL}, K_{2sL}, \ldots]\) through the ksl array.

Note

knl and ksl contain integrated multipole strengths without factorial division. The field evaluation includes \(1/n!\) internally.

Overall Tracking Flow

Depending on the magnet length, the multipole has two tracking modes:

Thin lens mode (\(L = 0\))

====== Thin lens (length = 0) ======

Single multipole kick Kick(knl, ksl)
[Position unchanged, momentum jump only]

Thick lens mode (\(L > 0\))

====== Thick lens (length > 0) ======

Slice 1 → Slice 2 → ... → Slice N
(Each slice: Drift(ds/2) → Kick(ds) → Drift(ds/2))

where ds = L / N
knl_eff = kn * ds, ksl_eff = ks * ds

If all knl/ksl components are zero: degenerates to a single exact drift Drift(L)

The complete map is:

Thin lens:

\[\mathcal{M}_{\text{thin}} = \text{Kick}(K_{nL}, K_{nsL})\]

Thick lens (N slices):

\[\mathcal{M}_{\text{thick}} = \left[\mathcal{M}_{\text{DKD}}(\Delta s)\right]^N\]

where the DKD map for each slice is:

\[\mathcal{M}_{\text{DKD}}(\Delta s) = D\!\left(\frac{\Delta s}{2}\right) \circ K(\Delta s) \circ D\!\left(\frac{\Delta s}{2}\right)\]

Note

Thin lens mode does not change the particle position coordinates \((x, y, z)\), only applies momentum kicks
Chromaticity and other effects in thick lens mode are naturally introduced through the \(p_z\) expression in exact drift
When all knl / ksl components are zero, the thick lens degenerates to a pure drift, avoiding meaningless empty kick loops

Physical Derivation

Hamiltonian

In the Cartesian coordinate system (multipole has no curvature, \(h = 0\)), the general multipole Hamiltonian is:

\[H_{\text{mult}} = \frac{p_\tau}{\beta_0} - \sqrt{(1+\delta)^2 - p_x^2 - p_y^2} + \chi \sum_{n=0}^{N} \frac{K_n}{n!} \operatorname{Re}\left[(x - i y)^n\right]\]

where the summation term is the potential energy part. Splitting it into the propagation part (exact drift \(H_D\)) and the kick part (\(H_K\)):

\[H_D = \frac{p_\tau}{\beta_0} - p_z\]

\[H_K = \chi \sum_{n=0}^{N} \frac{K_n}{n!} \operatorname{Re}\left[(x - i y)^n\right]\]

Kick Map

From Hamilton’s equations \(\Delta p_x = -\frac{\partial H_K}{\partial x} \Delta s\), \(\Delta p_y = -\frac{\partial H_K}{\partial y} \Delta s\), for the integrated strength \(K_{nL} = K_n \cdot \Delta s\):

\[\Delta p_x = -\chi \sum_{n=0}^{N} \frac{K_{nL}}{n!} \operatorname{Re}\left[(x + i y)^n\right]\]

\[\Delta p_y = +\chi \sum_{n=0}^{N} \frac{K_{nsL}}{n!} \operatorname{Im}\left[(x + i y)^n\right]\]

where the real part of \((x+iy)^n\) corresponds to the normal component and the imaginary part corresponds to the skew component.

Note

The complex field convention is \(B_y + i B_x = \frac{P_0}{q_0} \sum_n \frac{K_n}{n!} (x+iy)^n\) (without conjugation). Using the conjugate \(\overline{(x+iy)^n}\) would lead to a sign error in \(\Delta p_y\). This convention has been verified through sextupole cross-validation.

Horner Nested Evaluation

The core of the multipole kick is to evaluate the polynomial:

\[P(z) = \sum_{n=0}^{N} c_n z^n, \qquad z = x + i y\]

where \(c_n = \chi \cdot K_{nL} / n!\). Direct expansion of higher-order terms is computationally expensive and numerically unstable. PASS uses Horner nested evaluation.

The Horner recursion starts from the highest-order coefficient and works downward:

index = order
dpx_mul = chi * knl[order] / order!     # Highest-order coefficient
dpy_mul = chi * ksl[order] / order!

while index > 0:
    zre = dpx_mul * x - dpy_mul * y      # Re[(dpx_mul + i*dpy_mul) * (x + iy)]
    zim = dpx_mul * y + dpy_mul * x      # Im[(dpx_mul + i*dpy_mul) * (x + iy)]
    index -= 1
    dpx_mul = chi * knl[index] / index! + zre
    dpy_mul = chi * ksl[index] / index! + zim

dpx = -dpx_mul    # px is negated (radian convention)
dpy = +dpy_mul    # py is not negated

where zre and zim are the real and imaginary parts of the complex multiplication \((\text{dpx\_mul} + i \cdot \text{dpy\_mul}) \cdot (x + i y)\).

The final kick is:

\[\Delta p_x = -\text{dpx\_mul}\]

\[\Delta p_y = +\text{dpy\_mul}\]

Note that \(\Delta p_x\) is negated (radian convention), and \(\Delta p_y\) is not.

Expansion Results for Each Order

Expanding the Horner recursion, the first few orders are:

Order	\(\Delta p_x\) (normal component)	\(\Delta p_y\) (normal component)
\(n=0\)	\(-\chi K_{0L}\)	\(0\)
\(n=1\)	\(-\chi K_{1L} \cdot x\)	\(+\chi K_{1L} \cdot y\)
\(n=2\)	\(-\chi K_{2L}/2 \cdot (x^2 - y^2)\)	\(+\chi K_{2L} \cdot x y\)
\(n=3\)	\(-\chi K_{3L}/6 \cdot (x^3 - 3xy^2)\)	\(+\chi K_{3L}/6 \cdot (3x^2 y - y^3)\)

The skew component kick naturally swaps real and imaginary parts through complex multiplication \(i \cdot z^n\): the normal component formula for \(\Delta p_x\) in the table above is moved to \(\Delta p_y\), and the normal component formula for \(\Delta p_y\) is moved to \(\Delta p_x\) and negated.

Note

The Horner recursion is general for any order \(N\). When the knl / ksl arrays have only a single nonzero order component, the multipole degenerates to the corresponding single-order element (quadrupole/sextupole/octupole, etc.), and the kick formula is particle-by-particle consistent with the hardcoded version.

Exact Drift Map

The drift part uses the exact drift (Table 1.1, map D, Eq. 1.86-1.88), identical to that of the quadrupole/sextupole/octupole:

\[x \mathrel{+}= \frac{p_x}{p_z} L\]

\[y \mathrel{+}= \frac{p_y}{p_z} L\]

\[z \mathrel{+}= L \left(1 - \frac{\beta_0}{\beta} \cdot \frac{1+\delta}{p_z}\right)\]

where:

\[p_z = \sqrt{(1+\delta)^2 - p_x^2 - p_y^2}\]

\[\beta = \frac{(1+\delta) \beta_0 \gamma_0}{\sqrt{1 + \left[(1+\delta) \beta_0 \gamma_0\right]^2}}\]

The exact drift preserves the full nonlinearity of \(p_z\), naturally introducing chromaticity, higher-order dispersion, and path-length effects.

Symplectic Integrators

Uniform (2nd-order leapfrog)

Each slice performs Drift-Kick-Drift:

\[\mathcal{M}_{\text{DKD}}(\Delta s) = D\!\left(\frac{\Delta s}{2}\right) \circ K(\Delta s) \circ D\!\left(\frac{\Delta s}{2}\right)\]

This is a 2nd-order symplectic integrator with truncation error \(O(\Delta s^2)\).

Yoshida4 (4th-order composition)

Three DKD steps are combined into a 4th-order symplectic integrator:

\[\mathcal{M}_{\text{Y4}}(\Delta s) = \mathcal{M}_{\text{DKD}}(z_1 \Delta s) \circ \mathcal{M}_{\text{DKD}}(z_0 \Delta s) \circ \mathcal{M}_{\text{DKD}}(z_1 \Delta s)\]

where the Yoshida coefficients are:

\[z_1 = \frac{1}{2 - 2^{1/3}} \approx 1.3512\]

\[z_0 = 1 - 2 z_1 \approx -1.7024\]

Truncation error \(O(\Delta s^4)\).

Naturally Included Effects

DKD-exact naturally includes all nonlinear effects for an ideal multipole without additional terms:

Effect	Source
Natural chromaticity	\(\delta\) dependence of \(p_z\) in exact drift
Higher-order nonlinear dispersion	Complete square root expression of \(p_z\)
Path-length effects (\(R_{56}\), etc.)	\(z\) update in exact drift
Full nonlinearity of each order multipole kick	Horner recursion preserves all terms of \((x+iy)^n\)

The split-map truncation error is \(O(\Delta s^2)\) for uniform and \(O(\Delta s^4)\) for yoshida4. Finite-precision arithmetic also contributes error; see Integration precision for the coefficient, substep and particle-storage precision conventions.

Reference-orbit scope

The multipole uses a straight reference orbit. It does not provide an hxl curvature correction for a bent reference orbit.

Absolute normal/skew field errors and static DX/DY/DPSI alignment use the common Element errors interface. Alignment moves only the magnetic field; apertures and SC boundaries remain in the design frame.

Application Scenarios

Field error injection: Insert magnet field errors exported from MAD-X as multipoles into the beamline, simulating installation errors and manufacturing deviations
Combined multipole elements: Simultaneously apply multipole kicks of multiple orders at the same location (e.g., quadrupole + sextupole + octupole combination)
Higher-order multipoles: Decapoles (\(n=4\)), dodecapoles (\(n=5\)), and other higher-order elements beyond the range of dedicated elements
Nonlinear effect studies: Study the impact of higher-order multipole fields on beam dynamics, such as dynamic aperture and resonance driving

References

Xsuite Physics Guide, Sec 1.10.3 (exact drift), Sec 1.10.5 (multipole)
Xsuite source code: xtrack/beam_elements/elements_src/multipole.h, track_magnet.h, track_magnet_kick.h, track_magnet_drift.h
Yoshida, H., “Construction of higher order symplectic integrators”, Phys. Lett. A 150 (1990)
MAD-X Physics Manual: multipole field and nonlinear transport
Wiedemann, H., “Particle Accelerator Physics”, Ch. 4 (nonlinear beam dynamics)

Internal Space Charge

A positive-length element may set space_charge (JSON Space charge) to an ElementSpaceCharge object. Num slices controls external transport, while Space charge.Num kicks controls SC integration. See Element Slicing and Internal Space Charge for scheduling, shared resources, supported backends and examples.