25  Appendix A — Field Maps

25.1 Current OPALX Field Maps

OPALX provides the seven field-map formats below. Availability describes the current supported scope: ✅ Available, 🟡 Partially available (a subset of the format or its options), and ⚪ Unavailable.

Format Availability now Current scope
AstraDynamic ✅ Available 1D on-axis RF field map for standing-wave RFCAVITY and TRAVELINGWAVE; for TRAVELINGWAVE, the source map must start at z=0 m
AstraMagnetoStatic ✅ Available 1D on-axis static magnetic field map with Fourier reconstruction.
3DDynamic ✅ Available 3D Cartesian RF field map for standing-wave RFCAVITY; automatic phase estimation requires the map to cover the local axis x=y=0.
2DMagnetoStatic 🟡 Partially available Normalized magnetic maps with radial origin r=0; an explicit TRUE/FALSE normalization flag makes the map fail to load; omit the flag to use automatic normalization
2DDynamic 🟡 Partially available Normalized RF maps with radial origin r=0; use the documented XZ/ZX columns; an explicit TRUE/FALSE normalization flag makes the map fail to load; omit the flag to use automatic normalization
G4beamline cylinder 🟡 Partially available Bz/Br block format; electric fields, Bphi, data and symmetry sections are unavailable
G4beamline grid 🟡 Partially available Six- or nine-column data format; points, symmetry sections and ZREVERSE are unavailable

Future support for the missing options and formats is unconfirmed. The historical OPAL descriptions below, including material formerly marked planned, do not establish a current OPALX implementation commitment.

The descriptor is read from the beginning of the first non-comment record. Comments begin with #. G4beamline maps have no descriptor; OPALX recognizes them by their first keyword, an optional param line followed by cylinder or grid. The file extension does not matter.

25.1.1 Element compatibility

Reader availability does not mean that every element accepts that format.

Element/model Accepted maps
FIELDMAP 2DMagnetoStatic, AstraMagnetoStatic, G4beamline cylinder and grid; dynamic maps are rejected
SOLENOID 2DMagnetoStatic, AstraMagnetoStatic, G4beamline cylinder and magnetic-only grid maps. SOLENOID does not check the map type, so other maps load but give wrong fields; use FIELDMAP for maps containing electric fields
RFCAVITY, TYPE="STANDING" AstraDynamic, 2DDynamic, 3DDynamic
RFCAVITY, TYPE="IDEAL" no field map; FMAPFN is rejected
TRAVELINGWAVE AstraDynamic; the source map must begin at z=0. Other dynamic maps load but stop the run at the first step
RBEND 1DProfile1 fringe profile or the built-in "1DPROFILE1-DEFAULT", read by the bend itself; see below

A wrong map given to SOLENOID is not rejected: an RF map is applied as a static field without its time dependence, and the electric field of a grid map is applied to the particles without the KS factor and is not seen by the reference particle.

For RFCAVITY and TRAVELINGWAVE, if FREQ differs from the map frequency by more than 1 %, OPALX prints a warning and uses the map frequency. A 3DDynamic map that declares frequency 0 therefore gives a static field whatever FREQ says. A static map given to RFCAVITY stops the run.

CYCLOTRONSECTOR and RFCAVITY, TYPE="SINGLEGAP" use separate loaders for sector fields and voltage profiles. See the cyclotron guide for their configuration.

⚪ The FAST accelerated field-map mode is currently unavailable; changing FAST does not select a different field evaluation mode. Future support is unconfirmed. For static-map placement and the independent BSCALE and ESCALE multipliers, see the FIELDMAP reference.

25.1.2 AstraDynamic and AstraMagnetoStatic

The ASTRA readers resample the on-axis data with a natural cubic spline onto an equidistant grid with as many points as there are accepted samples, mirror the profile periodically, and construct a truncated Fourier representation for off-axis field evaluation. N_Fourier in the header is the number of harmonics kept, counting the constant term: harmonics \(0\) to \(N_{\mathrm{Fourier}}-1\). It must be positive; this is not checked.

The first line is AstraDynamic N_Fourier [TRUE|FALSE] or AstraMagnetoStatic N_Fourier [TRUE|FALSE]. AstraDynamic then reads a frequency in MHz and (z [m], Ez [MV/m]) records; AstraMagnetoStatic reads (z [m], Bz [T]) records immediately after its header. The optional flag defaults to TRUE and controls normalization of the input profile to a peak absolute on-axis field of 1 MV/m or 1 T, respectively. Supply at least two samples with increasing \(z\) and a nonzero on-axis field; both readers reject a zero peak even with normalization disabled. A sample whose \(z\) does not exceed the previous one by more than \(10^{-10}\) m is skipped without a message. End the file with a newline: a last line without one is ignored. Neither reader provides a FAST variant.

