27  Appendix D — Auto-phasing Algorithm

27.1 Standing Wave Cavity

For external RF fields in OPAL-T, the instantaneous field is the interpolated spatial field multiplied by cos(omega t + phi). The energy gain of a particle is therefore

\[ \Delta E(\varphi, r) = q V_0 \int_{z_{\mathrm{begin}}}^{z_{\mathrm{end}}} \cos(\omega t(z,\varphi) + \varphi)\, E_z(z,r)\, dz. \tag{27.1}\]

To maximize the gain, one differentiates with respect to the lag \varphi and sets the derivative to zero. This yields the lag rule

\[ \tan(\varphi) = - \Gamma_1 / \Gamma_2. \tag{27.2}\]

The original appendix defines

\[ \Gamma_1 = \sum_{i=1}^{N-1} \left(1 + \omega \frac{\partial t}{\partial\varphi}\right) \int_{z_{i-1}}^{z_i} \sin\!\left(\omega \left(t_{i-1} + \Delta t_i\frac{z-z_{i-1}}{\Delta z_i}\right)\right) \left(E_{z,i-1} + \Delta E_{z,i}\frac{z-z_{i-1}}{\Delta z_i}\right) dz, \tag{27.3}\]

and

\[ \Gamma_2 = \sum_{i=1}^{N-1} \left(1 + \omega \frac{\partial t}{\partial\varphi}\right) \int_{z_{i-1}}^{z_i} \cos\!\left(\omega \left(t_{i-1} + \Delta t_i\frac{z-z_{i-1}}{\Delta z_i}\right)\right) \left(E_{z,i-1} + \Delta E_{z,i}\frac{z-z_{i-1}}{\Delta z_i}\right) dz. \tag{27.4}\]

Assuming piecewise-linear field and time-of-flight models between samples, the integrals can be evaluated analytically in terms of four coefficients:

\[ \Gamma_{11,i} = -\frac{\cos(\omega t_i) - \cos(\omega t_{i-1})}{\omega\Delta t_i}, \qquad \Gamma_{12,i} = \frac{-\omega\Delta t_i\cos(\omega t_i) + \sin(\omega t_i) - \sin(\omega t_{i-1})}{\omega^2 (\Delta t_i)^2}, \tag{27.5}\]

\[ \Gamma_{21,i} = \frac{\sin(\omega t_i) - \sin(\omega t_{i-1})}{\omega\Delta t_i}, \qquad \Gamma_{22,i} = \frac{\omega\Delta t_i\sin(\omega t_i) + \cos(\omega t_i) - \cos(\omega t_{i-1})}{\omega^2 (\Delta t_i)^2}. \tag{27.6}\]

With these, the appendix rewrites the accumulated sums in a form suitable for an iterative implementation.

27.1.1 Implemented Iterative Idea

The legacy algorithm starts from a guessed kinetic-energy evolution,

K[i] = K[i-1] + (z[i] - z[0]) * q * V;
b[i] = sqrt(1. - 1. / ((K[i] - K[i-1]) / (2.*m*c^2) + 1)^2);
t[i] = t[0] + (z[i] - z[0]) / (c * b[i])

which assumes a roughly linear energy increase proportional to the maximum voltage. From that provisional t(z) model, OPAL computes the lag from Equation 27.2, then updates the kinetic energy using the analytic segment formulas,

\[ K_i = K_{i-1} + q\,\Delta z_i \Bigl[ \cos\varphi\,\bigl(E_{z,i-1}(\Gamma_{21,i}-\Gamma_{22,i}) + E_{z,i}\Gamma_{22,i}\bigr) - \sin\varphi\,\bigl(E_{z,i-1}(\Gamma_{11,i}-\Gamma_{12,i}) + E_{z,i}\Gamma_{12,i}\bigr) \Bigr], \tag{27.7}\]

rebuilds the time-of-flight model, and iterates until \varphi converges.

27.2 Traveling Wave Structure

Traveling-wave auto-phasing is slightly more complicated because the field is composed of:

  • an entry fringe field
  • two standing-wave core contributions with phase offsets
  • an exit fringe field

