Octupole

This module describes the PASS octupole element Octupole, used to simulate the motion of charged particles in an octupole magnet. The octupole provides a cubic nonlinear magnetic field and is an important nonlinear element in accelerators, primarily used for Landau damping, amplitude-dependent tune shift (ADTS), and resonance suppression.

The PASS octupole 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.

Code Location

• Source file: PASS/commands/element/octupole.py

• Class name: Octupole (inherits from Command)

• Registration name: octupole

• Key features:

  • Supports thin lens mode (length = 0, applies only an octupole kick)

  • Supports thick lens mode (length > 0, DKD-exact symplectic integration)

  • Supports uniform (2nd-order leapfrog) and yoshida4 (4th-order Yoshida composition) integrators

  • Supports normal octupole (k3l) and skew octupole (k3sl) and their combinations

  • Zero field (k3l = k3sl = 0) automatically degenerates to a pure drift

  • Higher-order nonlinear effects naturally introduced through exact drift

  • Supports aperture check

Coordinate Convention

PASS uses normalized curvilinear coordinates consistent with Xsuite. 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, \(\zeta = s - \beta_0 c t\)
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\).

Octupole Field and Normalized Strength

The magnetic field of an octupole magnet has a cubic distribution in the transverse plane. In complex notation:

\[B_y + i B_x = \frac{1}{6}(B''' + i B'''_s)(x + i y)^3\]

where \(B'''\) is the normal octupole field third derivative and \(B'''_s\) is the skew octupole field third derivative. Expanding:

\[B_y = \frac{1}{6} B''' (x^3 - 3 x y^2) - \frac{1}{6} B'''_s (3 x^2 y - y^3)\]

\[B_x = \frac{1}{6} B''' (3 x^2 y - y^3) + \frac{1}{6} B'''_s (x^3 - 3 x y^2)\]

The normalized octupole strength is defined as:

\[K_3 = \frac{q_0 B'''}{6 P_0}\]

\[K_{3s} = \frac{q_0 B'''_s}{6 P_0}\]

The integrated strength is:

\[K_{3L} = K_3 \cdot L, \qquad K_{3sL} = K_{3s} \cdot L\]

where \(L\) is the magnet length. In PASS, the user directly specifies \(K_{3L}\) (k3l) and \(K_{3sL}\) (k3sl); for thick lenses, \(K_3 = K_{3L} / L\) and \(K_{3s} = K_{3sL} / L\) are solved internally.

Overall Tracking Flow

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

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

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