25.1.3 2DMagnetoStatic

The header declares XZ or ZX ordering. Axis bounds are in cm, and each count is the number of intervals: a count of N gives N+1 grid points. Samples contain Bz Br in XZ order or Br Bz in ZX order, in tesla. Data advance fastest in z for XZ ordering and in r for ZX ordering. The reader uses bilinear interpolation and normalizes the on-axis longitudinal field to a peak magnitude of 1 T. The on-axis Bz must not be zero everywhere; this is not checked and gives invalid fields. Exactly (Nz_intervals+1)(Nr_intervals+1) samples are read; further data are rejected.

2DMagnetoStatic XZ
z_begin_cm z_end_cm Nz_intervals
0 r_end_cm Nr_intervals
Bz Br
...

For ZX, put the radial bounds/count first and the longitudinal bounds/count second. Radial grids must start at zero. A nonzero radial origin is not detected: the grid is used as if it started at \(r=0\).

25.1.4 2DDynamic

This RF format uses axis bounds in cm and interval counts, giving (Nz_intervals+1)(Nr_intervals+1) samples. The frequency in MHz appears between the two axis records for both orderings. Use a radial grid starting at zero; as for 2DMagnetoStatic, a nonzero radial origin is not detected.

2DDynamic XZ
z_begin_cm z_end_cm Nz_intervals
frequency_MHz
0 r_end_cm Nr_intervals
Ez Er unused Hphi
...

For ZX, the radial bounds/count come first and the longitudinal bounds/count come after the frequency. The current reader consumes data as follows:

Ordering Data columns
XZ Ez Er unused Hphi
ZX Er Ez Hphi unused

Data advance fastest in z for XZ ordering and in r for ZX ordering.

Electric components are in MV/m and Hphi is in A/m. Use the column order for the selected orientation when preparing or converting a map.

Normalization uses the maximum absolute Ez over the entire grid, rather than only the axis. The resulting peak absolute Ez is 1 MV/m. Hphi is converted to magnetic flux density with the same normalization factor and the vacuum permeability \(\mu_0\). Ez must not be zero everywhere; this is not checked.

🟡 Normalization options: use a two-token header, such as 2DDynamic XZ. Explicit TRUE/FALSE normalization flags currently do not work for 2DMagnetoStatic and 2DDynamic; omit the flag to use automatic normalization. The ASTRA and 3DDynamic normalization flags are available. Future availability of the missing 2D options is unconfirmed.

25.1.5 3DDynamic

3DDynamic supplies a Cartesian RF map for mapped standing-wave RFCAVITY. Its complete layout is:

3DDynamic [TRUE|FALSE]
frequency_MHz
x_begin_cm x_end_cm Nx_intervals
y_begin_cm y_end_cm Ny_intervals
z_begin_cm z_end_cm Nz_intervals
Ex Ey Ez Hx Hy Hz
...

Each interval count N gives N+1 points. The z index changes fastest, followed by y and x. Electric components are in MV/m; magnetic-field-strength components are in A/m and are converted to magnetic flux density using \(\mu_0\). The reader uses trilinear interpolation.

By default, all six components are divided by the maximum absolute on-axis Ez, interpolated to x=y=0 in every z plane. Use 3DDynamic FALSE when the map does not contain that axis or has zero on-axis Ez. With FALSE, physical field values retain their input scale before the element amplitude is applied. Nonfinite field records are rejected regardless of the flag. Disabling normalization does not remove the on-axis requirement of automatic phase estimation: with an off-axis-only map, automatic phasing stops the run. For such a map set APVETO=TRUE and give LAG explicitly.

Frequency must be finite and nonnegative. Bounds must be finite and strictly increasing, with at least one interval per axis. Every field component must be finite, and data after the last expected grid point are rejected.

Mapped standing-wave RFCAVITY supplies the RF time dependence: electric amplitudes multiply \(\cos(\omega t+\phi)\) and magnetic amplitudes multiply \(-\sin(\omega t+\phi)\). Here \(t\) is in seconds, \(\omega\) in rad/s and \(\phi\) in radians; the element also supplies its amplitude and error settings.

25.1.6 G4beamline maps

OPALX reads the cylinder and grid formats written by G4beamline. Positions are in mm, magnetic fields in tesla, and electric fields in MV/m. Neither reader normalizes to a field peak. With BSCALE=1 and ESCALE=1, a FIELDMAP element preserves the map’s field scale after applying any param factors.

