31 Cyclotron Physics
The first cyclotron implementation preserves the OPAL 2022.1 PSI Ring map model. Input radii are converted from millimetres to metres and map strengths from kilogauss to tesla. The host reader computes first derivatives with the legacy five-point Lagrange stencil, including one-sided stencils at both radial and angular boundaries. A final angular column copies the first column and its derivatives. Fields and derivatives are interpolated bilinearly.
Let \(F(r,\theta)\) be the stored median-plane map in tesla, \(y\) the vertical displacement in metres, and \(s_B\) the element’s BSCALE. The base field is
\[ B_y=s_B F,\qquad B_r=s_B y\,\partial_r F,\qquad B_\theta=s_B\frac{y}{r}\,\partial_\theta F. \]
Convert to Cartesian components using \(B_x=B_r\cos\theta-B_\theta\sin\theta\) and \(B_z=B_r\sin\theta+B_\theta\cos\theta\), then apply the element rotation. The proper rotation from old OPAL coordinates is \((x,y,z)_{\mathrm{old}}\mapsto(x,-z,y)_{\mathrm{OPALX}}\) for positions, momenta, and fields. The model retains only the first-order off-plane extension; it is not a general three-dimensional Maxwell field reconstruction. The acceptance test is on the median plane.
The mirrored trim coil uses \(q=S\min(r-r_1,r_2-r)\), with slope \(S\) in inverse metres. Define
\[ u=\frac{1}{1+10^{0.03(q-4)}},\quad v=\frac{1}{1+10^{-0.2(q-8)}},\quad \Delta B_y=\frac{B_{\max}}{2.78}(-3+3u+5v). \]
The preserved legacy radial correction is
\[ \Delta B_r=y\frac{B_{\max}S\ln 10}{2.78} [-0.09u(1-u)+v(1-v)]. \]
Legacy OPAL uses this derivative convention on both halves: it does not reverse its sign on the outer half when mirroring the profile. This compatibility choice must not be interpreted as a corrected Maxwell-consistent off-plane model. Shape radii are not hard support bounds. Trim contributions are independent of BSCALE and additive across named coils.
Sector support is a half-open angular wedge with closed radial bounds and explicit vertical limits. The final radial interpolation cell is clamped at the outer grid point to avoid an out-of-bounds read. Host reference evaluation and Kokkos particle evaluation share formulas and map storage treated as read-only. No collective reduction is introduced in the field kernel.
The Boris pusher conserves momentum norm in this magnetic-only case up to roundoff. Old OPAL’s CYCLOTRON-T default is classical four-stage RK4. Its explicit TIMEINTEGRATOR="LF2" instead uses drift–Boris-kick–drift and provides the matched-integrator field-port regression. At the original 0.164527805199081 ns timestep, the 72 MeV trajectories agree within 8.6 nm in position and \(1.5\times10^{-9}\) in normalized momentum, including the precision limit of the old ASCII orbit dump and rounded launch momentum. The RK4 comparison decreases from 335 to 76 to 36 micrometres as OPALX’s timestep is halved twice.
Compare trajectories at common physical times; a completed directed turn can take more steps than old OPAL’s fixed STEPSPERTURN setting. A negative excursion of more than \(10^{-9}\) m from the launch plane, initiates the next crossing, excluding the launch point and opposite-direction crossing. Earlier turns are counted at timestep endpoints. The final requested return is localized for static magnetic single-container tracking with completed emission, including runs with space charge. The threader’s reference return remains a separate calculation.
For coasting RING tracking, particle field candidates are selected from the current bunch bounds in the moving frame, transformed into each sector’s local frame including misalignment. A conservative angular-wedge test retains sectors that may intersect those bounds. The field kernel then enforces the existing radial, vertical and half-open angular support. The threader’s first-turn path index is not used to exclude magnetic sectors: its measured return length can differ from the tracked orbit and accumulate a boundary-selection error over successive turns. Field formulas, SI units and Boris substeps are unchanged.
Candidate selection uses host bounds already available to tracking and adds no particle copies or MPI collectives; field evaluation remains in the existing Kokkos kernels. Sector callbacks follow prepared beamline order. Corrected membership and coordinate-frame round trips can change floating-point results. A ten-turn, zero-offset, 72 MeV PSI Ring proton check keeps particle/reference separation below \(10^{-9}\) m on one and two MPI ranks. This is a tracking consistency check, not an absolute orbit-accuracy or convergence bound.
31.0.1 Final reference return event
With launch position \(\mathbf r_0\) and unit launch momentum \(\mathbf n\), the terminal event solves
\[ g(\tau)=\mathbf n\cdot[\mathbf r_{\mathrm{ref}}(t_n+\tau)-\mathbf r_0]=0, \qquad 0<\tau\le\Delta t, \qquad \mathbf n\cdot\mathbf p_{\mathrm{ref}}>0. \]
Positions are in metres, times in seconds and mechanical momentum in \(mc\) units. TRACK brackets the armed final crossing, then bisects by repeating its own Boris reference advance from the unchanged step start. It retains the nonnegative endpoint, resolves time to \(10^{-12}\Delta t\) (or floating-point stagnation), and requires a section residual no larger than \(10^{-9}\) m. A discontinuous or unresolved crossing fails and requests a smaller timestep. No position or momentum projection is applied.
The accepted duration is broadcast before the ordinary particle kernels run. Both half drifts, the kick, reference-frame update and output clock use that duration. Trial reference sampling does not write monitor records. The magnetic Boris kick retains momentum-norm conservation to roundoff; event-dependent time selection is not a claim of global symplecticity. Accumulated transverse orbit error remains independent of the final plane residual.
With space charge, the self-field calculation and particle advance use the accepted common duration. Multiple-container completion, ongoing emission and SINGLEGAP RF remain excluded from explicit TURNS stopping; see the TURNS restrictions.
31.1 Experimental discrete RF tracking
The experimental radial-voltage model supports an unpolarized positive-proton bunch in one container, including MPI tracking with an active space-charge solver. Use the default proton rest mass and omit POLARIZATION; restart is unsupported. The bunch transport requires magnetic sectors and at most 64 discrete SINGLEGAP cavities.
Magnetic transport, gap localization and particle kicks run in Kokkos kernels for a bunch. The scalar reference is tracked on the host. A bare single-particle run on one MPI rank retains a host implementation without the 64-gap bunch limit. TRACK,EKINSTOP adds the reference kinetic-energy target described below.
Profiles contain normalized coordinate \(u\), voltage multiplier \(f(u)\), and \(df/du\) at each support point. Cubic Hermite interpolation uses the supplied derivatives. The support is the closed interval \([0,1]\); values outside it do not produce a kick. The local \(x\) axis follows the gap, \(z\) is its positive normal, and \(y\) is vertical. Set \(\varphi=\omega t-\phi_0\), with seconds and radians. For peak voltage \(V\) in volts, rest energy \(M\) in eV, gap width \(g\) in metres, and a proton of incoming speed \(\beta c\),
\[ a=\frac{\omega g}{2\beta c},\qquad \Delta\gamma=\frac{Vf(u)}{M}\frac{\sin a}{a}\cos\varphi. \]
The zero-width limit is one. Radial momentum is preserved while the positive longitudinal momentum is reconstructed from the new energy. The subsequent legacy focusing rotation is
\[ \alpha=-\frac{f'(u)V c\sin\varphi} {\ell\,\omega\,2\pi\,|\mathbf p|\,M},\qquad \begin{pmatrix}p_x'\\p_z'\end{pmatrix}= \begin{pmatrix}\cos\alpha&\sin\alpha\\-\sin\alpha&\cos\alpha\end{pmatrix} \begin{pmatrix}p_x\\p_z\end{pmatrix}, \]
where \(\ell\) is the profile’s physical length and momentum is in units of \(m_pc\). The kick uses the total incoming momentum and preserves vertical momentum:
\[ |\mathbf p|=\sqrt{p_x^2+p_y^2+p_z^2},\qquad p_{z,f}=+\sqrt{\gamma_f^2-1-p_x^2-p_y^2}. \]
The radial/longitudinal rotation leaves \(p_y\) unchanged. The transit factor uses the total speed; the model includes neither vertical RF focusing nor vertical variation of the voltage profile.
The extra \(2\pi\) and the absence of a transit factor in the focusing term reproduce OPAL 2022.1’s convention deliberately. This is a compatibility model, not a newly derived general RF focusing law. Unsupported backward states, and kicks without a physical outgoing momentum, are rejected without modifying momentum. Zero voltage leaves momentum exactly unchanged.
Host and device share the kick formulas and gap-event ordering. Each particle and the reference use their own localized arrival times for the RF phase. The accepted step duration is common to the bunch; particle and reference positions are not projected onto one another.
With space charge, SCFIELDUPDATE="MIDPOINT" first predicts positions with a ballistic half drift, gathers the existing PIC self fields there, then restores the starting positions. Frozen gathered self fields supply Boris half kicks before and after the complete external magnetic/RF transport. PRESTEP samples self fields at the starting positions instead. This split approximates the collective force over each step; it does not solve Poisson separately at each particle’s RF event. The timestep must resolve both collective evolution and gap crossings. Binning, Green functions, open boundaries and charge normalization retain the selected field solver’s behavior. The reference carries no self-field kick and defines the common stopping time. A terminal reference energy event is localized before prediction/gather so the whole bunch uses that accepted duration. This experimental extension still needs mesh, particle and timestep convergence checks before quantitative extraction-density predictions.
A trial magnetic Boris step brackets positive crossings of each local \(z=0\) gap plane. Forty bisections of the substep time locate each root. The earliest accepted crossing is processed first, followed by a complete kick and the remaining magnetic step. Already processed gaps are excluded from the remainder of that step. Spatial sector support is used directly instead of the nominal coasting orbit’s path index; leaving that support raises an error. An initial point on a plane is not a crossing.
Unlike old OPAL’s distance/speed estimate, this procedure locates the actual plane intersection. At 2880 steps per nominal turn (41.13 ps), the first accelerating turn reaches 73.7423187 MeV versus old LF2’s 73.7423109 MeV. The maximum matched-time position difference is 0.758 micrometres. A single zero-offset particle remains within 3 picometres of its reference. Regression bounds of 2 micrometres position, \(5\times10^{-7}\) normalized momentum and 20 eV final energy accommodate the measured event-location difference and old ASCII precision. These are first-turn regression bounds, not an established asymptotic convergence rate or full-cycle accuracy claim.
At DT/2 and DT/4 the maximum position differences against matched old-LF2 runs are 0.507 and 0.186 micrometres. At DT/4 the final energy difference is -1.93 eV. Those historical accelerating-turn comparisons sampled the return at a timestep endpoint. The current localized TURNS mode excludes RF; accelerating runs use their time/step schedule or EKINSTOP. Particle E/B diagnostic arrays contain gathered self fields when PIC is active; this event handler does not populate the external magnetic/RF contribution. External field diagnostics require separate explicit sampling. Timesteps must resolve individual gap crossings without an intervening unobserved recrossing.
31.2 Energy-target semantics and long-run comparison
With rest energy \(M\) in eV and mechanical momentum \(\mathbf p\) in units of \(m_pc\), the reference criterion is
\[ K=(\sqrt{1+|\mathbf p|^2}-1)M\ \geq\ 10^9\,\mathrm{EKINSTOP}. \]
The reference criterion is checked immediately after each complete RF kick, including a decelerating harmonic kick. The tracker never applies a fractional RF kick or clamps the energy to the target. Rank zero first advances the reference over the requested step, localizes a terminal target event, and broadcasts the accepted duration, outgoing reference state and terminal decision before PIC prediction and gathering.
Every physical particle advances through that same accepted duration, using its own localized RF arrivals. Reaching the target earlier does not stop an individual particle. The common output clock and reference-frame update use the accepted duration; the reference receives no self-field kick.
At the terminal RF endpoint only, a floating-point allowance handles a particle whose independent transport or frame transformation leaves it just short of the plane:
\[ \delta=64N\epsilon_{\mathrm{double}}L,\qquad L=\max\!\left(1\,\mathrm m,\max_d|r_{a,d}|,\max_d|r_{b,d}|\right). \]
Here \(N\ge1\) counts accepted tracking steps including the final step. The positions \(\mathbf r_a\) and \(\mathbf r_b\) are the start and trial endpoint of the current magnetic interval, in laboratory metres; this can be the remaining part of a step after an earlier gap. An upstream, approaching particle whose trial endpoint is within \(\delta\) short of the plane receives the complete endpoint kick at the common final time. Its starting distance may already be inside that allowance. An arrival within this band is numerically unresolved, so the convention can include a physically later particle within the band. More distant arrivals are excluded.
Ordinary steps retain strict crossing signs, and genuinely bracketed roots use forty bisections. The terminal convention adds no position projection, extra drift or fractional kick. The allowance describes floating-point endpoint resolution and grows with the number of accepted steps; it is not a bound on magnetic, PIC or timestep discretization error.
Old OPAL’s orbit dump instead records the endpoint after the remainder drift. Compare energies after the same kick, but compare positions and momenta using a separate matched fixed-step run. In the no-TC 2880-step case, both codes pass the target in the same 949th gap event. Old LF2 records 590.325895173 MeV; OPALX records 590.326824538 MeV. The difference is +929.365 eV (1.6 ppm). At the common endpoint the position difference is 55.785 micrometres, not the millimetre-scale difference obtained by comparing records at different times.
This inter-code agreement must not be confused with timestep accuracy: halving old LF2’s timestep changes its final energy to 590.296910517 MeV, a 28.985 keV shift. Long-run RF phase accumulation requires a separate refinement check even when the two implementations agree closely at a common timestep.
The half-step OPALX result is 590.297352913 MeV, giving +442.396 eV (0.75 ppm) relative to old LF2. The matched final position difference falls to 26.682 micrometres and both runs contain 949 gap kicks. Particle/reference separation stays below 3.2 nm over the full cycle. The observed reduction supports the port comparison; two timestep levels do not establish an asymptotic order.
With the named mirrored trim coil active over the full azimuth, old LF2 reaches 590.385013924 MeV and OPALX reaches 590.386116234 MeV at the corresponding fixed-step endpoint. The difference is +1102.310 eV (1.87 ppm), the final position difference is 63.183 micrometres, and the largest sampled position difference is 65.301 micrometres. OPALX records 949 kicks and particle/reference separation below 1.5 nm. The old result changes by 59.119 keV relative to TC-off, confirming that the coil is effective in this comparison. Explicit old-OPAL PHIMIN=0, PHIMAX=360 is essential; an omitted upper limit in the installed 2022.1 parser did not activate the intended full-azimuth coil.
The reproducible sandbox/cyclotron/report_acceleration590.py checks empirical inter-code envelopes of 1.5 keV in final energy and 100 micrometres in sampled position difference, and requires the no-TC refinement to reduce the difference. These bounds accommodate the measured event-timing discrepancy; they are not physical error estimates. Active-TC timestep refinement remains future work.
Download the archived Python scripts, including sandbox/cyclotron/report_acceleration590.py. The bundle preserves the original directory layout; inputs and result data are excluded.
31.3 Spectral Tune Calculation
SpectralTunes evolves two independent external-field rays using the same support-aware ExternalFieldRayTracker as the linear-map rays, but without map segmentation or exit-plane projections. The reference starts at supplied kinetic energy \(K\), radius \(r\) and normalized radial momentum \(u_r\); its tangential momentum is positive, \(u_\theta=\sqrt{(1+K/M)^2-1-u_r^2}\), where \(M=mc^2\) and \(K\) use the same energy units. The second ray has the same momentum and initial radial/vertical offsets of 5 mm. This does not find a closed orbit or suppress nonlinear amplitude effects.
For samples \(i=0,\ldots,N-1\), the signals are the difference in cylindrical radii and the displaced ray’s vertical position. Following old OPAL’s getTunes(), physical time is replaced by sample index. The legacy normalization \(L\) is the nominal post-step turn number at the last sampled step, initialized to 1; it is not a directed geometric return count. Fixed steps and fixed sampling stride are required.
The estimator subtracts the sample mean and fits sine/cosine columns at \(\omega_k=2\pi k/[4(N-1)]\), \(k=1,\ldots,\lfloor1.6N\rfloor\). With centered data \(d\), design matrix \(A_i=(\cos(\omega_k i),\sin(\omega_k i))\), and unbiased sample variance \(v\), the power is
\[P_k=\frac{d^T A(A^T A)^{-1}A^T d}{2v}.\]
This is the Lomb–Scargle periodogram with old oversampling 4/high-frequency factor 0.8, written as a two-column least-squares solve rather than copying the legacy peak-array implementation. The returned tune is \(k/(4L)\) at the largest power; there is no sub-bin interpolation. The grid spacing is \(1/(4L)\), so it is 0.0025 when the recorded legacy normalization is \(L=100\). Use the reported legacy_turns value rather than assuming it always equals the requested TURNS: the last sampled post-step count depends on the sampling stride. Physical spectral resolution remains set by record duration, and sampling limits the unaliased frequency range.
The implementation reanchors its trigonometric recurrence every 256 samples to bound accumulated roundoff. Invalid/constant signals raise an error rather than returning a fictitious tune. Unlike old code’s vertical-mean gate, a valid zero-mean vertical oscillation is analyzed. No global canonical symplecticity assumption enters this method. Energy drift, timestep/amplitude sensitivity and agreement with independent old-code trajectories must still be checked.
The archived 230-row study spans 72 to 529.993 MeV. Its 100-nominal-turn, 720-step-per-turn RK4 comparison agrees with old OPAL within one 0.0025 tune bin in both planes at every row. The maximum relative kinetic-energy drift in OPALX is 8.03e-6. This establishes legacy-port agreement at these settings, not an absolute tune-accuracy bound. Both codes differ from the supplied SEO tune table, particularly near 500 MeV; that discrepancy remains a separate question. No 530–590 MeV result is claimed without additional validated launch conditions.
Download the archived Python scripts, including sandbox/cyclotron/report_spectral_table.py and sandbox/cyclotron/run_spectral_tunes.py. The archive contains source scripts; the launch table, field maps and result data are not included.