Appendix A — OPAL-T Field Maps

A.1 Introduction

This appendix documents the field-map types accepted by OPAL-T. The legacy implementation supports several one-, two-, and three-dimensional field-map formats that originated from different external codes and accelerator applications.

The original manual groups them into three families:

1. 2D and 3D sampled field maps with interpolation on a grid
2. 1D on-axis profiles reconstructed off axis from a truncated Fourier series
3. Enge-function fringe-field models for selected bend magnets

In all cases, electric maps are normalized to a peak on-axis longitudinal field of 1 MV/m and magnetic maps to a peak on-axis longitudinal field of 1 T, unless the map type is explicitly documented as an exception.

A.2 Comments in Field Maps

Comments are introduced by # and extend to the end of the line. They are accepted:

• at the beginning of the file
• between data lines
• at the end of a complete data record

They must not split a record that is expected to stay on one line. A valid example is:

# This is a valid comment
1DMagnetoStatic 40 # This is also valid
-60.0 60.0 9999
# and this is valid too
0.0 2.0 199

A broken example is:

1DMagnetoStatic # invalid split record
40
-60.0 60.0 # invalid inline split # 9999
0.0 2.0 199

A.3 Normalization

ASCII field maps are normalized with the maximum absolute value of the longitudinal on-axis field. The documented exception is 1DProfile1. This normalization can be disabled by appending FALSE to the first line of the field map.

A.4 Field-Map Warnings and Errors

If OPAL-T encounters a parsing error, it disables the corresponding element, emits a warning, and continues the simulation. The main warning categories are:

• too few lines compared with the header counts
• too many lines compared with the header counts
• wrong number or type of values on a given line
• file not found
• unrecognized field-map descriptor
• too few Fourier coefficients for a 1D field reconstruction

For one-dimensional maps the reconstruction quality is checked with the legacy criteria

\[ \frac{\sum_{i=1}^N (F_{z,i} - \tilde F_{z,i})^2}{\sum_{i=1}^N F_{z,i}^2} \le 10^{-2}, \tag{A.1}\]

and

\[ \frac{\max_i |F_{z,i} - \tilde F_{z,i}|}{\max_i |F_{z,i}|} \le 10^{-2}, \tag{A.2}\]

where F_z is the sampled field from the file and \tilde F_z is the field reconstructed after low-pass filtering.

A.5 Types and Format

The legacy appendix lists both implemented and planned descriptors.

A.6 Field-Map Orientation

Two- and three-dimensional maps carry an orientation string in the header.

For 2D maps:

• XZ: primary direction in z, secondary in r
• ZX: primary direction in r, secondary in z

For 3D maps:

• XYZ: primary direction in z, secondary in y, tertiary in x

The primary index increases fastest and the tertiary index slowest. Accordingly, the first field component column corresponds to the primary axis-order interpretation. For 2D dynamic maps in XZ orientation the four data columns are:

• Ez
• Er
• |E| (unused by the legacy code)
• Hphi

In the alternative 2D orientation, the first two columns are interchanged while the third and fourth are unchanged.

A.7 FAST Attribute for 1D Field Maps

For some 1D field maps, the boolean attribute FAST can be used to speed up field evaluation. When FAST = TRUE, OPAL-T generates an internal 2D field map and then uses bilinear interpolation rather than the slower Fourier-series technique.

This is faster, but the legacy appendix warns that it can introduce numerical noise if the generated 2D grid is too coarse.

A.8 1DMagnetoStatic

A 1DMagnetoStatic map stores one-dimensional static magnetic data on axis. An example header from the appendix is:

1DMagnetoStatic 40
-60.0 60.0 9999
0.0 2.0 199

This describes a map with 10000 longitudinal points (9999 spacings) from -60 cm to 60 cm relative to ELEMEDGE. The field is normalized so that max(|B_on axis|) = 1 T. The code computes Nz/2 complex Fourier coefficients and retains only N_Fourier during tracking.

If FAST = TRUE, the third line defines the radial range of an internally generated 2D map. In the example, that is 0 cm to 2 cm with 200 radial values.