Single octupole kick Kick(K3L, K3sL)
[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

If K3L = 0 and K3sL = 0: degenerates to a single exact drift Drift(L)

The complete map is:

Thin lens:

\[\mathcal{M}_{\text{thin}} = \text{Kick}(K_{3L}, K_{3sL})\]

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

• Dispersion-related effects in thick lens mode are naturally introduced through the \(p_z\) expression in exact drift

• When \(K_{3L} = 0\) and \(K_{3sL} = 0\), the thick lens degenerates to a pure drift, avoiding meaningless empty kick loops

Physical Derivation

Hamiltonian

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

\[H_{\text{oct}} = \frac{p_\tau}{\beta_0} - \sqrt{(1+\delta)^2 - p_x^2 - p_y^2} + \frac{\chi}{24}\left[K_3(x^4 - 6 x^2 y^2 + y^4) + K_{3s}(4 x^3 y - 4 x y^3)\right]\]

Splitting it into the propagation part (exact drift \(H_D\)) and the kick part (\(H_K\)):

\[H_D = \frac{p_\tau}{\beta_0} - \sqrt{(1+\delta)^2 - p_x^2 - p_y^2}\]

\[H_K = \frac{\chi}{24}\left[K_3(x^4 - 6 x^2 y^2 + y^4) + K_{3s}(4 x^3 y - 4 x y^3)\right]\]

where \(H_D\) is the exact drift Hamiltonian (preserving the \(p_z\) square root without small-momentum expansion), and \(H_K\) is the octupole kick. This is the standard split-operator method: the Hamiltonian is split into analytically solvable parts, maps are applied separately, and then combined into a symplectic integrator.

Exact Drift Map D

The Hamilton’s equations of the propagation part give the exact drift:

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

\[x \leftarrow x + \frac{p_x}{p_z} \cdot L_D\]

\[y \leftarrow y + \frac{p_y}{p_z} \cdot L_D\]

\[\zeta \leftarrow \zeta + L_D \cdot \left(1 - \frac{\beta_0}{\beta} \cdot \frac{1+\delta}{p_z}\right)\]

where \(L_D\) is the drift length, and \(\beta\) is the particle’s actual normalized velocity:

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

Note

The meaning of “exact”: the drift part preserves the exact square root \(p_z = \sqrt{(1+\delta)^2 - p_x^2 - p_y^2}\) without small-momentum expansion \(p_x \ll 1\). The approximation lies only in separating the propagation part from the kick part (split-operator method). This formula is identical to the exact drift in the Drift element and the Quadrupole and Sextupole elements.

Octupole Kick Map K

The kick part is a thin lens map (position unchanged, momentum jump only). From Hamilton’s equations \(\dot{p}_x = -\partial H / \partial x\), \(\dot{p}_y = -\partial H / \partial y\):

\[\Delta p_x = -\frac{\chi}{6} K_{3L} (x^3 - 3 x y^2) + \frac{\chi}{6} K_{3sL} (3 x^2 y - y^3)\]

\[\Delta p_y = \frac{\chi}{6} K_{3L} (3 x^2 y - y^3) + \frac{\chi}{6} K_{3sL} (x^3 - 3 x y^2)\]

where the kick effective length is already included in the integrated strengths \(K_{3L}\) and \(K_{3sL}\).

Complex notation verification: \((x+iy)^3 = (x^3 - 3xy^2) + i(3x^2y - y^3)\), the real part corresponds to the normal octupole, and the imaginary part corresponds to the skew octupole.

Physical meaning of each term:

Term	Source	Physical Meaning
\(-\frac{\chi}{6} K_{3L} (x^3 - 3xy^2)\)	\(\frac{\chi K_3}{24} x^4\)	Horizontal cubic nonlinear focusing (proportional to \(x^3\))
\(+\frac{\chi}{6} K_{3L} (3x^2y - y^3)\)	\(-\frac{\chi K_3}{4} x^2 y^2\)	Horizontal-vertical coupling kick
\(+\frac{\chi}{6} K_{3sL} (3x^2y - y^3)\)	\(\frac{\chi K_{3s}}{6} x^3 y\)	Skew octupole horizontal coupling kick
\(+\frac{\chi}{6} K_{3sL} (x^3 - 3xy^2)\)	\(-\frac{\chi K_{3s}}{24} y^4\)	Skew octupole vertical cubic nonlinear focusing

For thin lens mode, the integrated strengths \(K_{3L}\) and \(K_{3sL}\) are used directly. For DKD mode, \(K_3 \Delta s\) and \(K_{3s} \Delta s\) are used.

Note

A normal octupole (\(K_3 > 0\)) provides a restoring force proportional to \(x^3\) for particles with positive offset in the horizontal direction. This is the key difference from the sextupole (proportional to \(x^2\)) and the quadrupole (proportional to \(x\)). The octupole focusing force is proportional to the cube of the position, making it a nonlinear element—particles far from the axis experience much stronger deflection than near-axis particles.

Comparison with quadrupole and sextupole: the quadrupole kick depends linearly on \(x\), the sextupole kick depends quadratically on \(x\), and the octupole kick depends cubically on \(x\). This means the octupole does not affect particles on the reference orbit (kick is zero when \(x = y = 0\)), nor does it affect linear orbits (the kick is extremely small for small-amplitude particles), but it produces strong nonlinear deflection for large-amplitude particles. This property makes the octupole an ideal element for Landau damping.

A skew octupole (\(K_{3s} \neq 0\)) rotates the octupole action by \(\pi / 8\), producing a different \(x\)-\(y\) coupling pattern. In practice, it is often used to simulate installation rotation errors or drive specific higher-order coupling resonances.

Uniform Integrator (2nd-order symplectic)

Each slice uses the drift-kick-drift (DKD) structure, i.e., 2nd-order leapfrog:

\[S_2(\Delta s) = D\!\left(\frac{\Delta s}{2}\right) \circ K(\Delta s) \circ D\!\left(\frac{\Delta s}{2}\right)\]

The per-slice error is \(O(\Delta s^3)\), and the global error is \(O(\Delta s^2)\). A 2nd-order symplectic integrator where every step is a canonical transformation.

yoshida4 Integrator (4th-order symplectic)

A 4th-order symplectic map is constructed by composing three 2nd-order DKD steps [Yoshida 1990]:

\[S_4(\Delta s) = S_2(z_1 \Delta s) \circ S_2(z_0 \Delta s) \circ S_2(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\]

Note

\(z_0 < 0\) means the middle step is a backward tracking (the drift and kick “lengths” are negative). This is a mathematical requirement of the Yoshida composition method and is fully self-consistent in the symplectic map group. The per-slice error is \(O(\Delta s^5)\), and the global error is \(O(\Delta s^4)\).

Amplitude-Dependent Tune Shift

The most important physical effect of the octupole is the amplitude-dependent tune shift (ADTS), which is the physical basis of Landau damping.

Physical Mechanism

Considering single-plane motion (\(y = 0\)), the normal octupole kick is:

\[\Delta p_x = -\frac{\chi}{6} K_{3L} \, x^3\]

Under the smooth approximation, the equivalent frequency shift over one revolution is:

\[\Delta Q_x = -\frac{\chi K_{3L}}{16\pi} \oint \beta_x^2 \, ds \cdot J_x\]

where \(J_x = \frac{1}{2\beta_x}(x^2 + (\beta_x p_x + \alpha_x x)^2)\) is the action. The tune shift is proportional to the square of the amplitude (i.e., the action \(J_x\)), meaning that large-amplitude particles have tunes deviating from small-amplitude particles. This spreads the beam in tune space, enabling Landau damping.

Note

• The tune shift produced by the octupole is proportional to \(J\) (action), i.e., proportional to the square of the amplitude

• The tune shift produced by the sextupole through dispersion-momentum deviation coupling is proportional to \(\delta\), i.e., proportional to the momentum deviation

• The tune shift of the quadrupole is independent of amplitude (linear element)

• The octupole ADTS does not depend on dispersion (\(\eta_x\)) and can be used at dispersion-free locations

Naturally Included Higher-Order Effects

In the DKD-exact scheme, all nonlinear effects of an ideal octupole magnet are naturally included without any additional treatment:

Effect	Source
Amplitude-dependent tune shift	\(x^3\) term in the kick; large-amplitude particles experience stronger deflection
Higher-order dispersion	Exact \(p_z\) in drift makes dispersion evolution contain all orders of \(\delta\) dependence
Path-length effects (\(R_{56}\), etc.)	\(\zeta\) update in drift contains the complete \(R_{56}\), \(T_{566}\), and higher-order terms
Thick-lens distribution effects	In DKD multi-slice, drift changes \(x\), and subsequent kicks act on updated coordinates
\(x\)-\(y\) coupling	\(x^2 y\), \(xy^2\) cross terms in the kick
Resonance driving	4th-order resonances (\(4Q_x\), \(2Q_x \pm 2Q_y\), \(4Q_y\), etc.)

Note

The only approximation is the discretization error of the split-operator integrator (\(O(\Delta s^2)\) for uniform, \(O(\Delta s^4)\) for yoshida4), which can be controlled by increasing the number of slices. This is a truncation error of the mathematical method, not an omission of physical effects.

Interface Parameters

Property	JSON key	Type	Unit	Description
s	s (m)	float	m	Longitudinal position of the element in the beamline
length	length (m)	float	m	Element length (must be \(\ge 0\); \(= 0\) for thin lens)
name	name	str		Element name
k3l	k3l	float	\(\text{m}^{-3}\)	Normal octupole integrated strength \(K_{3L}\), default 0
k3sl	k3sl	float	\(\text{m}^{-3}\)	Skew octupole integrated strength \(K_{3sL}\), default 0
num_slice	num slices	int		Number of slices, default 1 (effective only for thick lens)
integrator	integrator	str		Integrator, options: adaptive (default uniform), uniform, yoshida4
aperture_type	aperture type	str		Aperture type, default off
aperture_value	aperture value	list		Aperture parameter values, default []

Usage Examples

Thick Lens Normal Octupole

{
    "OCT1": {
        "S (m)": 10.0,
        "Command": "Octupole",
        "Length (m)": 0.5,
        "K3L": 500.0,
        "Num Slices": 5,
        "Integrator": "yoshida4",
        "Aperture Type": "off"
    }
}

Normal octupole (\(K_{3L} > 0\)), length 0.5 m, 5 slices, 4th-order symplectic integration. Used for Landau damping.

Thin Lens Octupole

{
    "OCT2": {
        "S (m)": 20.0,
        "Command": "Octupole",
        "Length (m)": 0.0,
        "K3L": 1000.0,
        "Aperture Type": "off"
    }
}

Zero-length octupole, applying only the \(K_{3L}\) thin lens kick, no body tracking.

Negative Octupole

{
    "OCT3": {
        "S (m)": 30.0,
        "Command": "Octupole",
        "Length (m)": 0.4,
        "K3L": -500.0,
        "Num Slices": 1,
        "Integrator": "uniform",
        "Aperture Type": "off"
    }
}

Negative octupole (\(K_{3L} < 0\)), providing a tune shift in the opposite direction to a positive octupole.

Skew Octupole

{
    "OCT4": {
        "S (m)": 40.0,
        "Command": "Octupole",
        "Length (m)": 0.3,
        "K3L": 0.0,
        "K3SL": 300.0,
        "Num Slices": 1,
        "Integrator": "uniform",
        "Aperture Type": "off"
    }
}

Pure skew octupole (\(K_{3L} = 0\), \(K_{3sL} \neq 0\)), producing a coupling effect equivalent to rotating the normal octupole by \(\pi / 8\).

Normal + Skew Octupole Combination

{
    "OCT5": {
        "S (m)": 50.0,
        "Command": "Octupole",
        "Length (m)": 0.5,
        "K3L": 500.0,
        "K3SL": 100.0,
        "Num Slices": 3,
        "Integrator": "yoshida4",
        "Aperture Type": "circle",
        "Aperture Value": [0.04]
    }
}

Combined octupole with both normal and skew components (simulating installation rotation error), with a circular aperture check.

Application Scenarios

• Landau damping: The octupole produces an amplitude-dependent tune shift, causing the tunes of large-amplitude particles to deviate from the working point, providing Landau damping for coherent oscillations and suppressing beam instabilities

• Resonance suppression: By adjusting the octupole strength, particle tunes are pushed away from dangerous resonance lines, avoiding beam loss due to resonance excitation

• Dynamic aperture control: The cubic nonlinear field of the octupole limits the stable phase-space region, affecting beam lifetime and dynamic aperture

• Nonlinear coupling correction: Using skew octupoles (k3sl) to control higher-order \(x\)-\(y\) coupling

• 4th-order resonance driving: Placing octupoles at specific phases to drive 4th-order resonances (\(4Q_x\), \(2Q_x \pm 2Q_y\), etc.) for resonance extraction or beam scraping

• LHC Landau damping scheme: Distributing octupole families (MO) in the arc region to provide sufficient Landau damping over a wide energy range

References

• Xsuite Physics Guide, Sec 1.10.3 (exact drift), Sec 1.10.5 (multipole)

• Xsuite source code: xtrack/beam_elements/elements_src/octupole.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: octupole field and nonlinear transport

• Wiedemann, H., “Particle Accelerator Physics”, Ch. 4 (nonlinear beam dynamics)