An optional first line param scales the stored values the same way G4beamline does; only one param line is accepted. Magnetic values are multiplied by normB/current and electric values by normE/gradient. Each key defaults to 1. current=0 is rejected, and so is gradient=0 in a grid map. The current= and gradient= that G4beamline gives where it places a map correspond to BSCALE and ESCALE on the FIELDMAP element.

Symmetry sections (extendX, extendY, extendZ, …) are rejected by both readers.

ZREVERSE is an attribute of FIELDMAP and SOLENOID and is supported only for a cylinder map. The same map filename cannot be loaded with opposite ZREVERSE settings at the same time; use separate files if both orientations are needed.

cylinder maps

A cylinder map holds an axially symmetric magnetic field on an r-z grid:

param normB=1. current=1.
cylinder Z0=-1500.0000 nZ=301 dZ=10.0000 nR=51 dR=10.0000
Bz
<nZ rows of nR values>
Br
<nZ rows of nR values>

The cylinder line gives the first z (Z0), the number of points and the spacing in z (nZ, dZ), and the same in r (nR, dR). Each count must be at least 2. r always starts at 0. X0, Y0, and tolerance are accepted and ignored, as are other unknown keys; Z0, nZ, dZ, nR and dR are required, and dZ and dR must be positive. A Bz block is required and a Br block is optional, in either order; a missing Br block means \(B_r=0\). Each row must hold exactly nR values. In each block a row is one z point and a column one r point, with column 0 on the axis. Er, Ez, and Bphi blocks and the one-point-per-row data form are rejected.

The field is interpolated bilinearly in r and z, as for 2DMagnetoStatic. ZREVERSE mirrors the map about its own \(z=0\) and negates \(B_z\); \(B_r\) is unchanged. The map then covers \([-z_{\mathrm{end}}, -Z_0]\) instead of \([Z_0, z_{\mathrm{end}}]\), which moves the element when \(Z_0 \neq -z_{\mathrm{end}}\).

grid maps

A grid map holds a field on a cartesian grid, one point per row:

param current=1.
grid X0=-200.0000 Y0=-120.0000 Z0=-1380.0000 nX=60 nY=25 nZ=553 dX=10.0000 dY=10.0000 dZ=5.0000
data
-2.0000e+02 -1.2000e+02 -1.3800e+03 6.2742e-05 3.7624e-04 -1.6298e-04
-2.0000e+02 -1.2000e+02 -1.3750e+03 3.7771e-05 3.3956e-04 9.2075e-05
...

The grid line gives the first point (X0, Y0, Z0), the number of points (nX, nY, nZ, each at least 2), and the spacing (dX, dY, dZ). Each row after data holds x y z Bx By Bz, or nine values x y z Bx By Bz Ex Ey Ez. Rows are placed by their own coordinates, so their order does not matter. A row more than a quarter of a spacing off the grid, a row that repeats a point, and a point with no row are all errors. A points section in place of data is rejected, and so is ZREVERSE.

The field is interpolated trilinearly. A point on or beyond the upper face of the grid in any axis gets no field. Storage for the electric field is allocated only when a nonzero electric value appears, so nine-column maps whose electric columns are all zero cost no more than six-column maps.

Memory use

A grid map takes 24 bytes per grid point for the magnetic field, and another 24 bytes per point if it holds a nonzero electric field. The \(60\times25\times553\) map above takes about 20 MB. Every MPI rank holds its own copy, and GPU builds keep one copy in CPU memory and one in GPU memory.

If memory runs out while any map is loaded, OPALX stops with a message that names the map. On Linux the operating system may instead accept the request and end the job without a message once the memory is filled. To reduce the memory needed, use a coarser grid or a smaller box, or run fewer MPI ranks per node.

25.1.7 Recognized but unsupported headers

The following additional or legacy formats are unavailable in current OPALX. A recognized header alone does not make a format usable.

Format or family Availability now Future support
Legacy 1DDynamic, 1DMagnetoStatic, 1DElectroStatic ⚪ Unavailable Unconfirmed
2DElectroStatic ⚪ Unavailable Unconfirmed
Legacy 3DMagnetoStatic (including Extended) and 3DElectroStatic ⚪ Unavailable Unconfirmed
H5hut/HDF5 field blocks ⚪ Unavailable Unconfirmed
AstraElectroStatic ⚪ Unavailable Unconfirmed

