This chapter documents element models whose geometry, field support, or runtime semantics require more than the generic placement conventions.
Analytic sector and rectangular bends
The OPALX SBEND and RBEND are field-based bend models. The reference particle and the bunch are integrated through a magnetic field that is evaluated in the element frame; bends are not tracked with transfer matrices. The field has dipole and quadrupole terms, an Enge fringe field when HGAP > 0, and a correction for the vertical edge focusing.
Coordinates
The placed pose of a bend is the entrance frame used by its field model. For SBEND, the local \(z\) axis follows the design-orbit tangent at the entrance. For RBEND, it is normal to the entrance pole face and follows the straight magnet body; it generally differs from the incoming orbit tangent. ELEMEDGE derives this element frame from the reference geometry, while X…PSI specify its explicit pose.
SBEND: positions are converted to bend coordinates \((x, y, s)\), where \(s\) is the arc length along the design orbit, from 0 at the entrance to \(L\) at the exit, and \(x\) is the radial offset from the design orbit. The field is evaluated in these coordinates and turned back into the entrance frame. The pole faces are perpendicular to the design orbit.
RBEND: the field is evaluated in the straight frame of the magnet body, with \(z\) from 0 at the entrance face to \(L\) at the exit face. The design orbit crosses the faces at the pole-face angles E1 and E2. If neither is specified, both are ANGLE/2. If one is specified, the other is derived so that E1 + E2 = ANGLE; specifying both requires that sum. Explicit pole-face angles require \(L>0\), \(|\mathrm{ANGLE}|<\pi\), and \(|E_1|,|E_2|<\pi/2\).
Field strength
The dipole strength is \[
B_0 = \frac{P_0}{c\,q}\,K_0 ,
\] where \(P_0\) is the global P0 (GeV/\(c\), default 1) and \(q\) the reference charge in units of \(e\). With these input units, the signed magnetic rigidity is \[
(B\rho)_0[\mathrm{T\,m}]
=\frac{P_0[\mathrm{GeV}/c]}{0.299792458\,q}.
\] Thus \(B_0=(B\rho)_0K_0\) and \(g=(B\rho)_0K_1\). In expressions using \(P_0/c\), the implementation first converts the input momentum from GeV/\(c\) to eV/\(c\) and uses \(c\) in m/s. Dividing by \(q\) makes the bend direction independent of the charge sign. If K0 is not given, it is derived from ANGLE \(\theta\): \[
K_0^{\mathrm{SBEND}} = \frac{\theta}{L},
\qquad
K_0^{\mathrm{RBEND}} = \frac{2\sin(\theta/2)}{L}
\quad\text{or}\quad \frac{\theta}{L_{\mathrm{arc}}}\ \text{with}\ E_1, E_2,
\] where \(L_{\mathrm{arc}}\) is the length of the design orbit between the two faces. A given K0 replaces this value. The quadrupole gradient is \(g = P_0 K_1/(c\,q)\), and the skew terms follow from K0S and K1S in the same way. K2, K3, K2S and K3S are parsed but not applied.
For RBEND, a positive DESIGNENERGY \(T_d\) (MeV) scales the field by \(p(T_d)/P_0\), with \(p(T_d) = \sqrt{T_d(T_d + 2mc^2)}/c\) for the beam’s rest mass. Form the ratio \(p(T_d)/P_0\) with both momenta in the same units; DESIGNENERGY is entered in MeV while P0 is entered in GeV/\(c\). SBEND rejects DESIGNENERGY. P0 should therefore be set to the reference momentum of the beam.
Longitudinal profile
With the full gap \(g_{\mathrm{gap}} = 2\,\)HGAP (or GAP for RBEND), the field is multiplied by an Enge function of the distance \(d\) past a pole face (\(d < 0\) inside the magnet), \[
F(d) = \frac{1}{1 + \exp\!\left(\sum_{i=0}^{5} c_i\,(d/g_{\mathrm{gap}})^i\right)},
\] with the OPAL default coefficients \(c = (0.478959,\ 1.911289,\ -1.185953,\ 1.630554,\ -1.082657,\ 0.318111)\). \(F \to 1\) inside the magnet, \(F \to 0\) outside, and \(F \approx 0.38\) at the face. Of the entrance and exit values, the smaller one is used. The field extends \(5\,g_{\mathrm{gap}}\) before the entrance face and past the exit face; beyond that it is zero. With HGAP = 0 the edge is hard: \(F = 1\) on \([0, L)\) and the field is zero elsewhere.
RBEND can instead read a 1DProfile1 profile through FMAPFN; its amplitude is then set so that the design orbit bends by ANGLE. This is a separate profile-dipole model: explicitly specifying K0, K0S, K1, K1S, K2, K2S, K3, K3S or FINT with that profile is rejected, even when the explicit value is zero. Its fringe field comes from the profile derivatives; the native finite-gap correction below is not added. See the field-map appendix.
Field in and near the magnet
For the native analytic normal terms, let \(F'\) and \(F''\) be derivatives with respect to the longitudinal field coordinate (\(s\) for SBEND, \(z\) for RBEND): \[
\begin{aligned}
B_y &= B_0\left(F - \tfrac12 F''\,y^2\right) + g\,F\,x,\\
B_s &= B_0\,F'\,y,\\
B_x &= g\,F\,y + C\,F'\,y .
\end{aligned}
\] The \(F''\) and \(F'\) terms keep the dipole fringe field free of sources to first order in \(y\). They give the geometric edge focusing, including the \(h\tan E\) term of a rotated pole face.
The last term, with coefficient \(C\), adds the finite-gap correction to the vertical edge focusing. With signed curvature \(h = \theta/L_{\mathrm{arc}}\) and pole-face angle \(E\), \[
\psi = h\,\frac{g_{\mathrm{gap}}}{2}\,F_{\mathrm{int}}\,\frac{1 + \sin^2 E}{\cos E},
\qquad
\Delta k_y = h\left[\tan E - \tan(E - \psi)\right],
\] For a nonzero curvature, define the profile span \[
D=\left|F(-5g_{\mathrm{gap}})-F(5g_{\mathrm{gap}})\right|.
\] The coefficient multiplying the longitudinal derivative \(F'\) is \[
C=\begin{cases}
+(B_0/h)\,\Delta k_{y,\mathrm{in}}/D,&\text{entrance-limited profile},\\
-(B_0/h)\,\Delta k_{y,\mathrm{out}}/D,&\text{exit-limited profile}.
\end{cases}
\] The opposite signs compensate for the rising entrance and falling exit profiles. \(F_{\mathrm{int}}\) is FINT. For SBEND, \(E=0\); for RBEND, use E1 at the entrance and E2 at the exit. The native correction is zero when FINT = 0, the full gap is zero, or the reference curvature is zero.
Aperture
With HGAP > 0 the bend gets a rectangular aperture of half-height HGAP; HAPERT sets its horizontal half-width, which is otherwise unlimited. An APERTURE string may replace HAPERT if its vertical half-width does not exceed HGAP. Particles outside the aperture get no field, and are removed if they are inside the body, \(0 \le s < L\).
SBEND and RBEND class structure
The current implementation splits bend handling into a parser-facing object layer and a runtime representation layer. OpalSBend and OpalRBend inherit the common bend attributes and update logic from OpalBend, then instantiate and configure SBendRep and RBendRep respectively.
OpalSBend and OpalRBend read the input and set up SBendRep and RBendRep. These hold the Geometry and the field coefficients; SBend and RBend evaluate the field with the functions in BendFieldModel.
Multipole family
The OPALX MULTIPOLE element is a straight magnet with normal and skew multipole terms from quadrupole to decapole. QUADRUPOLE uses the same runtime element with only the quadrupole term. There is no separate SEXTUPOLE element; a sextupole is a MULTIPOLE with only its order-2 entry set.
Field expansion and conventions
The field is \[
B_y + i B_x = \sum_{m=0}^{4} (B_m - i A_m) (x + i y)^m,
\] where:
- \(m = 0\) is the dipole term, \(m = 1\) the quadrupole, \(m = 2\) the sextupole, \(m = 3\) the octupole and \(m = 4\) the decapole,
- \(B_m\) are normal coefficients,
- \(A_m\) are skew coefficients.
The class Multipole (src/AbsBeamline/Multipole.h) uses the same indexing: n = 0 is the dipole, n = 1 the quadrupole, and so on up to MAX_MP_ORDER - 1 = 4.
For the quadrupole and sextupole terms the transverse field is:
\[
\text{normal quadrupole:}\qquad
B_x = B_1\,y,\qquad
B_y = B_1\,x,
\]
\[
\text{skew quadrupole:}\qquad
B_x = -A_1\,x,\qquad
B_y = A_1\,y,
\]
\[
\text{normal sextupole:}\qquad
B_x = 2 B_2\,x y,\qquad
B_y = B_2 (x^2 - y^2),
\]
\[
\text{skew sextupole:}\qquad
B_x = -A_2 (x^2 - y^2),\qquad
B_y = 2 A_2\,x y.
\]
The same function, Multipole::computeField, evaluates the field for the particles and for the reference particle, so both see all orders.
MULTIPOLE
The parser-side element OpalMultipole (src/Elements/OpalMultipole.cpp) accepts the coefficient arrays:
KN: normal normalized strengths \(K_n\), in \(\mathrm m^{-(n+1)}\)
DKN: normal strength errors
KS: skew normalized strengths
DKS: skew strength errors
Each array may have at most five entries, and the first (dipole) entry of each must be zero. Before combining coefficients, DKN is resized to the length of KN, and DKS to the length of KS: missing error entries become zero, and excess error entries are discarded. To give an error to a nominally zero higher-order term, include its zero entry in the corresponding nominal array. MULTIPOLE is placed as a straight element, so a dipole term would steer the beam away from it; use SBEND or RBEND instead.
At update time the strengths and their errors are added and converted to field coefficients with the rigidity \(P_0/c\) from the global P0 (GeV/\(c\), default 1). With P0 in GeV/\(c\), the rigidity factor used here is \[
\mathcal R_0[\mathrm{T\,m}]
=\frac{P_0[\mathrm{GeV}/c]}{0.299792458}.
\] The implementation obtains this factor by converting P0 to eV/\(c\) before dividing by \(c\) in m/s. Thus the following \(P_0/c\) factors denote \(\mathcal R_0\): \[
B_n = \frac{P_0}{c}\,\frac{K_n + \Delta K_n}{n!},
\qquad
A_n = \frac{P_0}{c}\,\frac{K_{s,n} + \Delta K_{s,n}}{n!}.
\] The charge of the beam does not enter: a positive \(K_1\) focuses positive particles horizontally and defocuses negative ones.
OpalMultipole sets these coefficients on a MultipoleRep (src/BeamlineCore/MultipoleRep.h), which also holds the element length in its Geometry. The field is applied for \(0 \le z < L\) and only inside the APERTURE. Although the inherited help text mentions integrated strengths for L = 0, a zero-length MULTIPOLE has no field.
QUADRUPOLE
The parser-side OpalQuadrupole (src/Elements/OpalQuadrupole.cpp) creates the same MultipoleRep as MULTIPOLE, but takes scalar attributes:
K1, DK1: normal quadrupole strength and error
K1S, DK1S: skew quadrupole strength and error
They are stored as \[
\texttt{KN} = \{0, K_1\},\qquad
\texttt{KS} = \{0, K_{1s}\},
\] with the errors added in the same way as for MULTIPOLE.
Sextupole and higher orders
A sextupole is a MULTIPOLE with \[
\texttt{KN} = \{0, 0, K_2\},\qquad
\texttt{KS} = \{0, 0, K_{2s}\},
\] and octupole and decapole terms follow at indices 3 and 4.
A MULTIPOLE with terms above the quadrupole cannot be used with the boundary refinement of analytic RING tracking.
Class structure
The current parser-side and runtime-side structure is shown below.
Ideal RFCAVITY
RFCAVITY, TYPE="IDEAL" prescribes a uniform longitudinal electric field in its straight element frame. Let \(E_0\) and \(\delta E_0\) denote VOLT and DVOLT in MV/m, \(f\) denote FREQ in MHz, and \(\phi\) and \(\delta\phi\) denote LAG and DLAG in radians. With \(L\) in metres and \(t\) in seconds,
\[
\mathbf E_{\mathrm{RF}}(\mathbf r,t)
=\widehat{\mathbf z}\,10^6(E_0+\delta E_0)
\cos\!\left(2\pi\,10^6 f t+\phi+\delta\phi\right)
\chi_{\mathcal C}(\mathbf r),
\qquad \mathbf B_{\mathrm{RF}}=0.
\]
The support \(\mathcal C\) consists of local \(0\le z<L\) inside the configured APERTURE; without an aperture it has no transverse limit. The field is added to existing fields. Particle removal follows the separate aperture rules. The reference particle uses \(\delta E_0=\delta\phi=0\). The input guide gives an example, parameter restrictions, and automatic-phasing controls.
This model has abrupt longitudinal edges, no fringe fields, no transverse RF focusing, and no electromagnetic cavity-mode solution. Ordinary drift–kick–drift tracking evaluates its field at the physical midpoint \(t+h/2\) of a step of duration \(h\).
For a particle with charge \(q\) in C and approximately constant speed \(v\) through the cavity, define \(\omega=2\pi\,10^6 f\). The energy gain is
\[
\Delta K\simeq q\,10^6(E_0+\delta E_0)L\,
\operatorname{sinc}\!\left(\frac{\omega L}{2v}\right)
\cos(\omega t_c+\phi+\delta\phi),
\qquad \operatorname{sinc}(a)=\frac{\sin a}{a},
\]
in joules, where \(t_c\) is the time at the cavity centre and \(\operatorname{sinc}(0)=1\). This is a constant-speed approximation; tracking integrates the field through the finite cavity. VOLT specifies the peak electric-field amplitude in MV/m, independent of \(L\). The nominal peak spatially integrated voltage is \(10^6 E_0 L\) volts. For \(f=0\) and \(\phi=0\), the nominal energy gain is \(q\,10^6 E_0 L\) joules for a full traversal.
For constant time models, VARIABLE_RF_CAVITY produces the same particle field within their common field region when its amplitude is \(E_0+\delta E_0\) in MV/m, its frequency is \(f\) in MHz, and its phase is \(\phi+\delta\phi+\pi/2\). Its sine convention and rectangular support are described below.
RF cavity with time models
VARIABLE_RF_CAVITY prescribes a uniform longitudinal electric field in its straight element frame. Let \(A(t)\) be the amplitude-model output in MV/m, \(f(t)\) the frequency-model output in MHz, and \(\phi(t)\) the phase-model output in radians, with \(t\) and the integration variable \(\tau\) in seconds. For constant or polynomial frequency models, the implemented field is
\[
\mathbf E_{\mathrm{RF}}(\mathbf r,t)
=\widehat{\mathbf z}\,10^6 A(t)\,
\sin\!\left[2\pi\,10^6\int_0^t f(\tau)\,d\tau+\phi(t)\right]
\chi_{\mathcal C}(\mathbf r),
\qquad \mathbf B_{\mathrm{RF}}=0,
\]
in V/m and T respectively. The support indicator is one on
\[
\mathcal C=\{(x,y,z):\ 0\le z<L,\ |x|\le W/2,\ |y|\le H/2\},
\]
and zero elsewhere; \(L\), \(W\), and \(H\) are the full cavity dimensions in metres. The longitudinal entrance and both transverse faces are included, while the longitudinal exit is excluded. The field is added to any existing external and self-fields. Particle-loss apertures are a separate tracking operation. The input guide describes the available time models and current integral limitations.
This is an ideal prescribed-field buncher model, without an electromagnetic cavity-mode solution, fringe fields, or transverse RF focusing. Within the ordinary drift–kick–drift integrator, the device particle kernel and host reference evaluate the field at the physical midpoint \(t+h/2\) of each step of duration \(h\). Subdividing a step changes this sampling time consistently; it does not reset the RF phase each turn. See the integration method.
For constant amplitude \(E_0=10^6A\) in V/m and angular frequency \(\omega=2\pi\,10^6f\) in rad/s, a particle with charge \(q\) in C and approximately constant speed \(v\) through the cavity gains
\[
\Delta K \simeq q E_0 L\,
\operatorname{sinc}\!\left(\frac{\omega L}{2v}\right)
\sin(\omega t_c+\phi),
\qquad \operatorname{sinc}(u)=\frac{\sin u}{u},
\]
in joules, where \(t_c\) is the time at the cavity centre. This finite transit-time formula is a useful weak-kick approximation, not a replacement for integrating the reference when its speed changes appreciably. A nonaccelerating synchronous orbit requires zero net RF energy gain per turn when there are no other energy gains or losses, and an RF frequency \(f_{\mathrm{RF}}=h_{\mathrm{RF}}/T_{\mathrm{rev}}\) in Hz, where \(h_{\mathrm{RF}}\) is an integer harmonic and \(T_{\mathrm{rev}}\) is its measured return time in seconds. Choose the restoring phase using the ring’s longitudinal dynamics and calibrate the finite-cavity reference motion. A chosen phase alone does not establish a self-consistent space-charge match.
The automatic maximum-energy cavity phaser does not change this element’s explicit phase model. COF remains a static magnetic, fixed-energy orbit calculation; it does not solve the RF-periodic six-dimensional synchronous orbit. Bare-orbit input and RF tracking must respect the orbit handover constraints.
MONITOR sampling
MONITOR is a passive sampling plane, without a detector-material or field model. The input guide describes its collection modes, output files, and retained timestamp conventions.
Spatial crossings
Let \(\mathbf r=(x,y,z)\) and \(\widetilde{\mathbf p}=\mathbf p/(mc)=\gamma\boldsymbol\beta\) be the particle state in the monitor frame, with \(\gamma=\sqrt{1+|\widetilde{\mathbf p}|^2}\). For a positive particle timestep \(h_k\), the predicted displacement is
\[
\Delta\mathbf r_k=c h_k\frac{\widetilde{\mathbf p}_k}{\gamma_k}.
\]
A crossing is recorded when \(z_k<0\) and \(z_k+\Delta z_k>0\). The linear intersection fraction and sampled position are
\[
\lambda_k=-\frac{z_k}{\Delta z_k},\qquad
\mathbf r_k^{\mathrm{hit}}=\mathbf r_k+\lambda_k\Delta\mathbf r_k,
\qquad z_k^{\mathrm{hit}}=0.
\]
The strict inequalities exclude exact endpoint hits and reverse crossings. The saved momentum is \(\widetilde{\mathbf p}_k\), without a momentum update at the intersection. In ordinary drift–kick–drift tracking, the stored crossing time is calculated as
\[
t_k^{\mathrm{hit}}=t_b+\frac{h}{2}+\lambda_k h_k,
\]
where \(t_b\) is the bunch time at the start of the step and \(h\) is the bunch timestep. This is a straight-drift estimate from the sampled state, not an additional integration through external or self-fields. Particle positions, momenta and crossing times are collected over the passage, rather than at one common laboratory time.
Temporal snapshots
A temporal snapshot is triggered by the reference particle’s crossing. For an ordinary full timestep \(h>0\), let \(t_m=t_{\mathrm{end}}-h/2\) and \((\mathbf r_{\mathrm{ref}},\widetilde{\mathbf p}_{\mathrm{ref}})\) be the reference state supplied at the midpoint. Define
\[
\tau=-\frac{z_{\mathrm{ref}}}{h v_{\mathrm{ref},z}},\qquad
t_{\mathrm{cross}}=t_m+\tau h,
\qquad
\mathbf v_{\mathrm{ref}}=c\frac{\widetilde{\mathbf p}_{\mathrm{ref}}}
{\sqrt{1+|\widetilde{\mathbf p}_{\mathrm{ref}}|^2}}.
\]
The snapshot origin is placed at the predicted reference intersection and its longitudinal axis is aligned with the reference momentum. If \(\mathcal T\) is the rigid transform from the current container frame to that snapshot frame, and \(Q\) its rotation, the sampled positions are
\[
\mathbf r_k^{\mathrm{snapshot}}
=\mathcal T(\mathbf r_k^{\mathrm{end}})
+\left(\tau-\frac12\right)h\,Q\mathbf v_k.
\]
Thus each particle is drifted by the same time correction from the timestep endpoint. Longitudinal particle offsets are retained: this is a bunch snapshot, not an intersection of every particle with \(z=0\). The calculation uses a rigid spatial transform and straight drift, without a Lorentz boost or an additional momentum push. The saved momentum is the current container momentum.
The current output stores \(t_{\mathrm{cross}}\) as reference TIME, but \(t_{\mathrm{end}}\) as each particle’s time. Accordingly,
\[
\texttt{meanTime}-\texttt{TIME}
=\left(\frac12-\tau\right)h
\]
for an ordinary full step. The two agree when \(\tau=1/2\) and generally differ otherwise. This timestamp convention is distinct from the time used to drift the snapshot positions; see the output interpretation.