A.9 AstraMagnetoStatic

This format accepts non-equidistant longitudinal samples in meters. The first column is z, the second is the on-axis longitudinal magnetic field. OPAL-T uses cubic-spline interpolation to resample the data to an equidistant mesh, then computes Fourier coefficients from that internal mesh.

The appendix explicitly notes that AstraMagnetoStatic does not provide a FAST path.

A.10 1DDynamic

A 1DDynamic map is the RF analogue of 1DMagnetoStatic. An example header is:

1DDynamic 40
-3.0 57.0 4999
1498.953425154
0.0 2.0 199

The field is sampled on axis, normalized so that max(|E_on axis|) = 1 MV/m, and evaluated at runtime with the time factor cos(omega t + phi).

A.11 AstraDynamic

AstraDynamic accepts a frequency line followed by non-equidistant z and Ez samples in meters and MV/m. OPAL-T spline-resamples the data to an internal equidistant mesh before the Fourier reconstruction.

The appendix again notes that there is no FAST variant.

A.12 1DProfile1

1DProfile1 is the special bend-fringe profile format. It uses Enge functions for the entrance and exit fringe fields [13],

\[ F(z) = \frac{1}{1 + e^{\sum_{n=0}^{N_{\mathrm{order}}} c_n (z/D)^n}}, \tag{A.3}\]

where D is the full gap of the magnet and c_n are fitted coefficients. Unlike the other ASCII formats, 1DProfile1 is not normalized to unit peak field.

The appendix warns that the polynomial degree should be odd and the highest coefficient should be positive, otherwise the fitted profile may turn upward again at large distance.

The generic file layout is:

A.12.1 1DProfile1 Type 1

Type 1 stores the magnet length implicitly in the difference between the second exit and entrance parameters. The appendix defines

\[ \begin{aligned} \text{Entrance Parameter 1} &= \text{Entrance Parameter 2} - \Delta_1 \\ \text{Entrance Parameter 3} &= \text{Entrance Parameter 2} + \Delta_2 \\ \text{Exit Parameter 2} &= L - \text{Entrance Parameter 2} \\ \text{Exit Parameter 1} &= \text{Exit Parameter 2} - \Delta_3 \\ \text{Exit Parameter 3} &= \text{Exit Parameter 2} + \Delta_4 \end{aligned} \tag{A.4}\]

and recovers internally

\[ \begin{aligned} L &= \text{Exit Parameter 2} - \text{Entrance Parameter 2} \\ \Delta_1 &= \text{Entrance Parameter 2} - \text{Entrance Parameter 1} \\ \Delta_2 &= \text{Entrance Parameter 3} - \text{Entrance Parameter 2} \\ \Delta_3 &= \text{Exit Parameter 2} - \text{Exit Parameter 1} \\ \Delta_4 &= \text{Exit Parameter 3} - \text{Exit Parameter 2}. \end{aligned} \tag{A.5}\]

A.13 Two-Dimensional Families

2DElectroStatic XZ
-3.0 51.0 4999
0.0 2.0 199
0.00000e+00 0.00000e+00
4.36222e-06 0.00000e+00
...

2DMagnetoStatic ZX
0.0 2.0 199
-3.0 51.0 4999
0.00000e+00 0.00000e+00
0.00000e+00 4.36222e-06
...

2DDynamic XZ
-3.0 51.0 4121
1498.953425154
0.0 1.0 75
0.00000e+00 0.00000e+00 0.00000e+00 0.00000e+00
...

A.14 Three-Dimensional Families

3DMagnetoStatic
-1.5 1.5 227
-1.0 1.0 151
-3.0 51.0 4121
0.00e+00 0.00e+00 0.00e+00
...

3DMagnetoStatic_Extended
-9.9254 9.9254 133
-2.0 1.0 15
-22.425 47.425 465
-8.10970000e-05
...

3DDynamic
1498.9534
-1.5 1.5 227
-1.0 1.0 151
-3.0 51.0 4121
0.00e+00 0.00e+00 0.00e+00 0.00e+00 0.00e+00 0.00e+00
...