Recognition is not support: these formats are unavailable in the currently audited OPALX source tree. A file of one of these types stops the run with Couldn't determine type of fieldmap in file "<file>". This also happens when a 1DProfile1 file or "1DPROFILE1-DEFAULT" is given to an element other than RBEND.

25.1.8 RBEND fringe profiles

RBEND reads a 1DProfile1 file given in FMAPFN with its own reader; no other element accepts this format, and SBEND ignores FMAPFN. The file uses the OPAL Type 2 layout described in the historical section: the header 1DProfile1 N_entrance N_exit gap, then begin origin end flag for the entrance and the same for the exit, then N_entrance+1 entrance coefficients followed by N_exit+1 exit coefficients. Entrance positions are measured from the entrance face and exit positions from the exit face. A Type 1 file, whose exit positions include the magnet length, is not detected and puts the exit fringe in the wrong place.

The values are read in order, so line breaks do not matter. Lengths are in centimetres; the flag must be an integer and is ignored. Each order may be at most 15, begin < origin < end must hold for both faces, and the gap must be positive. If a profile rises away from the magnet, the signs of its odd coefficients are flipped so that it falls. Comments start with # or //; any data after the coefficients is rejected.

FMAPFN="1DPROFILE1-DEFAULT" uses OPAL’s default fifth-order profile for a 0.02 m gap, with each fringe reaching 0.1 m from its face. OPALX shifts both faces so the integral of the profile equals L. If no such shift exists, the run stops with Cannot match default fringe effective length; supply an explicit 1DProfile1 map.

When HGAP or GAP is given, the profile is stretched to that gap; otherwise the file’s gap is used. The field amplitude is not read from the file: it is set so that the design orbit bends by ANGLE, using DESIGNENERGY if given and P0 otherwise. With a profile, K0 to K3S and FINT are rejected.

Missing files, unavailable formats and malformed records are rejected with an error. The error handling described in the historical OPAL section applies to that historical version.

25.2 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.

25.3 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

25.4 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.

25.5 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{25.1}\]

and

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

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

25.6 Types and Format

The legacy appendix lists both implemented and planned descriptors.

25.6.1 Implemented families

Type Meaning
1DMagnetoStatic one-dimensional static magnetic field
AstraMagnetoStatic ASTRA magnetic field format with non-equidistant sampling
1DDynamic one-dimensional time-dependent RF field
AstraDynamic ASTRA dynamic field format
1DProfile1 Enge-like bend fringe profile
2DElectroStatic two-dimensional electrostatic field
2DMagnetoStatic two-dimensional static magnetic field
2DDynamic two-dimensional dynamic field
3DMagnetoStatic three-dimensional static magnetic field
3DMagnetoStatic_Extended mid-plane magnetic field extended to 3D
3DDynamic three-dimensional dynamic field

25.6.2 Planned but not implemented in the historical appendix

Type Note
1DElectroStatic not implemented; old workaround was 1DDynamic with very low frequency
3DElectroStatic not implemented

25.7 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.

Figure 25.1: Axis-ordering conventions for the legacy field-map orientation rules.

25.8 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.

Figure 25.2: Example of field noise caused by insufficient one-dimensional reconstruction.

25.9 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.

Line Contents
1 1DMagnetoStatic N_Fourier [TRUE|FALSE]
2 z_start z_end Nz in cm
3 r_start r_end Nr in cm
remaining lines Bz samples in tesla

25.10 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.

Line Contents
1 AstraMagnetoStatic N_Fourier [TRUE|FALSE]
remaining lines z_i [m], Bz_i [T]

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

25.11 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).

Line Contents
1 1DDynamic N_Fourier [TRUE|FALSE]
2 z_start z_end Nz in cm
3 frequency in MHz
4 r_start r_end Nr in cm for the optional FAST path
remaining lines Ez samples in MV/m

25.12 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.

Line Contents
1 AstraDynamic N_Fourier [TRUE|FALSE]
2 frequency in MHz
remaining lines z_i [m], Ez_i [MV/m]

The appendix again notes that there is no FAST variant.

25.13 1DProfile1

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

