Solenoid

This module describes the PASS solenoid element Solenoid, used to simulate the motion of charged particles in a longitudinal magnetic field. The solenoid produces a uniform magnetic field \(B_z\) along the beam direction, coupling the horizontal and vertical planes through the Larmor rotation effect while providing transverse focusing.

The PASS solenoid uses an exact nonlinear map (analytical solution of the Hamiltonian in the Larmor framework). For a pure solenoid (without multipole field overlay), the map is analytic for the stated uniform-field model, subject to floating-point roundoff; when multipole fields are superimposed, a Sol-Kick-Sol (SKS) symplectic integrator is used.

Registration name: solenoid
Key features:
- Uses exact solenoid map (Larmor rotation + focusing, \(p_z\) computed per particle)
- No axial thin lens mode; at \(L=0\) only integrated transverse multipoles act
- Supports multipole field overlay (knl / ksl), using SKS integrator
- Supports uniform (2nd-order leapfrog) and yoshida4 (4th-order Yoshida composition) integrators
- \(k_s = 0\) gives multipole DKD transport, or pure drift if no transverse multipoles remain
- Chromaticity effects naturally introduced through per-particle \(p_z\)
- Supports aperture check

The fields below configure PASS.para.schema.elements.SolenoidItem. 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`	Element length (must be \(\ge 0\); \(=0\) retains only transverse multipole kicks)
`ks`	`KS`	`float`	\(\text{m}^{-1}\)	`0.0`	Solenoid normalized strength \(k_s = q_0 B_z / P_0\), default 0
`knl`	`KiL`	`list[float]`	\(\text{m}^{-n}\)	`[]`	Multipole normal integrated strength array \(K_{nL}\), default `[]`
`ksl`	`KiSL`	`list[float]`	\(\text{m}^{-n}\)	`[]`	Multipole skew integrated strength array \(K_{sL}\), default `[]`
`num_slices`	`Num slices`	`int`	1	`1`	Number of external body slices, default 1 (also used for a pure solenoid)
`integrator`	`Integrator`	`str`		`'adaptive'`	Integrator, options: `adaptive` (default `uniform`), `uniform`, `yoshida4`
`aperture_type`	`Aperture type`	`str`	—	`'off'`	Aperture type, default `off`
`aperture_value`	`Aperture value`	`list`	m / rad	`[]`	Aperture parameter values, default `[]`

Note

knl / ksl are optional parameters. When their sums with enabled field errors are all zero, each solenoid slice uses the exact body map; num_slices applies and integrator is unused
When nominal multipoles plus enabled field errors are nonzero, the SKS integrator is enabled, and num_slices and integrator take effect
When ks = 0 and the element has length, it uses multipole DKD; it is a pure drift only if nominal plus error multipoles are zero
When length = 0, only transverse multipoles and enabled field errors act; the axial field has no thin lens map

Usage Examples

Pure Solenoid (Exact Map)

{
    "SOL1": {
        "S (m)": 10.0,
        "Command": "Solenoid",
        "Length (m)": 1.0,
        "KS": 2.0,
        "Aperture type": "off"
    }
}

Length 1.0 m, normalized strength \(k_s = 2.0\). Uses a single-segment exact solenoid map without splitting truncation error, but subject to roundoff.

Weak Solenoid

{
    "SOL2": {
        "S (m)": 20.0,
        "Command": "Solenoid",
        "Length (m)": 2.0,
        "KS": 0.5,
        "Aperture type": "off"
    }
}

Weak-field solenoid with a small Larmor rotation angle.

Reverse-Field Solenoid

{
    "SOL3": {
        "S (m)": 30.0,
        "Command": "Solenoid",
        "Length (m)": 1.5,
        "KS": -3.0,
        "Aperture type": "off"
    }
}

\(k_s < 0\) indicates a reverse magnetic field, with the Larmor rotation in the opposite direction.

Solenoid with Quadrupole Overlay (SKS Integrator)

{
    "SOL4": {
        "S (m)": 40.0,
        "Command": "Solenoid",
        "Length (m)": 1.0,
        "KS": 2.0,
        "KiL": [0.0, 0.1],
        "KiSL": [],
        "Num slices": 4,
        "Integrator": "yoshida4",
        "Aperture type": "off"
    }
}

Solenoid (\(k_s = 2.0\)) with superimposed quadrupole component (\(K_{1L} = 0.1\)), 4 slices, 4th-order symplectic integrator. The KiL array index 0 is \(K_{0L}\) (dipole), and index 1 is \(K_{1L}\) (quadrupole).

Zero-Field Degeneration (Pure Drift)

{
    "SOL5": {
        "S (m)": 50.0,
        "Command": "Solenoid",
        "Length (m)": 1.0,
        "KS": 0.0,
        "Aperture type": "off"
    }
}

When \(k_s = 0\), degenerates to a pure drift.

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.

Solenoid Field and Normalized Strength

The solenoid produces a uniform magnetic field along the beam direction (\(s\) axis):

\[\vec{B} = (0, \, 0, \, B_z)\]

The normalized solenoid strength is defined as:

\[k_s = \frac{q_0 B_z}{P_0}\]

where \(q_0\) is the reference particle charge and \(P_0\) is the reference particle momentum. In PASS, the user directly specifies \(k_s\) (ks).

Define the half-strength:

\[\text{sk} = \frac{k_s}{2}\]

The Larmor rotation angle is:

\[\theta = \frac{\text{sk} \cdot L}{p_z} = \frac{k_s L}{2 p_z}\]

where \(p_z\) is the particle’s normalized longitudinal momentum component (different for each particle, see below), and \(L\) is the solenoid length.

Physical Derivation

Hamiltonian

In the Cartesian coordinate system, the solenoid Hamiltonian is:

\[H_{\text{sol}} = \frac{p_\tau}{\beta_0} - \sqrt{(1+\delta)^2 - p_x^2 - p_y^2} + \frac{k_s^2}{8}(x^2 + y^2) - \frac{k_s}{2}(x p_y - y p_x)\]

The physical meaning of each term:

Term	Physical Meaning
\(-\sqrt{(1+\delta)^2 - p_x^2 - p_y^2}\)	Free propagation (exact drift)
\(\frac{k_s^2}{8}(x^2 + y^2)\)	Solenoid focusing (equivalent quadrupole component)
\(-\frac{k_s}{2}(x p_y - y p_x)\)	Larmor rotation (\(x\)-\(y\) coupling)

Note

The Larmor rotation term \(-\frac{k_s}{2}(x p_y - y p_x)\) depends on both position and momentum simultaneously, which is the fundamental difference between the solenoid and the quadrupole. The quadrupole kick term depends only on position, allowing the Hamiltonian to be cleanly split into drift and kick parts (DKD integrator). The Larmor rotation term of the solenoid cannot be split into purely position-dependent or purely momentum-dependent parts, and therefore cannot use ordinary drift for DKD integration.

Larmor Framework and Exact Solution

Performing the Larmor transformation—rotating the transverse coordinate system about the \(s\) axis by angle \(\theta = \text{sk} \cdot s / p_z\)—defines the canonical momenta in the Larmor framework:

\[p_{k1} = p_x + \text{sk} \cdot y\]

\[p_{k2} = p_y - \text{sk} \cdot x\]

In the Larmor framework, \(p_{k1}\) and \(p_{k2}\) are conserved quantities (do not vary with \(s\)), so the longitudinal momentum component:

\[p_z = \sqrt{(1+\delta)^2 - p_{k1}^2 - p_{k2}^2}\]

is constant per particle throughout the solenoid. This allows the solenoid map to be solved exactly without approximation.

Exact Solenoid Map

Given the solenoid length \(L\), the Larmor rotation angle:

\[\theta = \frac{\text{sk} \cdot L}{p_z}\]

The map is divided into two steps: rotation and drift.

Step 1: Larmor rotation (rotating coordinates to the Larmor framework at \(s=L\))

\[\text{rps}_0 = \cos\theta \cdot x + \sin\theta \cdot y\]

\[\text{rps}_1 = \cos\theta \cdot p_x + \sin\theta \cdot p_y\]

\[\text{rps}_2 = \cos\theta \cdot y - \sin\theta \cdot x\]

\[\text{rps}_3 = \cos\theta \cdot p_y - \sin\theta \cdot p_x\]

Step 2: Drift in the Larmor framework (equivalent drift length \(\sin\theta / \text{sk}\))

\[x' = \cos\theta \cdot \text{rps}_0 + \frac{\sin\theta}{\text{sk}} \cdot \text{rps}_1\]

\[p_x' = \cos\theta \cdot \text{rps}_1 - \text{sk} \cdot \sin\theta \cdot \text{rps}_0\]

\[y' = \cos\theta \cdot \text{rps}_2 + \frac{\sin\theta}{\text{sk}} \cdot \text{rps}_3\]

\[p_y' = \cos\theta \cdot \text{rps}_3 - \text{sk} \cdot \sin\theta \cdot \text{rps}_2\]

Longitudinal coordinate update:

\[\Delta\zeta = L \cdot \left(1 - \frac{1+\delta}{p_z \cdot \text{rvv}}\right)\]

where \(\text{rvv} = \beta / \beta_0\) is the ratio of the particle velocity to the reference particle velocity:

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

Note

\(p_z\) is different for each particle (including contributions from \(\delta\) and Larmor momenta), so the map is exactly nonlinear
When \(k_s \to 0\), \(\sin\theta/\text{sk} \to L/p_z\), and the map degenerates to exact drift

Why the Solenoid Has No Thin Lens Mode

The thin lens limit of a quadrupole (\(L \to 0\), \(k_1 \to \infty\), \(k_1 L = \text{const}\)) gives a finite momentum kick \(\Delta p_x = -k_{1L} \cdot x\), which is physically self-consistent.

The thin lens limit of a solenoid (\(L \to 0\), \(k_s \to \infty\), \(k_s L = \text{const}\)) has a fundamental difficulty:

Larmor rotation angle \(\theta = k_s L / (2 p_z)\) is finite ✓
Focusing term \(\text{sk} \cdot \sin\theta = (k_s/2) \cdot \sin\theta \to \infty\) diverges ✗

The scaling behavior of position and momentum is asymmetric: the rotation angle is finite but the focusing force diverges, so the thin lens limit does not exist.

Therefore PASS provides no axial thin lens map. At \(L=0\), KS has no effect, but nominal transverse multipoles and enabled field errors still apply their integrated thin kick.

Multipole Field Overlay and SKS Integrator

When transverse multipole field components (\(k_{nl}\) / \(k_{sl}\)) are superimposed inside the solenoid, the total Hamiltonian is:

\[H = H_{\text{sol}} + H_{\text{mult}}\]

where \(H_{\text{mult}}\) is the multipole kick Hamiltonian (depending only on position). Since \(H_{\text{sol}}\) and \(H_{\text{mult}}\) do not commute, a split-operator method is needed.

PASS uses the Sol-Kick-Sol (SKS) integrator, fully parallel to the quadrupole’s DKD:

\[\mathcal{M}_{\text{SKS}}(\Delta s) = \text{Sol}\!\left(\frac{\Delta s}{2}\right) \circ \text{Kick}(\Delta s) \circ \text{Sol}\!\left(\frac{\Delta s}{2}\right)\]

where:

Sol = exact solenoid map (_solenoid_exact_cpu), handling the \(B_z\) field
Kick = multipole kick (Horner recursion), handling transverse multipole fields

	Drift Operator	Kick Operator	Scenario
Quadrupole DKD	Free drift `drift_exact`	Quadrupole kick `quad_kick`	\(B_z = 0\), only transverse gradient field
Solenoid SKS	Solenoid map `solenoid_exact`	Multipole kick `multipole_kick`	\(B_z \neq 0\), superimposed transverse multipole fields

Note

The “Sol” in SKS is not a free drift but the exact solenoid map. Inside the solenoid, \(B_z\) is always present, and particles do not drift in field-free space. If a free drift is incorrectly used instead of the solenoid map, the Larmor rotation effect would be lost.

Uniform Integrator (2nd-order symplectic)

Each slice uses the Sol-Kick-Sol structure, i.e., 2nd-order leapfrog:

\[S_2(\Delta s) = \text{Sol}\!\left(\frac{\Delta s}{2}\right) \circ \text{Kick}(\Delta s) \circ \text{Sol}\!\left(\frac{\Delta s}{2}\right)\]

The per-slice error is \(O(\Delta s^3)\), and the global error is \(O(\Delta s^2)\).

yoshida4 Integrator (4th-order symplectic)

A 4th-order symplectic map is constructed by composing three 2nd-order SKS 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\]

The per-slice error is \(O(\Delta s^5)\), and the global error is \(O(\Delta s^4)\).

Overall Tracking Flow

Depending on whether multipole fields are superimposed, the solenoid has two tracking paths:

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

No multipole field (knl/ksl all zero):
  Single-segment exact solenoid map Sol(L, ks)
  [Zero error, no slicing needed]

With multipole field (knl/ksl nonzero):
  Slice 1 → Slice 2 → ... → Slice N
  (Each slice: Sol(ds/2) → Kick(ds) → Sol(ds/2))
  where ds = L / N

Special cases:
  ks = 0 → multipole DKD, or Drift(L) if no transverse multipoles remain
  L = 0 → only the integrated transverse multipole kick remains

The complete map is:

Without multipole field:

\[\mathcal{M} = \text{Sol}(L, k_s)\]

With multipole field (\(N\) slices):

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

Chromaticity Effects

The chromaticity effects of the solenoid are naturally introduced through the per-particle \(p_z\) expression.

In the Larmor framework, \(p_z\) depends on \(\delta\) and the Larmor momenta \(p_{k1}, p_{k2}\):

\[p_z = \sqrt{(1+\delta)^2 - (p_x + \text{sk} \cdot y)^2 - (p_y - \text{sk} \cdot x)^2}\]

Particles with different momentum deviations \(\delta\) have different \(p_z\), and therefore different Larmor rotation angles \(\theta = \text{sk} \cdot L / p_z\) and different equivalent drift lengths \(\sin\theta / \text{sk}\). This is the physical origin of solenoid chromaticity—momentum-dependent rotation angle and focusing strength.

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

Low-energy beam transport lines: In low-energy sections where \(\beta\gamma\) is small, solenoid focusing is more efficient than quadrupoles, and is commonly used in injectors and low-energy transport lines
Electron coolers: Solenoids confine the electron beam to co-move with the ion beam, used for cooling transverse emittance
Collider detector solenoids: The solenoid magnetic fields of large experimental detectors (e.g., CMS, ATLAS) have a significant impact on beam optics and must be accurately accounted for in the lattice model
Superconducting solenoids: Multipole field errors in high-field superconducting solenoids can be modeled through knl / ksl parameter overlay
Rotationally symmetric beams: The Larmor rotation of the solenoid can be used to eliminate \(x\)-\(y\) coupling or produce specific rotationally symmetric beam distributions

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.