5  OPAL-T

5.5.1 Global Cartesian Coordinate System

The floor coordinate system K is the laboratory frame in which the placed beamline is embedded.

5.5.2 Local Cartesian Coordinate System

Each element e_i carries a local frame K'_i whose origin is at the entrance of the element. The displacement is described by a vector v and the orientation by a unitary matrix W. The source manual writes this as a product of Tait-Bryan rotations:

\[ \mathbf v = \begin{pmatrix} X \\ Y \\ Z \end{pmatrix}, \qquad \mathcal W = \mathcal S \mathcal T \mathcal U, \tag{5.3}\]

with pitch Theta, yaw Phi, and roll Psi.

The element-by-element recurrence is

\[ \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. \tag{5.4}\]

5.5.3 Space-Charge Coordinate System

For the electrostatic space-charge solve, OPAL-T introduces a co-moving frame whose origin is at the bunch mean position and whose z axis is aligned with the mean momentum.

5.5.4 Curvilinear Coordinate System

For beam statistics and reference-orbit interpretation, OPAL-T uses a local curvilinear frame (x, y, s) attached to the reference trajectory.

5.5.5 Design or Reference Orbit

The reference orbit consists of straight sections and circular arcs and is computed by the Orbit Threader from the placed elements.

5.5.6 Compatibility Mode

The compatibility mode was introduced so existing input files could remain valid while the geometry model moved to explicit 3D placement. The user can choose whether downstream ELEMEDGE positions should include fringe-field effects with the IDEALIZED option. The manual warns that this approximation is weakest for elements overlapping dipole fringe regions.

5.5.7 Orbit Threader and Autophasing

The OrbitThreader integrates a design particle through the lattice and builds the IndexMap structure used to accelerate active-element lookup during bunch tracking. When the reference particle reaches an RF structure for the first time, the legacy implementation also autophases it.

5.7.1 Statistics Output

The <input>.stat file stores bunch moments and diagnostics in ASCII SDDS style. The dump rate is controlled by STATDUMPFREQ.

The original manual lists a long table. The most important columns are:

The later columns in the source table also include:

• dE: bunch energy spread
• dt: time-step size
• partsOutside: particles outside the beam-halo boundary
• DebyeLength
• plasmaParameter
• temperature
• rmsDensity

Two options extend this base payload:

• COMPUTEPERCENTILES
• DUMPBEAMMATRIX

With COMPUTEPERCENTILES = TRUE, the file gains percentile columns for the beam size and the normalized emittance at 68.27%, 95.45%, 99.73%, and 99.994% in each of x, y, and z.

With DUMPBEAMMATRIX = TRUE, the file gains the upper-triangular entries of the six-dimensional beam matrix: S11, S12, …, S16, S22, …, S66.

5.7.2 Monitor Statistics Output

Monitor elements write a dedicated second statistics file, data/<input>_Monitors.stat, each time the bunch crosses a monitor. The source chapter documents the payload as:

5.7.3 Input File Transcription

OPAL-T writes data/<input>_3D.opal. This is a transcription of the input file in which ELEMEDGE placements are replaced by the corresponding explicit X, Y, Z, THETA, PHI, and PSI values computed by the geometry layer.

5.7.4 Element Positions Output Files

OPAL-T can dump placed element geometry in several formats:

• data/<input>_ElementPositions.txt
• data/<input>_ElementPositions.py
• data/<input>_ElementPositions.sdds

These are intended for visualization and placement cross-checking.

The source manual distinguishes the three outputs:

• ElementPositions.txt Stores BEGIN, MID, and END entries for elements. The remaining columns contain the floor-coordinate position in the order z, x, y.
• ElementPositions.py A Python helper script for exporting the beamline to ASCII, VTK, or HTML. It supports --export-vtk, --export-web, projection to a plane, and explicit projection normals.
• ElementPositions.sdds An SDDS-style indicator file used to overlay element locations on beam statistics plots.

For the SDDS indicator file the documented columns are:

5.7.5 Reference Particle Trajectory Output

The reference-particle path is written to data/<input>_DesignPath.dat. The documented columns are:

5.9.1 Fringe Field Models

The straight-multipole derivation starts from Maxwell’s equations,

\[ \nabla \cdot \mathbf{B} = 0, \qquad \nabla \times \mathbf{B} = 0, \tag{5.5}\]

and a complex-potential representation. In cylindrical coordinates, this yields the standard multipole expansion

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

where b_n and a_n are the normal and skew coefficients at reference radius r_0.

For a straight fringe field, the source chapter expands the scalar potential as

\[ V = \sum_{n=1}^{\infty} V_n(r,z)\sin n\varphi, \qquad V_n = \sum_{k=0}^{\infty} C_{n,k}(z)\,r^{n+2k}, \tag{5.7}\]

and derives the recurrence

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

with closed form

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

The central-axis gradient profile C_{n,0}(z) is then modeled with an Enge function.

5.9.2 Fringe Field of a Curved Multipole

For a curved multipole with fixed curvature radius rho, the Frenet-Serret scale factor is

\[ h_s = 1 + \frac{x}{\rho}. \tag{5.10}\]

The source expands the three field components as

\[ \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} \tag{5.11}\]

and derives recursion relations from Maxwell’s equations, including

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

and

\[ c_{i,k} + \frac{1}{\rho} c_{i-1,k} = \frac{1}{2k+1}\,\partial_s b_{i,k}. \tag{5.13}\]

The remaining coefficients can then be determined recursively from the mid-plane field series

\[ B_z(z=0) = B_{0,0} + B_{1,0}x + B_{2,0}x^2 + \cdots. \tag{5.14}\]

The variable-curvature extension rho = rho(s) is then obtained by carrying an additional \partial_s rho term through the same expansion strategy.

5.9.3 A More Compact Fringe-Field Treatment

The source closes with an alternative derivation based on the factorized mid-plane field

\[ B_z(x,z=0,s) = T(x)\,S(s), \tag{5.15}\]

and an odd-in-z scalar potential

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

For a straight multipole, Laplace’s equation leads to

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

while for curved multipoles the operator is modified by the curvature terms through h_s. The point of this alternative derivation is to keep the geometry and fringe profile separated through T(x) and S(s).