\[ F(z) = \frac{1}{1 + e^{\sum_{n=0}^{N_{\mathrm{order}}} c_n (z/D)^n}}, \tag{25.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.

Figure 25.3: Polynomial Enge-style profile used for 1DProfile1.
Figure 25.4: Profile shape for 1DProfile1.

The generic file layout is:

Line Contents
1 1DProfile1 N_Enge_Entrance N_Enge_Exit Gap
2 three entrance parameters plus a placeholder
3 three exit parameters plus a placeholder
following lines entrance coefficients c_0 ... c_N then exit coefficients

25.13.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{25.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{25.5}\]

Figure 25.5: RBEND profile geometry for 1DProfile1 type 1.
Figure 25.6: SBEND profile geometry for 1DProfile1 type 1.

25.13.2 1DProfile1 Type 2

Type 2 removes the magnet-length information from the field map and uses the beamline element attribute L instead. This allows the Enge origins to move relative to the physical edges.

\[ \begin{aligned} \text{Entrance Parameter 2} &= \text{perpendicular distance of the entrance Enge origin from the entrance edge}, \\ \text{Exit Parameter 2} &= \text{perpendicular distance of the exit Enge origin from the exit edge}. \end{aligned} \tag{25.6}\]

The remaining deltas are still recovered from the parameter differences. The two main advantages noted in the appendix are:

  • the Enge origins can be adjusted to model the fringe more accurately
  • one map can be reused for magnets with identical fringe fields but different lengths

25.14 Two-Dimensional Families

25.14.1 2DElectroStatic

Example header:

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

This format describes a sampled electrostatic field with bilinear interpolation. In the legacy workflow these maps were often produced with Poisson Superfish [2]. In the source example the map spans 5000 longitudinal points and 200 radial points. The field is non-negligible from -3.0 cm to 51.0 cm relative to ELEMEDGE, and the radial support is 0.0 cm to 2.0 cm. In XZ orientation the first column is Ez and the second is Er; for ZX orientation the columns are exchanged.

Line Contents
1 2DElectroStatic Orientation [TRUE|FALSE]
2 fastest-changing axis extent and spacing count
3 slowest-changing axis extent and spacing count
remaining lines (Ez, Er) for XZ, (Er, Ez) for ZX

25.14.2 2DMagnetoStatic

Example header:

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

This is the magnetostatic analogue of 2DElectroStatic. The field is normalized so that max(|Bz on axis|) = 1 T. In the source example the orientation is ZX, so the fastest-changing index is radial and the stored pair is (Br, Bz) rather than (Bz, Br).

Line Contents
1 2DMagnetoStatic Orientation [TRUE|FALSE]
2 fastest-changing axis extent and spacing count
3 slowest-changing axis extent and spacing count
remaining lines (Bz, Br) for XZ, (Br, Bz) for ZX

25.14.3 2DDynamic

Example header:

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
...

This is the two-dimensional RF format. It adds a frequency line and stores four values per grid point:

  • Ez
  • Er
  • |E| (present but unused by OPAL-T)
  • Hphi

The first two columns follow the XZ / ZX orientation rule, while the third and fourth do not.

Line Contents
1 2DDynamic Orientation [TRUE|FALSE]
2 fastest-changing axis extent and spacing count
3 frequency in MHz
4 slowest-changing axis extent and spacing count
remaining lines Ez/Er, Er/Ez, |E|, Hphi

25.15 Three-Dimensional Families

25.15.1 3DMagnetoStatic

Example header:

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
...

The plain 3D magnetostatic format stores full sampled vector-field data on a Cartesian grid and uses trilinear interpolation. The legacy ordering is z fastest, then y, then x. The data columns are Bx, By, and Bz.

Line Contents
1 3DMagnetoStatic [TRUE|FALSE]
2 x_start x_end Nx in cm
3 y_start y_end Ny in cm
4 z_start z_end Nz in cm
remaining lines Bx By Bz

25.15.2 3DMagnetoStatic_Extended

Example header:

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

This format stores only a mid-plane magnetic map and reconstructs the 3D field using Maxwell consistency and a perfect-magnetic-conductor mid-plane symmetry. The stored quantity is the perpendicular field component on the mid-plane, and the upper half-plane is mirrored to negative y.

Line Contents
1 3DMagnetoStatic_Extended [TRUE|FALSE]
2 x_start x_end Nx in cm
3 y_start y_end Ny in cm
4 z_start z_end Nz in cm
remaining lines stored mid-plane By values

25.15.3 3DDynamic

Example header:

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
...

The dynamic 3D format adds a frequency specification and then stores six field components per sample:

  • Ex
  • Ey
  • Ez
  • Hx
  • Hy
  • Hz

The grid ordering is again z fastest, then y, then x.

Line Contents
1 3DDynamic [TRUE|FALSE]
2 frequency in MHz
3 x_start x_end Nx in cm
4 y_start y_end Ny in cm
5 z_start z_end Nz in cm
remaining lines Ex Ey Ez Hx Hy Hz