28  Overview

28.1 Introduction

OPALX tracks relativistic particles in three dimensions using time as the independent variable. It computes self-consistent space-charge forces in the electrostatic approximation. Short-range longitudinal and transverse wake-field models are not available in the current OPALX version. OPALX is one of the few codes that is implemented using a parallel programming paradigm from the ground up. This makes OPALX indispensable for high statistics simulations of various kinds of existing and new accelerators. OPALX provides beamline elements whose supported external fields can overlap. Each active element is evaluated in its local frame, and its field contribution is added to the particle fields. Supported RF models include standing-wave cavities and traveling-wave structures. The OPEN space-charge solver offers standard and integrated Green functions; the integrated form supports accurate treatment of elongated beams. A shifted Green-function formulation is available for cathode image-charge calculations under its documented restrictions [1], [2], [3]. For particle-source simulations, such as electron guns, OPALX can use energy binning in three-dimensional electrostatic space-charge calculations to model beams with a large energy spread [4].

28.2 Variables in OPALX

OPALX uses the following position and normalized momentum components to describe particle motion. Normalized momentum is dimensionless, \(\widetilde{\mathbf p}=\mathbf p/(mc)=\gamma\boldsymbol\beta\), as defined in Conventions.

The position components X, Y and Z describe particle coordinates in the current reference frame [m]. The corresponding momentum components PX, PY and PZ are dimensionless, with normalized momentum \(\widetilde{\mathbf p}=\mathbf p/(mc)=\gamma\boldsymbol\beta\). For external-field evaluation, OPALX temporarily transforms positions and momenta into each active element’s local frame. Laboratory coordinates require the reference-to-laboratory transformation.

The independent variable is t [s].

28.3 Integration of the Equation of Motion

OPALX integrates the relativistic Lorentz equation

\[\frac{\mathrm{d}\gamma\mathbf{v}}{\mathrm{d}t} = \frac{q}{m}[\mathbf{E}_{ext} + \mathbf{E}_{sc} + \mathbf{v} \times (\mathbf{B}_{ext} + \mathbf{B}_{sc})]\]

where \(\gamma\) is the relativistic factor, \(q\) is the charge, and \(m\) is the rest mass of the particle. \(\mathbf{E}\) and \(\mathbf{B}\) are abbreviations for the electric field \(\mathbf{E}(\mathbf{x},t)\) and magnetic field \(\mathbf{B}(\mathbf{x},t)\). To update the positions and momenta OPALX uses the Boris-Buneman algorithm [5].

28.3.1 Implemented split-step update

The present OPALX tracker is the time-based ParallelTracker. It uses a leap-frog (LF2) style drift–kick–drift update with a Boris-Buneman momentum kick. Second-order accuracy requires appropriately centred, sufficiently smooth field data; the source-moment qualification below applies to binned space charge.

For a particle state \((\mathbf{x}^n,\mathbf{P}^{n})\), where \(\mathbf{P}=\gamma \mathbf{v}/c\), positions are in metres and time is in seconds. One full drift–kick–drift step is organized as:

\[ \mathbf{x}^{n+1/2} = \mathbf{x}^{n} + \frac{c\Delta t}{2}\frac{\mathbf{P}^{n}} {\sqrt{1 + |\mathbf{P}^{n}|^2}}, \]

then fields are assembled at that half-step position,

\[ \mathbf{E}^{n+1/2} = \mathbf{E}_{sc}^{n+1/2} + \mathbf{E}_{ext}^{n+1/2}, \qquad \mathbf{B}^{n+1/2} = \mathbf{B}_{sc}^{n+1/2} + \mathbf{B}_{ext}^{n+1/2}, \]

then the Boris momentum update is applied,

\[ \mathbf{P}^{n+1} \xleftarrow{\;\frac{1}{2}\mathbf{E}\;} \xleftarrow{\;\mathbf{B}\;} \xleftarrow{\;\frac{1}{2}\mathbf{E}\;} \mathbf{P}^{n}, \]

and finally the second half drift is performed,

\[ \mathbf{x}^{n+1} = \mathbf{x}^{n+1/2} + \frac{c\Delta t}{2} \frac{\mathbf{P}^{n+1}}{\sqrt{1 + |\mathbf{P}^{n+1}|^2}}. \]

For the ordinary tracking loop with SCFIELDUPDATE=“MIDPOINT”, the main sequence is:

  1. timeIntegration1(): first half position push.
  2. resetFields(), followed by computeSpaceChargeFields().
  3. emitFromEmissionSources().
  4. computeExternalFields().
  5. timeIntegration2(): Boris kick and second half position push.
  6. Advance the bunch clock and update the reference particle.

With SCFIELDUPDATE=“PRESTEP”, resetFields() and computeSpaceChargeFields() occur before the first half drift. Boundary-refined analytic-ring tracking uses the specialized preparation described below. Emission follows the space-charge solve, so newly emitted particles enter the external-field evaluation in their creation step and contribute to space charge at the next solve.

So the implemented method is not just “a Boris pusher in isolation”; it is a split PIC/tracking loop in which the field solve and external-element queries are placed between two half drifts.

28.3.2 Frame handling during field assembly

One important implementation detail is that space-charge and external fields are not evaluated in the same coordinate frame.

For space charge, computeSpaceChargeFields() temporarily transforms the bunch from the reference frame into a beam-aligned frame whose \(z\)-axis follows the mean momentum. Self-fields are computed there, then the particle positions and the computed \(\mathbf{E}\) and \(\mathbf{B}\) contributions are rotated back to the reference frame.