The appendix uses the field map FINLB02-RAC.T7 as the representative traveling-wave example.

Figure 27.1: Cropped 1DDynamic field map used in the traveling-wave auto-phasing discussion.

The corresponding energy gain is written as the sum of four integrals over the entry fringe, two core components, and exit fringe. In the notation of the appendix, the two core contributions are shifted by one cell length s and by phase offsets \varphi_{c1} and \varphi_{c2}.

27.2.1 Example

The legacy example is:

FINLB02_RAC: TravelingWave, L=2.80, VOLT=14.750*30/31,
             NUMCELLS=40, FMAPFN="FINLB02-RAC.T7",
             ELEMEDGE=2.67066, MODE=1/3,
             FREQ=1498.956, LAG=FINLB02_RAC_lag;

From this, the appendix derives

\[ V_{\mathrm{core}} = \frac{V_0}{\sin(2\pi/3)} = \frac{2V_0}{\sqrt{3}}, \qquad \varphi_{c1} = \frac{\pi}{6}, \qquad \varphi_{c2} = \frac{\pi}{2}, \tag{27.8}\]

and an exit-fringe phase offset determined by NUMCELLS and MODE.

27.2.2 Alternative Approach for Traveling-Wave Structures

In the ultra-relativistic limit, where beta changes only weakly along the structure, the time-of-flight can be approximated linearly,

\[ t(z,\varphi) \approx \frac{z}{\beta c} + t_0. \tag{27.9}\]

For the traveling-wave example, the appendix then rewrites the derivative condition in terms of periodic core and fringe fields over a period 3 s, and shows how the expression simplifies because \omega/(\beta c) \approx 10\pi. The final reduced condition is expressed as a convolution,

\[ 0 \equiv \int_0^{3s} g(\xi-z)\,\bigl(G(z) - 26 H(z)\bigr)\,dz = \mathcal{F}^{-1}\!\left(\mathcal{F}(g)\,\bigl(\mathcal{F}(G)-26\mathcal{F}(H)\bigr)\right), \tag{27.10}\]

with the phase relation

\[ -\frac{\omega}{\beta c}\,\xi = \varphi. \tag{27.11}\]

The appendix also uses the trigonometric identity

\[ \sin(a+\pi+\pi/6) + \sin(a+\pi-\pi/6) = -\sqrt{3}\,\sin(a), \tag{27.12}\]

which is the final algebraic step that collapses the two core terms into the reduced convolution form.

27.3 Current OPALX Availability

OPALX can search for the RF crest phase of a nominal on-axis reference particle. Availability below describes what can currently be used: ✅ Available and ⚪ Unavailable.

Capability Availability now Current scope
Crest-phase search for mapped RFCAVITY, TYPE="IDEAL" and TRAVELINGWAVE ✅ Available Local maximization of nominal on-axis reference-particle exit energy
Input phase offset and per-cavity phase preservation ✅ Available LAG adds an offset from crest; APVETO=TRUE preserves the specified phase
Automatic phasing of SINGLEGAP and VARIABLE_RF_CAVITY ⚪ Unavailable Configure their phases explicitly
Automatic H5 saving of newly optimized phases for restart ⚪ Unavailable Prepare the required operating phases explicitly for restart

Future availability of the unavailable capabilities is unconfirmed. The retained OPAL derivations and examples describe historical OPAL behavior; they are not a current OPALX roadmap.

27.3.1 Scope and Control

Use OPTION, AUTOPHASE=n; to set the number of local phase refinements. The default is 6; use a positive integer for automatic phasing.

APVETO defaults to FALSE. Setting it to TRUE preserves the configured phase and bypasses automatic phase searching. After automatic phasing, subsequent encounters reuse the selected phase.

Mapped standing-wave RFCAVITY accepts the RF formats listed in Field Maps. TRAVELINGWAVE currently requires an AstraDynamic map beginning at z=0. The ideal uniform-field model uses no map. SINGLEGAP and VARIABLE_RF_CAVITY have no automatic phase search in current OPALX.

27.3.2 Search Strategy

The search first estimates a crest phase from the cavity model, then refines it by tracking trial phases through the cavity. The reference starts on the cavity axis at the field entrance, with the incoming longitudinal momentum and arrival time.

This calculation uses nominal fields without DVOLT or DLAG. It excludes space charge, overlapping elements and transverse bunch offsets. The first independent beam defines the design reference; other beams use the same cavity settings. The optimized quantity is the reference-particle exit kinetic energy, rather than the bunch-mean energy.

The operating phase includes the user-specified offset:

\[ \phi_{\mathrm{operating}} = \operatorname{fmod} (\phi_{\mathrm{crest}} + \phi_{\mathrm{LAG}} + 2\pi, 2\pi). \]

LAG is in radians. LAG=0 requests crest operation; nonzero LAG intentionally moves operation away from crest. Input FREQ is in MHz, with \(\omega=2\pi\,10^6\,\mathrm{FREQ}\) in rad/s. For mapped RF cavities, a map frequency differing by more than 1% replaces the element frequency; the resulting effective frequency is used for phasing.

27.3.3 Initial Estimate for RFCAVITY

For mapped standing-wave cavities, the initial estimate uses the sampled on-axis field and an iterative time-of-flight and energy approximation. The historical standing-wave derivation in the OPAL section provides context; the current result is refined by direct tracking.

For RFCAVITY, TYPE="IDEAL", the initial estimate tracks the on-axis reference particle through the uniform RF field. Phase refinement and tracking time-step convergence are separate checks. See the ideal cavity input.

27.3.4 Initial Estimate for TRAVELINGWAVE

The traveling-wave estimate accounts for the entry fringe, two phase-shifted core contributions and the exit fringe. The supported AstraDynamic source map and the element’s cell and phase settings define these contributions. The phase estimate is then refined using the tracked exit energy.

27.3.5 Refinement by Direct Tracking

The initial local step is \(\pi/360\) radians, or 0.5 degrees. The search follows the direction of increasing exit energy, then halves the step once per refinement. After n refinements the step is \(0.5^\circ/2^n\); the default n=6 gives 0.0078125 degrees.

This finds a local maximum around the initial estimate; a global maximum is not guaranteed. Increasing AUTOPHASE refines the phase step but does not establish tracking time-step convergence. The input LAG is added after the crest search.

27.3.6 Special Cases

DC-like operation — ✅ available. At an effective frequency of at most 1.000001 Hz (\(1.000001\times10^{-6}\) MHz), OPALX adds 0 or pi to the configured phase according to the sign of amplitude times particle charge. There is no RF phase scan in this case.

27.3.7 Outputs and Persistence

The chosen operating phase is retained for subsequent encounters in the current run.

For a non-optimizer RF search with automatic phasing enabled for the cavity, rank 0 writes data/<element-name>_AP.dat in the auxiliary output directory. Its columns are cavity-local z in metres and kinetic energy in MeV. Vetoed and DC cases do not produce this diagnostic file.

The log’s <element-name>_phi1 uses degrees and the phase reference at the field entrance. In radians,

\[ \phi_{\mathrm{log}} = \operatorname{fmod} (\phi_{\mathrm{operating}} + \omega t_{\mathrm{entry}}, 2\pi), \]

where \(t_{\mathrm{entry}}\) is the reference arrival time at the field entrance in seconds. Convert units and time reference before reusing a logged phase as an absolute LAG with APVETO=TRUE.

⚪ Automatic saving of newly optimized cavity phases for H5 restart is currently unavailable. Future support is unconfirmed. Prepare the required operating phases explicitly when setting up a restart; use APVETO=TRUE if those absolute phases must be preserved.

27.3.8 Practical Summary

  • Use automatic phasing for supported mapped or ideal cavities, and treat LAG as the requested offset from crest.
  • Use APVETO=TRUE when a specified absolute cavity phase must remain fixed.
  • Automatic saving of newly optimized phases for H5 restart is unavailable.
  • Formats and algorithms described only in the historical OPAL section are not automatically available in OPALX or confirmed for a future release.