With SCFIELDUPDATE="MIDPOINT", the position drift leaves particle momenta at \(\mathbf{P}^{n}\). The binned solve therefore obtains its mean momentum and mean Lorentz factor from these unchanged momenta. They determine the beam alignment, longitudinal mesh stretch and relativistic field conversion. For example, with rest-frame electric field \(\mathbf{E}'\), source velocity \(\mathbf{v}_s\) and its unit direction \(\widehat{\mathbf{v}}_s\), the direct field conversion is

\[ \mathbf{E}_{sc}=\overline{\gamma}\mathbf{E}' -(\overline{\gamma}-1)(\mathbf{E}'\cdot\widehat{\mathbf{v}}_s) \widehat{\mathbf{v}}_s, \qquad \mathbf{B}_{sc}=\frac{\overline{\gamma}}{c^2} \mathbf{v}_s\times\mathbf{E}', \qquad \mathbf{v}_s=\frac{c\langle\mathbf{P}^{n}\rangle}{\overline{\gamma}}. \]

Here \(\overline{\gamma}=\langle\sqrt{1+|\mathbf{P}^{n}|^2}\rangle\) is the bin mean Lorentz factor. Midpoint positions do not also centre these source moments in time. When source direction or energy changes, their lag can contribute a first-order error term; a small low-energy coefficient does not change that formal order. Establish accuracy by timestep convergence for the beam and fields being studied, including source-frame evolution.

For external fields, compatible analytic rings select candidate elements from the particles’ laboratory positions on the device. Coasting cyclotron rings use spatial sector candidates from the current bunch bounds; other geometries retain the OrbitThreader path-length query. Each selected element uses its local coordinate transformation and support test. Overlapping external fields, including those of SCALINGFFAMAGNET elements, are superposed for both physical-particle transport and reference transport. For a physical particle at position \(\mathbf r\) and time \(t\), the magnetic field entering the Boris kick is

\[ \mathbf B_{\mathrm{total}}(\mathbf r,t) =\mathbf B_{\mathrm{self}}(\mathbf r,t) +\sum_{j\in\mathcal S(\mathbf r,t)}\mathbf B_j(\mathbf r,t), \]

where \(\mathcal S\) contains the active external elements and all magnetic fields are in tesla. Each contribution must be rotated into the same coordinate frame before addition. Outside an element’s support its contribution is zero; that zero cannot erase another element’s external field or an existing self magnetic field. The reference uses the same external-field sum evaluated on its own trajectory; it carries no self-field kick. Spatial selection is independent of whether the collective solver permits step retries.

The moving reference frame is updated with a quaternion. For normalized old and new directions \(\mathbf{u}\) and \(\mathbf{v}\), its half-angle is computed as \(\tfrac12\operatorname{atan2}(|\mathbf{u}\times\mathbf{v}|, \mathbf{u}\cdot\mathbf{v})\). This retains small resolved rotations when the dot product rounds to one; the existing \(10^{-12}\) parallel/antiparallel threshold is unchanged. Reference and COF integration remain on the host; particle drifts, kicks, support checks, and coordinate transformations use Kokkos.

28.3.3 Boris momentum update

The implemented Boris kernel follows the standard relativistic Birdsall-Langdon form. With \(q\) in coulombs, rest mass \(m\) in kilograms, \(\mathbf{E}\) in V/m, \(\mathbf{B}\) in tesla, and normalized momentum \(\mathbf{P}=\mathbf{p}/(mc)\):

  1. half electric kick \[ \mathbf{P}^{-} = \mathbf{P}^{n} + \frac{\Delta t}{2}\frac{q}{m c}\mathbf{E}, \]
  2. magnetic rotation with \[ \gamma^- = \sqrt{1 + |\mathbf{P}^{-}|^2}, \qquad \mathbf{t} = \frac{\Delta t}{2}\frac{q}{\gamma^- m}\mathbf{B}, \qquad \mathbf{s} = \frac{2\mathbf{t}}{1 + |\mathbf{t}|^2}, \] and \[ \mathbf{w} = \mathbf{P}^{-} + \mathbf{P}^{-}\times\mathbf{t}, \qquad \mathbf{P}^{+} = \mathbf{P}^{-} + \mathbf{w}\times\mathbf{s}, \]
  3. second half electric kick \[ \mathbf{P}^{n+1} = \mathbf{P}^{+} + \frac{\Delta t}{2}\frac{q}{m c}\mathbf{E}. \]

BorisPusher implements the same update using its stored rest energy in eV and charge in elementary-charge units; its numerical coefficients therefore contain \(c/\texttt{mass}\) and \(c^2/\texttt{mass}\) instead of the SI coefficients above.

28.3.4 Common-step boundary refinement for bare analytic rings

Eligible bare rings (FIELDSOLVER, TYPE=NONE) reuse the ordinary device drift–kick–drift sequence with shared subdivision of each nominal DT. For trial duration \(h\), all particles first drift to the common midpoint time. The existing element kernels supply external fields there. A register-only Boris endpoint trial tests whether any particle changes element support between the start, midpoint and endpoint. The replicated reference is tested with the same external-field geometry. MPI combines these decisions so every rank accepts or bisects the same interval.

Bare analytic rings apply selected element callbacks in the prepared lattice’s occurrence order. This includes aperture and monitor callbacks, because their coordinate transformations also affect floating-point rounding. Using this order avoids changing the arithmetic sequence with element allocation addresses. It does not change field supports or formulas; charged and cyclotron tracking retain their established callback order. Bitwise identity across different execution backends or MPI decompositions is not implied.

An accepted trial commits the ordinary Boris kick and second drift once. A rejected trial has not changed momentum: the uncommitted first drift is reversed and the shorter interval is tried again. Both child intervals remain scheduled. The NONE solver adapter retains the mean-momentum rotation but uses the tracking origin, avoiding position quantization from adding and subtracting accumulated path length. Fixed domains, image boundaries, and other solver configurations retain their established coordinate handling. Eligibility is listed in the tracking guide.

This controller is not applied to collective space-charge solves. Resolving every macroparticle’s field-boundary event by repeating a whole-bunch PIC solve can be prohibitively expensive. The ordinary synchronized PIC sequence remains responsible for physical integration. Its accuracy must be established by timestep, mesh and particle-number convergence, independently of tune recording.

The schedule first limits \(h\) to one quarter of the shortest positive element body/support length divided by \(c\). Further bisection stops at a root-relative numerical floor

\[ h_{\mathrm{floor}} = \max\!\left(10^{-12}\Delta t_0, \frac{64\epsilon\max(1\,\mathrm{m},|\mathbf{R}_{\mathrm{ref}}|)} {v_{\mathrm{ref}}}\right), \]

where \(\Delta t_0\) is the nominal interval, \(\epsilon\) is double-precision machine epsilon, \(\mathbf{R}_{\mathrm{ref}}\) is the laboratory reference position, and \(v_{\mathrm{ref}}>0\) is its physical speed in m/s. The controller also bounds subdivision depth at 64 and work at one million trials per nominal interval. Unresolved crossings at the numerical floor are accepted. Compensated time accumulation retains the complete nominal interval.

The underlying Boris update is second order for smooth, appropriately centred fields. State-dependent boundary selection does not itself establish that order at hard edges. Magnetic rotation preserves momentum magnitude with zero electric field up to roundoff. Refinement changes the step partition and floating-point operation order. Output frequencies and the global step counter count accepted substeps; MAXSTEPS counts completed nominal intervals.

28.3.5 Passive selected-particle section observations

Diagnostic crossings can be reconstructed from two accepted endpoints without altering the particle or the integration schedule. Let a fixed plane in laboratory coordinates be \(g(\mathbf r)=\mathbf n\cdot(\mathbf r-\mathbf r_0)=0\). For a bracket with \(g_n<0\) and \(g_{n+1}\geq0\), define

\[ \alpha=\frac{-g_n}{g_{n+1}-g_n},\qquad t_c=t_n+\alpha(t_{n+1}-t_n),\qquad \mathbf w_c=(1-\alpha)\mathbf w_n+\alpha\mathbf w_{n+1}, \]

where \(\mathbf w\) contains position [m] and normalized momentum \(\widetilde{\mathbf p}\) at the same physical time. Positive interpolated momentum along the normal selects forward crossings. A negative-side excursion arms the next return, so the launch point, reverse crossing and near-plane jitter do not count as turns. Histories are keyed by fixed particle IDs; missing intervals are not interpolated. The count is the number of observed forward crossings of that plane, which is a turn count only when the selected section is crossed once per revolution. Positive substeps can have equal rounded absolute timestamps. Such endpoint pairs still define a spatial interpolation and share the recorded crossing time; strictly decreasing timestamps are rejected. No integration step is changed to make diagnostic times distinct.

Linear interpolation is exact for constant drift and has second-order event error for a smooth transverse crossing. It does not correct transport errors or resolve multiple crossings hidden inside a timestep. Observation planes should be away from discontinuous fields and interpolation must be checked under timestep refinement. Space charge can remain nonzero in a magnet-free straight. The internal bare-ring benchmark records only selected endpoints and leaves the full population’s physical advancement unchanged; it introduces no public input command. Cyclotron tracking does not activate this benchmark recorder.

28.3.6 Integration class structure

The current integration stack is shown below.

classDiagram
  direction TB

  class TrackRun {
    +execute()
  }

  class Tracker {
    +execute()
  }

  class ParallelTracker {
    +execute()
    +timeIntegration1(pusher)
    +timeIntegration2(pusher)
    +computeSpaceChargeFields(sourceOth)
    +computeExternalFields(oths)
    +emitFromEmissionSources(t, dt)
    +updateReference(pusher)
  }

  class PartBunch {
    +updateAllParticleMoments()
    +calcBeamParameters()
    +incrementT()
    +getParticleContainer(i)
  }

  class ParticleContainer {
    +R
    +P
    +E
    +B
    +dt
    +transformBunch(trafo)
  }

  class OrbitThreader {
    +execute()
    +query(s, dz)
  }

  class BorisPusher {
    +kick(R, P, E, B, dt, mass, charge)
    +push(R, P, dt)
  }

  class LF2 {
    <<leap-frog integrator>>
  }

  TrackRun --> ParallelTracker : constructs/runs
  Tracker <|-- ParallelTracker
  ParallelTracker --> PartBunch : advances
  PartBunch --> ParticleContainer : owns
  ParallelTracker --> OrbitThreader : active-element queries
  ParallelTracker --> BorisPusher : push/kick kernel
  LF2 ..> BorisPusher : same split-step scheme
Figure 28.1: Current time-integration structure used by the OPALX parallel tracker.

The main point is that ParallelTracker orchestrates the full step, while BorisPusher only provides the local momentum and position update kernel. Field assembly, coordinate-frame changes, emission, and reference-particle updates are handled outside the pusher in the tracker loop itself.

28.4 Positioning of Elements

OPALX places elements in three-dimensional laboratory space and evaluates each active field in the element’s local frame. Explicit placement uses translations and rotations; reference-line attributes may be compiled into the same spatial representation where supported by the element.

At runtime, ordinary element selection uses each container’s OrbitThreader support query. Compatible analytic rings instead select candidates from particle positions using spatial support tests. Each selected element is evaluated with its local frame and support condition. This permits overlapping field supports without assigning every longitudinal position to a single element.

Element length, field support, and aperture are distinct concepts. Models that need a finite transverse extent must define it through their supported geometry or aperture attributes rather than relying on an implicit beamline tube.

28.5 Coordinate Systems

The motion of a charged particle in an accelerator can be described by relativistic Hamilton mechanics. A particular motion is that of the reference particle, having the central energy and traveling on the so-called reference trajectory. Motion of a particle close to this fictitious reference particle can be described by linearized equations for the displacement of the particle under study, relative to the reference particle. OPALX uses time \(t\) as the independent variable. For a quantity evaluated along a trajectory parameterized by scalar path length \(s\),

\[\frac{\mathrm d}{\mathrm dt}=\frac{\mathrm ds}{\mathrm dt}\frac{\mathrm d}{\mathrm ds},\qquad \frac{\mathrm ds}{\mathrm dt}=|\mathbf v|=c|\boldsymbol\beta|.\]

In the tracker, the reference path length is accumulated along the reference trajectory; it is distinct from a particle’s longitudinal coordinate in the reference frame.

28.5.1 Global Cartesian Coordinate System

We define the global cartesian coordinate system, also known as floor coordinate system with \(K\), a point in this coordinate system is denoted by \((X, Y, Z) \in K\). In Figure 28.2 the geometry of the accelerator is uniquely defined by the sequence of physical elements in \(K\). The beam elements are numbered \(e_0, \ldots , e_i, \ldots e_n\).

Figure 28.2: Illustration of local and global coordinates.

28.5.2 Local Cartesian Coordinate System

A local coordinate system \(K'_i\) is attached to each element \(e_i\). This is simply a frame in which \((0,0,0)\) is at the entrance of each element. For an illustration see Figure 28.2. The local reference system \((x, y, z) \in K'_n\) may thus be referred to a global Cartesian coordinate system \((X, Y, Z) \in K\).

The local coordinates \((x_i, y_i, z_i)\) at element \(e_i\) with respect to the global coordinates \((X, Y, Z)\) are defined by three displacements \((X_i, Y_i, Z_i)\) and three angles \((\Theta_i, \Phi_i, \Psi_i)\).

For the explicit element pose, \(\Theta\) (THETA) rotates about the \(Y\)-axis, \(\Phi\) (PHI) about the \(X\)-axis, and \(\Psi\) (PSI) about the \(Z\)-axis. These are Tait–Bryan angles [6]. The element’s active local-to-laboratory rotation is composed as \(\mathcal W=R_y(\Theta)R_x(\Phi)R_z(\Psi)\); the corresponding laboratory-to-local transformation uses its inverse.

The displacement is described by a vector \(\mathbf{v}\) and the orientation by a unitary matrix \(\mathcal{W}\). The column vectors of \(\mathcal{W}\) are unit vectors spanning the local coordinate axes in the order \((x, y, z)\). \(\mathbf{v}\) and \(\mathcal{W}\) have the values:

\[\mathbf{v} =\left(\begin{array}{c} X \\ Y \\ Z \end{array}\right), \qquad \mathcal{W}=\mathcal{S}\mathcal{T}\mathcal{U}\]

where

\[\mathcal{S}=\left(\begin{array}{ccc} \cos\Theta & 0 & \sin\Theta \\ 0 & 1 & 0 \\ -\sin\Theta & 0 & \cos\Theta \end{array}\right), \quad \mathcal{T}=\left(\begin{array}{ccc} 1 & 0 & 0 \\ 0 & \cos\Phi & -\sin\Phi \\ 0 & \sin\Phi & \cos\Phi \end{array}\right), \quad \mathcal{U}=\left(\begin{array}{ccc} \cos\Psi & -\sin\Psi & 0 \\ \sin\Psi & \cos\Psi & 0 \\ 0 & 0 & 1 \end{array}\right).\]

We take the vector \(\mathbf{r}_i\) to be the displacement and the matrix \(\mathcal{S}_i\) to be the rotation of the local reference system at the exit of the element \(i\) with respect to the entrance of that element.

Denoting with \(i\) a beam line element, one can compute \(\mathbf{v}_i\) and \(\mathcal{W}_i\) by the recurrence relations

\[\mathbf{v}_i = \mathcal{W}_{i-1}\mathbf{r}_i + \mathbf{v}_{i-1}, \qquad \mathcal{W}_i = \mathcal{W}_{i-1}\mathcal{S}_i,\]

where \(\mathbf{v}_0\) corresponds to the origin of the LINE and \(\mathcal{W}_0\) to its orientation. In OPALX they can be defined using either X, Y, Z, THETA, PHI and PSI or ORIGIN and ORIENTATION, see Simple Beam Lines.

28.5.3 Space Charge Coordinate System

For ordinary space-charge calculations, OPALX constructs a solve frame K_sc whose z-axis aligns with the primary particle container’s mean momentum. Its longitudinal origin is set by the accumulated reference path length; it is not generally the bunch centroid. If the mean momentum is too small, the alignment uses the reference momentum, then the positive z direction as a final fallback. Collective elements can use a separate fixed-domain frame.

28.5.4 Curvilinear Coordinate System

In order to compute statistics of the particle ensemble, \(K_s\) is introduced. The accompanying tripod (Dreibein) of the reference orbit spans a local curvilinear right handed system \((x,y,s)\). The local \(s\)-axis is the tangent to the reference orbit. The two other axes are perpendicular to the reference orbit and are labelled \(x\) (in the bend plane) and \(y\) (perpendicular to the bend plane).

Figure 28.3: Illustration of \(K_\text{sc}\) and \(K_s\)

Both coordinate systems are described in Figure 28.3.

28.5.5 Design or Reference Orbit

The geometric placement model can contain straight sections and circular arcs. The OrbitThreader reference orbit is obtained by integrating the design particle through the active external fields. Fringe fields and overlapping fields can therefore make the tracked reference orbit differ from the geometric placement curve.

28.5.6 Compatibility Mode

Current LINE placement supports either ELEMEDGE placement for every element or explicit six-dimensional poses for every element. Mixing these placement conventions within a beamline is rejected. ELEMEDGE placement uses the geometric bend layout; explicit poses specify the spatial layout directly.

OPTION, IDEALIZED=... is parsed, but the current placement and tracking implementation does not read this setting. It therefore does not select a fringe-field correction to the placement path length.

28.5.7 Orbit Threader and Autophasing

The OrbitThreader integrates a design particle through the lattice and builds an interval-based occupancy map (IndexMap). If autophasing is enabled, OrbitThreader invokes the cavity autophaser on first encounter with supported RFCAVITY and TRAVELINGWAVE elements. Cavities with APVETO retain their configured phase. See the autophasing appendix. The multi map structure speeds up the search for elements that influence the particles at a given position in 3D space by minimizing the looping over elements when integrating an ensemble of particles. For each time step, IndexMap returns a set of elements \(\mathcal{S}_{\text{e}} \subset {e_0 \ldots e_n}\) in case of the example given in Figure 28.2. An implicit drift is modelled as an empty set \(\emptyset\). The IndexMap therefore represents an occupancy model on the reference coordinate: each interval stores the set of elements whose field-support extents are active on that interval. This is distinct from the geometric placement of the corresponding element bodies. In overlapping regions the design particle sees the sum of the active external fields, and the reference path is determined by integrating this combined field.

28.6 Flow Diagram of OPALX

Figure 28.4: Schematic workflow of OPALX’s execute method.

A regular time step in OPALX is sketched in Figure 28.4. In order to compute the coordinate system transformation from the reference coordinate system \(K_s\) to the local coordinate systems \(K'_n\) we join the transformation from floor coordinate system \(K\) to \(K'_n\) to the transformation from \(K_s\) to \(K\). All computations of rotations which are involved in the computation of coordinate system transformations are performed using quaternions. The resulting quaternions are then converted to the appropriate matrix representation before applying the rotation operation onto the particle positions and momenta.

As shown in Figure 28.4, particle trajectories are integrated and six-dimensional phase-space statistics are computed in the reference coordinate system.

28.7 Multipoles in different Coordinate systems

In the following sections there are three models presented for the fringe field of a multipole. The first one deals with a straight multipole, while the second one treats a curved multipole, both starting with a power expansion for the magnetic field. The last model tries to be different by starting with a more compact functional form of the field which is then adapted to straight and curved geometries.

28.7.1 Fringe field models

(for a straight multipole)

Most accelerator modeling codes use the hard-edge model for magnets - constant Hamiltonian. Real magnets always have a smooth transition at the edges - fringe fields. To obtain a multipole description of a field we can apply the theory of analytic functions.

\[\begin{aligned} \nabla \cdot \mathbf{B} & = 0 \Rightarrow \exists \quad \mathbf{A} \quad \text{with} \quad \mathbf{B} = \nabla \times \mathbf{A} \\ \nabla \times \mathbf{B} & = 0 \Rightarrow \exists \quad V \quad \text{with} \quad \mathbf{B} = - \nabla V \end{aligned}\]

Assuming that \(A\) has only a non-zero component \(A_s\) we get

\[\begin{aligned} B_x & = - \frac{\partial V}{\partial x} = \frac{\partial A_s}{\partial y} \\ \\ B_y & = - \frac{\partial V}{\partial y} = - \frac{\partial A_s}{\partial x} \end{aligned}\]

These equations are just the Cauchy-Riemann conditions for an analytic function \(\tilde{A} (z) = A_s (x, y) + i V(x,y)\). So the complex potential is an analytic function and can be expanded as a power series

\[\tilde{A} (z) = \sum_{n=0}^{\infty} \kappa_n z^n, \quad \kappa_n = \lambda_n + i \mu_n\]

with \(\lambda_n, \mu_n\) being real constants. It is practical to express the field in cylindrical coordinates \((r, \varphi, s)\)

\[\begin{aligned} x & = r \cos \varphi \quad y = r \sin \varphi \\ z^n & = r^n ( \cos n \varphi + i \sin n \varphi ) \end{aligned}\]

From the real and imaginary parts of the complex-potential expansion, we obtain

\[\begin{aligned} V(r, \varphi) & = \sum_{n=0}^{\infty} r^n ( \mu_n \cos n \varphi + \lambda_n \sin n \varphi ) \\ A_s (r, \varphi) & = \sum_{n=0}^{\infty} r^n ( \lambda_n \cos n \varphi - \mu_n \sin n \varphi ) \end{aligned}\]

Taking the gradient of \(-V(r, \varphi)\) we obtain the multipole expansion of the azimuthal and radial field components, respectively

\[\begin{aligned} B_{\varphi} & = - \frac{1}{r} \frac{\partial V}{\partial \varphi} = - \sum_{n=0}^{\infty} n r^{n-1} ( \lambda_n \cos n \varphi - \mu_n \sin n \varphi ) \\ B_r & = - \frac{\partial V}{\partial r} = - \sum_{n=0}^{\infty} n r^{n-1} ( \mu_n \cos n \varphi + \lambda_n \sin n \varphi ) \end{aligned}\]

Furthermore, we introduce the normal multipole coefficient \(b_n\) and skew coefficient \(a_n\) defined with the reference radius \(r_0\) and the magnitude of the field at this radius \(B_0\) (these coefficients can be a function of s in a more general case as it is presented further on).

\[b_n = - \frac{n \lambda_n}{B_0} r_0^{n-1} \qquad a_n = \frac{n \mu_n}{B_0} r_0^{n-1}\]

\[\begin{aligned} B_{\varphi}(r, \varphi) & = B_0 \sum_{n=1}^{\infty} ( b_n \cos n \varphi+ a_n \sin n \varphi ) \left( \frac{r}{r_0} \right) ^{n-1} \\ B_r (r, \varphi) & = B_0 \sum_{n=1}^{\infty} ( -a_n \cos n \varphi+ b_n \sin n \varphi ) \left( \frac{r}{r_0} \right) ^{n-1} \end{aligned}\]

To obtain a model for the fringe field of a straight multipole, a proposed starting solution for a non-skew magnetic field is

\[\begin{aligned} V & = \sum_{n=1}^{\infty} V_n (r,z) \sin n \varphi \\ V_n & = \sum_{k=0}^{\infty} C_{n,k}(z) r^{n+2k} \end{aligned}\]

It is straightforward to derive a relation between coefficients

\[\frac{1}{r}\frac{\partial}{\partial r}\left(r\frac{\partial V_n}{\partial r}\right) + \frac{\partial^2 V_n}{\partial z^2} - \frac{n^2 V_n}{r^2} = 0.\]

\[V_n = \sum_{k=0}^{\infty} C_{n,k}(z) r^{n+2k}\]

\[\Rightarrow \sum_{k=0}^{\infty} \left[ r^{n+2(k-1)} \left[ (n+2k)^2 - n^2 \right] C_{n,k}(z) + r^{n+2k} \frac{\partial^2 C_{n,k}(z)}{\partial z^2} \right] = 0\]

By identifying the term in front of the same powers of \(r\) we obtain the recurrence relation

\[C_{n,k}(z) = - \frac{1}{4k(n+k)} \frac{d^2 C_{n,k-1}} {dz^2}, k = 1,2, \ldots\]

The solution of the recursion relation becomes

\[C_{n,k} (z) = (-1)^k \frac{n!}{2^{2k} k! (n+k)!} \frac{d^{2k} C_{n,0}(z)}{dz^{2k}}\]

Therefore

\[V_n = - \left( \sum_{k=0}^{\infty} (-1)^{k+1} \frac{n!}{2^{2k} k! (n+k)!} C_{n, 0}^{(2k)}(z) r^{2k} \right) r^n\]

The transverse components of the field are

\[\begin{aligned} B_r & = \sum_{n=1}^{\infty} g_{rn} r^{n-1} \sin n \varphi \\ B_{\varphi} & = \sum_{n=1}^{\infty} g_{\varphi n} r^{n-1} \cos n \varphi \end{aligned}\]

where the following gradients determine the entire potential and can be deduced from the function \(C_{n,0}(z)\) once the harmonic \(n\) is fixed.

\[\begin{aligned} g_{rn} (r,z) & = \sum_{k=0}^{\infty} (-1)^{k+1} \frac{n! (n+2k)}{2^{2k} k! (n+k)!} C_{n,0}^{(2k)}(z)r^{2k} \\ g_{ \varphi n} (r,z) & = \sum_{k=0}^{\infty} (-1)^{k+1} \frac{n!n}{2^{2k} k! (n+k)!} C_{n,0}^{(2k)}(z)r^{2k} \end{aligned}\]

The z-directed component of the field can be expressed in a similar form

\[\begin{aligned} B_z & = - \frac{\partial V}{\partial z} = \sum_{n=1}^{\infty} g_{zn} r^n \sin n \varphi \\ g_{zn} & = \sum_{k=0}^{\infty} (-1)^{k+1} \frac{n!}{2^{2k} k! (n+k)!} C_{n,0}^{(2k+1)}(z) r^{2k} \end{aligned}\]

The gradient functions \(g_{rn}, g_{\varphi n}, g_{zn}\) are obtained from

\[\begin{aligned} B_{r,n} & = - \frac{\partial V_n}{\partial r} \sin n \varphi = g_{rn} r^{n-1} \sin n \varphi \\ B_{\varphi,n} & = - \frac{n}{r} V_n \cos n \varphi = g_{\varphi n} r^{n-1} \cos n \varphi \\ B_{z,n} & = - \frac{\partial V_n}{\partial z} \sin n \varphi = g_{zn} r^{n} \sin n \varphi \end{aligned}\]

One preferred model to approximate the gradient profile on the central axis is the k-parameter Enge function

\[\begin{aligned} C_{n,0}(z) & = \frac{G_0}{1+exp[P(d(z))]}, \quad G_0 = \frac{B_0}{r_0^{n-1}} \\ P(d) & = C_0 + C_1 \left( \frac{d}{\lambda} \right) + C_2 \left( \frac{d}{\lambda} \right)^2 + \ldots + C_{k-1} \left( \frac{d}{\lambda} \right)^{k-1} \end{aligned}\]

where \(d(z)\) is the distance to the field boundary and \(\lambda\) characterizes the fringe field length.

28.7.2 Fringe field of a curved multipole

(fixed radius)

We consider the Frenet-Serret coordinate system \((\hat{\mathbf{x}}, \hat{\mathbf{s}}, \hat{\mathbf{z}})\) with the radius of curvature \(\rho\) constant and the scale factor \(h_s = 1 + x/\rho\). A conversion to these coordinates implies that

\[\begin{aligned} \nabla \cdot \mathbf{B} & = \frac{1}{h_s} \left[ \frac{\partial (h_s B_x )}{\partial x} + \frac{\partial B_s}{\partial s} + \frac{\partial (h_s B_z )}{\partial z} \right] \\ \\ \nabla \times \mathbf{B} & = \frac{1}{h_s} \left[ \frac{\partial B_z}{\partial s} - \frac{\partial (h_s B_s )}{\partial z} \right] \hat{\mathbf{x}} + \left[ \frac{\partial B_x}{\partial z} - \frac{\partial B_z}{\partial x} \right] \hat{\mathbf{s}} + \frac{1}{h_s} \left[ \frac{\partial (h_s B_s)}{\partial x} - \frac{\partial B_x}{\partial s} \right] \hat{\mathbf{z}} \end{aligned}\]

To simplify the problem, consider multipoles with mid-plane symmetry, i.e.

\[B_z (z) = B_z (-z) \qquad B_x (z) = - B_x (-z) \qquad B_s (z) = - B_s (-z)\]

The most general form of the expansion is

\[\begin{aligned} B_z & = \sum_{i,k=0}^{\infty} b_{i,k} x^i z^{2k} \\ B_x & = z \sum_{i,k=0}^{\infty} a_{i,k} x^i z^{2k} \\ B_s & = z \sum_{i,k=0}^{\infty} c_{i,k} x^i z^{2k} \end{aligned}\]

Maxwell’s equations \(\nabla \cdot \mathbf{B} = 0\) and \(\nabla \times \mathbf{B} = 0\) in the above coordinates yield

\[\frac{\partial}{\partial x} \left( (1+x/ \rho) B_x \right) + \frac{\partial B_s}{\partial s} + (1+x/ \rho) \frac{\partial B_z}{\partial z} = 0\]

\[\begin{aligned} \frac{\partial B_z}{\partial s} & = (1+x/ \rho) \frac{\partial B_s}{\partial z} \\ \\ \frac{\partial B_x}{\partial z} & = \frac{\partial B_z}{\partial x} \\ \\ \frac{\partial B_x}{\partial s} & = \frac{\partial}{\partial x} \left( (1+x/ \rho) B_s \right) \end{aligned}\]

The substitution of the general-form equation into Maxwell’s equations allows for the derivation of recursion relations. Maxwell’s equations gives

\[\sum_{i,k=0}^{\infty} a_{i,k} (2k+1) x^i z^{2k} = \sum_{i,k=0}^{\infty} b_{i,k} i x^{i-1} z^{2k}\]

Equating the powers in \(x^i z^{2k}\)

\[a_{i,k} = \frac{i+1}{2k+1} b_{i+1,k}\]

A similar result is obtained from Maxwell’s equations

\[\begin{aligned} \sum_{i,k=0}^{\infty} \partial_s b_{i,k} x^i z^{2k} & = \left( 1+ \frac{x}{\rho} \right) \sum_{i,k=0}^{\infty} c_{i,k} (2k+1) x^i z^{2k} \\ \Rightarrow c_{i,k} & + \frac{1}{\rho} c_{i-1,k} = \frac{1}{2k+1} \partial_s b_{i,k} \end{aligned}\]

The last equation from \(\nabla \times \mathbf{B} = 0\) should be consistent with the two recursion relations obtained. Maxwell’s equations implies

\[\sum_{i,k=0}^{\infty} \left[ \frac{i+1}{\rho} c_{i,k} x^i + c_{i,k} i x^{i-1} \right] z^{2k+1} = \sum_{i,k=0}^{\infty} \partial_s a_{i,k} x^i z^{2k+1}\]

\[\Rightarrow \frac{\partial_s a_{i,k}}{i+1} = \frac{1}{\rho} c_{i,k} + c_{i+1,k}\]

This results follows directly from the a-factor relation and the c-factor relation; therefore the relations are consistent. Furthermore, the last required relations is obtained from the divergence of B

\[\sum_{i,k=0}^{\infty} \left[ \frac{a_{i,k} x^i z^{2k+1}}{\rho} + i a_{i,k} x^{i-1} z^{2k+1} + \frac{i a_{i,k} x^i z^{2k+1}}{\rho} + \partial_s c_{i,k} x^i z^{2k+1} + 2kb_{i,k}x^i z^{2k-1} \right] = 0\]

\[\Rightarrow \partial_s c_{i,k} + \frac{2(k+1)}{\rho} b_{i-1,k+1} + 2(k+1) b_{i,k+1} + \frac{1}{\rho} a_{i,k} + (i+1) a_{i+1,k} + \frac{i}{\rho} a_{i,k} = 0\]

Using the relation (the a-factor relation) to replace the \(a\) coefficients with \(b\)’s we arrive at

\[\partial_s c_{i,k} + \frac{(i+1)^2}{\rho (2k+1)} b_{i+1,k} + \frac{(i+1)(i+2)}{2k+1} b_{i+2,k} + \frac{2(k+1)}{\rho} b_{i-1,k+1} + 2(k+1) b_{i,k+1} = 0\]

All the coefficients above can be determined recursively provided the field \(B_z\) can be measured at the mid-plane in the form

\[B_z(z=0) = B_{0,0} + B_{1,0}x + B_{2,0} x^2 + B_{3,0} x^3 + \ldots\]

Here \(B_{i,0}\) are functions of \(s\) that describe the longitudinal variation of each multipole term \(x^i\). For a dipole magnet, the coefficient \(B_{0,0}(s)\) can be modeled with an Enge or \(\tanh\) profile.

28.7.3 Fringe field of a curved multipole

(variable radius of curvature)

This subsection presents formal background. The current MULTIPOLET implementation selects straight or constant-radius geometry; a variable-radius implementation is not available. Although the parser accepts VARRADIUS, that flag does not select a variable-radius field model.

The difference between this case and the above is that \(\rho\) is now a function of \(s\), \(\rho(s)\). We can obtain the same result starting with the same functional forms for the field (the general-form equation). The result of the previous section also holds in this case since no derivative \(\frac{\partial}{\partial s}\) is applied to the scale factor \(h_s\). For a reference particle with fixed mechanical momentum magnitude \(p_0\) in a planar transverse magnetic field, the magnitude of the local orbit radius is

\[|\rho(s)|=\frac{p_0}{|q|\,|B_z(0,0,s)|}=\frac{p_0}{|q|\,|b_{0,0}(s)|}.\]

Here \(p_0\) is in SI momentum units. This relates orbit curvature to field strength; it does not define the implemented constant-radius magnet geometry.

28.7.4 Fringe field of a multipole

This is a different, more compact treatment The derivation is more clear if we gather the variables together in functions. We assume again mid-plane symmetry and that the z-component of the field in the mid-plane has the form

\[B_z (x, z=0, s) = T(x) S(s)\]

where \(T(x)\) is the transverse field profile and \(S(s)\) is the fringe field. The symmetry condition \(B_z(z) = B_z(-z)\) requires \(\frac{\partial \psi}{\partial z}\) to be an even function in \(z\) when the field is represented using a scalar potential \(\psi\). Therefore, \(\psi\) is an odd function in z and can be written as

\[\psi = z f_0(x,s) + \frac{z^3}{3!} f_1(x,s) + \frac{z^5}{5!} f_2(x,s) + \ldots\]

In this subsection, use \(\mathbf B=+\nabla\psi\), the opposite sign convention to the earlier definition \(\mathbf B=-\nabla V\). The mid-plane field then gives \(f_0(x,s)=T(x)S(s)\). In a current-free region, Maxwell’s equations require \(\nabla^2\psi=0\), or explicitly

\[\frac{\partial}{\partial x} \left( h_s \frac{\partial \psi}{\partial x} \right) + \frac{\partial}{\partial s} \left( \frac{1}{h_s} \frac{\partial \psi}{\partial s} \right) + \frac{\partial}{\partial z} \left( h_s \frac{\partial \psi}{\partial z} \right) = 0\]

For a straight multipole \(h_s = 1\). Laplace’s equation becomes

\[\sum_{n=0}^{\infty} \frac{z^{2n+1}}{(2n+1)!} \left[\partial_x^2 f_n(x,s)+\partial_s^2 f_n(x,s)\right] + \sum_{n=1}^{\infty} f_n(x,s)\frac{z^{2n-1}}{(2n-1)!}=0.\]

By equating powers of \(z\) we obtain the recursion relation

\[f_{n+1}(x,s) = - \left( \partial_x^2 + \partial_s^2 \right) f_n(x,s)\]

The general expression for any \(f_n(x,s)\) is then obtained from the mid-plane field by

\[\begin{aligned} f_n(x,s) & = (-1)^n \left( \partial_x^2 + \partial_s^2 \right)^n f_0(x,s) \\ \\ f_n(x,s) & = (-1)^n \sum_{i=0}^n \binom{n}{i}T^{(2i)}(x) S^{(2n-2i)}(s) \end{aligned}\]

For a curved multipole of constant radius \(h_s = 1 + \frac{x}{\rho} \quad \text{with} \quad \rho = const.\) The corresponding Laplace’s equation is

\[\left( \frac{1}{\rho h_s} \partial_x + \partial_x^2 + \partial_z^2 + \frac{\partial_s^2}{h_s^2} \right) \psi = 0\]

Again we substitute with the functional form of the potential to get the recursion

\[\begin{aligned} f_{n+1}(x,s) & = - \left[ \frac{1}{\rho + x} \partial_x + \partial_x^2 + \frac{\partial_s^2}{(1+x/ \rho)^2} \right] f_n(x,s) \\ \\ f_n(x,s) & = (-1)^n \left[ \frac{1}{\rho + x} \partial_x + \partial_x^2 + \frac{\partial_s^2}{(1+x/ \rho)^2} \right]^n f_0(x,s) \end{aligned}\]

Finally consider what changes for \(\rho = \rho (s)\). Laplace’s equation is

\[\left[ \frac{1}{\rho h_s} \partial_x + \partial_x^2 + \partial_z^2 + \frac{\partial_s^2}{h_s^2} + \frac{x}{\rho^2 h_s^3} (\partial_s \rho) \partial_s \right] \psi = 0\]

The last step is again the substitution to get

\[\begin{aligned} f_{n+1}(x,s) & = - \left[ \frac{\partial_x}{\rho h_s} + \partial_x^2 + \partial_z^2 + \frac{1}{h_s^2}\partial_s^2 + \frac{x}{\rho^2 h_s^3} (\partial_s \rho) \partial_s \right] f_n(x,s) \\ \\ f_{n}(x,s) & = (-1)^n \left[ \frac{\partial_x}{\rho h_s} + \partial_x^2 + \partial_z^2 + \frac{\partial_s^2}{h_s^2} + \frac{x}{\rho^2 h_s^3} (\partial_s \rho) \partial_s \right]^n f_0(x,s) \end{aligned}\]

For the theoretical field profile \(T_{\mathrm{dipole}}(x)=B_0\), the same fixed-momentum planar-orbit relation gives

\[|\rho(s)|=\frac{p_0}{|q|\,|B_0 S(s)|}.\]

The relation applies where \(B_0S(s)\ne0\); the radius becomes unbounded as the field vanishes. It is not an implemented variable-radius MULTIPOLET model.

28.7.5 Cyclotron segment diagnostics

Native PROBE recording is available in cyclotron and supported RING particle tracking, including scaling FFAs. It is passive and works with or without space charge. All supported rings produce crossing records; radial histograms and per-turn radial means are cyclotron-only. Use fresh runs: diagnostic histories/output rewind do not support restart or continuation.

The PROBE model uses the accepted-endpoint interpolation above in both directions. Its legacy endpoint names \((XSTART,YSTART)\) represent laboratory \((x,z)\); the laboratory \(y\) coordinate is vertical. Let \(\mathbf a=(x_a,0,z_a)\) and \(\mathbf b=(x_b,0,z_b)\) be the segment endpoints [m], \(\mathbf d=\mathbf b-\mathbf a\), and \(\mathbf n=(-d_z,0,d_x)\). After finding a transverse plane crossing \(\mathbf r_c\), accept it only if

\[ 0\leq\frac{(\mathbf r_c-\mathbf a)\cdot\mathbf d}{\mathbf d\cdot\mathbf d}\leq1. \]

Both directions use a 1 nm arming distance. The vertical coordinate is unrestricted. Histories retain laboratory endpoints while the bunch frame changes; particle attributes carry the history through compaction and MPI migration. Only crossing records are transferred from the device for output. The diagnostic never changes physical particle state, fields, reference advancement, or accepted integration intervals.

In cyclotron tracking only, radial histograms use \(r_c=\sqrt{x_c^2+z_c^2}\) and bin index \(\lfloor(r_c-r_{\min})/\Delta r\rfloor\), where \(r_{\min}\) is the minimum radius on the finite segment and \(\Delta r=STEP\) after conversion to metres. With \(r_{\max}\) the maximum endpoint radius, the number of bins is \(\lceil(r_{\max}-r_{\min})/\Delta r\rceil+1\); the extra bin includes an exact upper boundary. Histogram output converts lengths to mm.

The .peaks observable is the arithmetic mean radius of hits assigned to each reference turn, with no charge weighting or histogram peak fit. An independent reference counter uses the launch section and forward reference momentum; turns start at zero. Hits in an accepted interval use the reference turn at the start of that interval. Near the reference return, this assigns crossings only to accepted-step resolution; reduce DT when turn grouping matters there. Collective diagnostic reductions may differ in their last bits across MPI partitions, but must preserve crossing IDs and integer hit counts.

The interpolation error is \(O(\Delta t^2)\) for smooth transverse crossings; no method based only on two endpoints can detect unresolved multiple crossings. An interval containing an RF kick does not satisfy the smooth-momentum assumption, so probes should not coincide with SINGLEGAP planes. Diagnostic history and output rewind are not checkpointed in this implementation.