10  Elements

10.11.1 OPAL-T mode

Additional OPAL-T attributes are:

FMAPFN

field-map file in T7 format.

TYPE

cavity type, either STANDING (default) or SINGLEGAP.

FREQ

cavity frequency in MHz. If both the cavity card and the field map define a frequency, OPAL-T warns on mismatch and uses the card value.

APVETO

if TRUE, the cavity is excluded from auto-phasing and the phase equals LAG at the arrival time of the reference particle at the field boundary.

Example standing-wave cavity that mimics a DC gun:

gun: RFCAVITY, L=0.018, VOLT=-131/(1.052*2.658),
     FMAPFN="1T3.T7", ELEMEDGE=0.00,
     TYPE=STANDING, FREQ=1.0e-6;

Example two-frequency standing-wave system:

rf1: RFCAVITY, L=0.54, VOLT=19.961, LAG=193.0/360.0,
     FMAPFN="1T3.T7", ELEMEDGE=0.129, TYPE=STANDING,
     FREQ=1498.956;

rf2: RFCAVITY, L=0.54, VOLT=6.250, LAG=136.0/360.0,
     FMAPFN="1T4.T7", ELEMEDGE=0.129, TYPE=STANDING,
     FREQ=4497.536;

10.11.2 OPAL-cycl mode

Cyclotron-side RFCAVITY describes a single-gap cavity sampled from a normalized radial voltage profile. The additional parameters are:

FMAPFN

ASCII file that stores the normalized voltage-amplitude curve of the cavity gap.

TYPE

in cyclotron usage this is typically SINGLEGAP.

FREQ

RF frequency in MHz.

RMIN, RMAX

inner and outer cavity radius in mm.

ANGLE

azimuthal cavity location in the global frame in deg.

PDIS

perpendicular distance of the cavity from the cyclotron center in mm.

GAPWIDTH

cavity gap width in mm.

PHI0

initial phase in deg.

Example:

rf0: RFCAVITY, VOLT=0.25796, FMAPFN="Cav1.dat",
     TYPE=SINGLEGAP, FREQ=50.637, RMIN=350.0,
     RMAX=3350.0, ANGLE=35.0, PDIS=0.0,
     GAPWIDTH=0.0, PHI0=phi01;

10.12.1 Fringe fields

The entrance and exit fringe fields are treated as standing-wave regions: \[ \begin{aligned} \mathbf{E}_{\mathrm{entrance}}(\mathbf{r},t) &= \mathbf{E}_{\mathrm{from\,map}}(\mathbf{r})\,\mathrm{VOLT}\, \cos\!\bigl(2\pi\,\mathrm{FREQ}\,t + \phi_{\mathrm{entrance}}\bigr), \\\\ \mathbf{E}_{\mathrm{exit}}(\mathbf{r},t) &= \mathbf{E}_{\mathrm{from\,map}}(\mathbf{r})\,\mathrm{VOLT}\, \cos\!\bigl(2\pi\,\mathrm{FREQ}\,t + \phi_{\mathrm{exit}}\bigr). \end{aligned} \] Here VOLT and FREQ are the element amplitude and frequency, the entrance phase is \phi_{entrance} = \mathrm{LAG}, and the exit phase is determined internally from LAG and NUMCELLS.

10.12.2 Reconstructed body field

The field of the accelerating structure body is reconstructed from the central part of the standing-wave map by superposition: \[ \begin{aligned} \mathbf{E}(\mathbf{r},t) = \frac{\mathrm{VOLT}}{\sin(2\pi\,\mathrm{MODE})} \Bigl[ &\mathbf{E}_{\mathrm{from\,map}}(x,y,z) \cos\!\bigl(2\pi\,\mathrm{FREQ}\,t + \mathrm{LAG} + \tfrac{\pi}{2}\,\mathrm{MODE}\bigr) \\\\ +&\mathbf{E}_{\mathrm{from\,map}}(x,y,z+d) \cos\!\bigl(2\pi\,\mathrm{FREQ}\,t + \mathrm{LAG} + \tfrac{3\pi}{2}\,\mathrm{MODE}\bigr) \Bigr]. \end{aligned} \] The cell spacing is \[ d = \lambda\,\mathrm{MODE}, \] where MODE is expressed in units of 2π. When the longitudinal coordinate advances past the end of the available map interval, OPAL-T subtracts an integer number of cavity wavelengths until the position falls back inside the repeated-cell range.

The legacy model therefore treats the entry and exit half cells through the standing-wave fringe fields and the interior through a repeated-cell traveling wave assembled from the same on-axis map.

The element attributes are:

label: TRAVELINGWAVE, APERTURE=real-vector, L=real,
       VOLT=real, LAG=real, FMAPFN=string,
       ELEMEDGE=real, FREQ=real, NUMCELLS=integer,
       MODE=real;

L

cavity length. In OPAL-T the effective structure length is reconstructed from the field map and NUMCELLS, so L is not the primary geometric input.

VOLT

peak RF voltage. The accelerating phase is again expressed by LAG.

LAG

phase lag in rad. In OPAL-T this is normally defined relative to the phase that maximizes energy gain of the reference particle, as determined by the auto-phasing algorithm.

DLAG

phase-lag error in rad.

FMAPFN

field map in T7 format.

FREQ

traveling-wave frequency in MHz. As for RFCAVITY, OPAL-T warns when this differs from the frequency declared in the field map, and the map value takes precedence.

NUMCELLS

number of accelerating cells, excluding entry and exit half-cell fringes.

MODE

mode in units of 2π; for example 1/3 stands for a 2π/3 structure.

FAST

if TRUE and the field map is 1D, OPAL-T builds a 2D interpolation map and avoids an FFT-based evaluation on every particle and every step.

APVETO

disable auto-phasing for this structure and use the user-supplied LAG directly at the arrival time of the reference particle at the field boundary.

The traveling-wave model requires the particle momentum P and charge CHARGE to be defined on the relevant optics command before the structure is used.

Example:

lrf0: TRAVELINGWAVE, L=0.0253, VOLT=14.750,
      NUMCELLS=40, ELEMEDGE=2.73066,
      FMAPFN="INLB-02-RAC.Ez", MODE=1/3,
      FREQ=1498.956, LAG=248.0/360.0;

10.14.1 OPAL-T mode

Optically, a collimator behaves like a drift space, but during tracking it also introduces an aperture limit. The aperture is checked at the entrance, and if the collimator has nonzero length it is also checked at the exit and at every timestep.

XSIZE

horizontal half-aperture in m.

YSIZE

vertical half-aperture in m.

For ECOLLIMATOR, the values are ellipse half-axes; for RCOLLIMATOR, they are rectangle half-widths.

Example:

Col: ECOLLIMATOR, L=1.0E-3, ELEMEDGE=3.0E-3, XSIZE=5.0E-4,
     YSIZE=5.0E-4, OUTFN="Coll.h5";

FLEXIBLECOLLIMATOR extends this with a small shape-description language. The supported primitive and composition commands are:

rectangle(width, height)

rectangle centered at the origin.

ellipse(width, height)

ellipse centered at the origin.

polygon(x0, y0; x1, y1; ...; xN, yN)

polygon whose final point is implicitly connected back to the first point. The polygon is triangulated internally, so self-crossing edges are not allowed.

mask('filename.pbm', width, height)

black-and-white PBM bitmap mask. White pixels stop particles.

translate(command, shiftx, shifty)

translate a shape by (shiftx, shifty).

rotate(command, angle)

rotate a shape about the origin.

union(command1, command2, ...)

union of several shape definitions.

difference(command1, command2)

particles pass command1 but not command2.

symmetric_difference(command1, command2)

particles pass either command but not both at the same time.

intersection(command1, command2)

particles pass both commands simultaneously.

repeat(command, N, shiftx, shifty)

repeat a shape N times with a translational offset.

repeat(command, N, angle)

repeat a shape N times with successive rotation.

The expression language supports the following constants and functions:

A simple elliptic collimator can be described by:

ellipse(0.04, 0.03)

A regular pepper-pot with rectangular holes can be described by:

repeat(
       repeat(
              translate(
                        rotate(
                               rectangle(
                                         0.002,
                                         0.002
                                        ),
                               0.78539
                              ),
                        -0.028,
                        -0.028
                       ),
              16,
              0.004,
              0.0
             ),
       16,
       0.0,
       0.004
      )

In FLEXIBLECOLLIMATOR, the hole description can be supplied directly through DESCRIPTION or through an external file specified by FNAME. The external file form is the one that allows comments and line breaks.

10.14.2 OPAL-cycl mode

Only CCOLLIMATOR is available in OPAL-cycl. It is a radial rectangular collimator that may absorb or scatter particles using the particle-matter interaction module.

XSTART, XEND, YSTART, YEND

start and end points of the collimator edge in mm.

ZSTART, ZEND

vertical bounds in mm.

WIDTH

collimator width in mm.

Example:

REAL y1=-0.0;
REAL y2=0.0;
REAL y3=200.0;
REAL y4=205.0;
REAL x1=-215.0;
REAL x2=-220.0;
REAL x3=0.0;
REAL x4=0.0;

cmphys: PARTICLEMATTERINTERACTION, TYPE=SCATTERING, MATERIAL=COPPER;

cma1: CCOLLIMATOR, XSTART=x1, XEND=x2, YSTART=y1, YEND=y2,
      ZSTART=2, ZEND=100, WIDTH=10.0, PARTICLEMATTERINTERACTION=cmphys;

cma2: CCOLLIMATOR, XSTART=x3, XEND=x4, YSTART=y3, YEND=y4,
      ZSTART=2, ZEND=100, WIDTH=10.0, PARTICLEMATTERINTERACTION=cmphys;

10.16.1 RBEND

Key attributes are:

• L: physical magnet length
• GAP: full vertical gap
• HAPERT: non-bend-plane aperture
• ANGLE: bend angle in rad
• K0, K0S: normal and skew dipole field amplitudes in T
• E1: entrance edge angle
• DESIGNENERGY: reference-particle energy in MeV
• FMAPFN: fringe-field map, typically 1DProfile1

If ANGLE is set, it overrides K0 and OPAL adjusts the field strength to bend the design particle through the requested angle.

10.16.2 RBEND3D

RBEND3D keeps the rectangular bend geometry but uses explicit field-map support for the field model. The input attributes follow the same geometric meaning as RBEND, and the entrance/exit pole-face interpretation stays the same.

10.16.3 SBEND

SBEND is the sector-bend version. The main difference is the interpretation of L: it is the chord length of the bend reference arc, \[ L = 2 R \sin(\alpha/2) \] and the element has both E1 and E2 as independent edge angles. Very large bend angles are possible, but once the entrance and exit fringe regions begin to overlap, the approximation becomes unreliable.

10.16.4 Bend setup rules in OPAL-T

The original manual emphasizes the following practical points:

1. Internally OPAL-T treats all bends as positive bends in the local reference frame and then uses ROTATION to orient them in the laboratory transverse plane.
2. If ANGLE is nonzero, K0 and K0S are ignored.
3. When ANGLE is used to define the bend strength, the actual beam bend still depends on whether the bunch energy matches DESIGNENERGY.
4. The hard-edge geometry defines the ideal reference trajectory, while the FMAPFN field map defines the soft-edge magnet seen by tracked particles.
5. If the default field map 1DPROFILE1-DEFAULT is used, OPAL shifts the fringe-field origins so that the effective length of the soft-edge magnet matches the ideal hard-edge reference bend.

10.16.5 RBEND and SBEND examples

A simple RBEND driven by ANGLE and the default fringe-field map is:

Bend: RBEND, ANGLE = 30.0 * Pi / 180.0,
      FMAPFN = "1DPROFILE1-DEFAULT",
      ELEMEDGE = 0.25,
      DESIGNENERGY = 10.0E6,
      L = 0.5, GAP = 0.02;

For an electron design beam this produces a 30 degree positive bend, a 1 m reference radius, and a field amplitude of about -0.0350195 T. The important part of the diagnostic output is the final fringe-field integration report, which tells the user the actual bend angle of the reference particle through the soft-edge magnet.

The same bend can be defined through K0 instead of ANGLE:

Bend: RBEND, K0 = -0.0350195,
      FMAPFN = "1DPROFILE1-DEFAULT",
      ELEMEDGE = 0.25,
      DESIGNENERGY = 10.0E6,
      L = 0.5, GAP = 0.02;

To numerical precision this reproduces the same geometry and field.

To bend in the opposite direction, the legacy manual gives four equivalent patterns:

Bend: RBEND, ANGLE = -30.0 * Pi / 180.0,
             FMAPFN = "1DPROFILE1-DEFAULT",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             L = 0.5, GAP = 0.02;

Bend: RBEND, ANGLE = 30.0 * Pi / 180.0,
             FMAPFN = "1DPROFILE1-DEFAULT",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             L = 0.5, GAP = 0.02,
             ROTATION = Pi;

Bend: RBEND, K0 = 0.0350195,
             FMAPFN = "1DPROFILE1-DEFAULT",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             L = 0.5, GAP = 0.02;

Bend: RBEND, K0 = -0.0350195,
             FMAPFN = "1DPROFILE1-DEFAULT",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             L = 0.5, GAP = 0.02,
             ROTATION = Pi;

The recommended style is to define the bend in the positive reference orientation and then use ROTATION to place it elsewhere in the transverse plane.

A representative four-dipole chicane setup is:

Bend1: RBEND, ANGLE = 20.0 * Pi / 180.0,
              E1 = 0.0,
              FMAPFN = "1DPROFILE1-DEFAULT",
              ELEMEDGE = 0.25,
              DESIGNENERGY = 10.0E6,
              L = 0.25,
              GAP = 0.02,
              ROTATION = Pi;

Bend2: RBEND, ANGLE = 20.0 * Pi / 180.0,
              E1 = 20.0 * Pi / 180.0,
              FMAPFN = "1DPROFILE1-DEFAULT",
              ELEMEDGE = 1.0,
              DESIGNENERGY = 10.0E6,
              L = 0.25,
              GAP = 0.02,
              ROTATION = 0.0;

Bend3: RBEND, ANGLE = 20.0 * Pi / 180.0,
              E1 = 0.0,
              FMAPFN = "1DPROFILE1-DEFAULT",
              ELEMEDGE = 1.5,
              DESIGNENERGY = 10.0E6,
              L = 0.25,
              GAP = 0.02,
              ROTATION = 0.0;

Bend4: RBEND, ANGLE = 20.0 * Pi / 180.0,
              E1 = 20.0 * Pi / 180.0,
              FMAPFN = "1DPROFILE1-DEFAULT",
              ELEMEDGE = 2.25,
              DESIGNENERGY = 10.0E6,
              L = 0.25,
              GAP = 0.02,
              ROTATION = Pi;

SBEND can be used in the same role once L, E1, and E2 are interpreted using the sector-bend geometry.

10.16.6 Custom 1DProfile1 bend maps

The source manual distinguishes two 1DProfile1 usage modes:

1. the map defines both the fringe fields and the magnet length,
2. the map defines only the fringe fields and the element L defines the body length.

In the first mode, a custom map can define an SBEND without supplying L in order to preserve the exit fringe placement:

1DProfile1 1 1 2.0
 -10.0  0.0  10.0 1
  15.0  25.0 35.0 1
  0.00000E+00
  2.00000E+00
  0.00000E+00
  2.00000E+00

Bend: SBEND, ANGLE = 60.0 * Pi / 180.0,
             E1 = -10.0 * Pi / 180.0,
             E2 = 20.0 * Pi / 180.0,
             FMAPFN = "TEST-MAP.T7",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             GAP = 0.02;

In the second mode, the field map contains only the entrance and exit fringe profiles and the magnet body is set by L:

1DProfile1 1 1 2.0
 -10.0  0.0  10.0 1
 -10.0  0.0  10.0 1
  0.00000E+00
  2.00000E+00
  0.00000E+00
  2.00000E+00

Bend: SBEND, ANGLE = 60.0 * Pi / 180.0,
             E1 = -10.0 * Pi / 180.0,
             E2 = 20.0 * Pi / 180.0,
             FMAPFN = "TEST-MAP.T7",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             L = 0.25,
             GAP = 0.02;

With ANGLE, OPAL adjusts the field amplitude so that the reference particle is bent by the requested amount after the fringe fields are included. With K0, that compensation is not automatic:

Bend: SBEND, K0 = -0.1400778,
             E1 = -10.0 * Pi / 180.0,
             E2 = 20.0 * Pi / 180.0,
             FMAPFN = "TEST-MAP.T7",
             ELEMEDGE = 0.25,
             DESIGNENERGY = 10.0E6,
             L = 0.25,
             GAP = 0.02;

In the original example this produces a small bend mismatch because the soft-edge effective length no longer matches the ideal hard-edge reference magnet. The manual then corrects this by moving the entrance and exit Enge origins outward by 0.03026 mm:

1DProfile1 1 1 2.0
 -10.0  -0.03026  10.0 1
 -10.0   0.03026  10.0 1
  0.00000E+00
  2.00000E+00
  0.00000E+00
  2.00000E+00

This increases the effective magnet length until the final tracked bend of the reference particle matches the desired 60 degree design bend again.

10.16.7 Bend fields from 1DProfile1

For RBEND and SBEND, OPAL-T divides the field into three regions:

1. entrance fringe field
2. central field region
3. exit fringe field

The fringe regions are modeled from the 1DProfile1 Enge functions associated with FMAPFN.

The Enge function is \[ F(z) = \frac{1}{1 + e^{\sum_{n=0}^{N_{\mathrm{order}}} c_n (z/D)^n}} \] where D is the full magnet gap, N_order is the Enge order, and z is the perpendicular distance from the chosen fringe-field origin to the magnet face.

For a positive bend OPAL-T works with:

• B_0: dipole field amplitude,
• R: bend radius,
• n = -(R/B_y)(\partial B_y/\partial x): field index set from K1,
• F(\Delta_z): the entrance, central, or exit Enge profile depending on the particle position.

The transverse-local coordinates are:

• y: vertical offset from the magnet mid-plane,
• \Delta_x: perpendicular distance from the reference trajectory in the bend plane,
• \Delta_z: perpendicular distance from the entrance or exit fringe-field origin.

Starting from \[ \nabla \cdot \vec{B} = 0, \qquad \nabla \times \vec{B} = 0, \] and defining \[ F' = \frac{dF}{dz}, \qquad F'' = \frac{d^2F}{dz^2}, \qquad F''' = \frac{d^3F}{dz^3}, \] one may write the exact off-axis field in terms of \[ \kappa(\Delta_z) = \sqrt{\frac{n^2}{R^2} + \frac{F''(\Delta_z)}{F(\Delta_z)}}. \] Then \[ \begin{aligned} B_x(\Delta_x,y,\Delta_z) &= -B_0 \frac{n}{R} e^{-n\Delta_x/R} \frac{F(\Delta_z)}{\kappa(\Delta_z)} \sin\!\bigl(\kappa(\Delta_z)y\bigr), \\\\ B_y(\Delta_x,y,\Delta_z) &= B_0 e^{-n\Delta_x/R} \cos\!\bigl(\kappa(\Delta_z)y\bigr) F(\Delta_z), \\\\ B_z(\Delta_x,y,\Delta_z) &= B_0 e^{-n\Delta_x/R} \Biggl[ \frac{F'\!(\Delta_z)}{\kappa(\Delta_z)}\sin\!\bigl(\kappa(\Delta_z)y\bigr) - \frac{1}{2\kappa(\Delta_z)} \left(F'''\!(\Delta_z) - \frac{F'\!(\Delta_z)F''\!(\Delta_z)}{F(\Delta_z)}\right) \left( \frac{\sin\!\bigl(\kappa(\Delta_z)y\bigr)}{\kappa(\Delta_z)^2} - y\frac{\cos\!\bigl(\kappa(\Delta_z)y\bigr)}{\kappa(\Delta_z)} \right) \Biggr]. \end{aligned} \] For tracking, OPAL-T uses the small-y expansion up to O(y^2).

In the fringe regions: \[ \begin{aligned} B_x &\approx -B_0 \frac{n}{R} e^{-n\Delta_x/R} y, \\\\ B_y &\approx B_0 e^{-n\Delta_x/R} \left[F(\Delta_z) - \left(\frac{n^2}{R^2}F(\Delta_z) + F''\!(\Delta_z)\right)\frac{y^2}{2}\right], \\\\ B_z &\approx B_0 e^{-n\Delta_x/R} y F'\!(\Delta_z). \end{aligned} \] In the central region: \[ \begin{aligned} B_x &\approx -B_0 \frac{n}{R} e^{-n\Delta_x/R} y, \\\\ B_y &\approx B_0 e^{-n\Delta_x/R}\left(1 - \frac{n^2}{R^2}\frac{y^2}{2}\right), \\\\ B_z &\approx 0. \end{aligned} \] These are the expressions OPAL-T uses internally after it determines whether a particle is in the entrance fringe, body, or exit fringe region.

10.16.8 Default bend field map

When FMAPFN="1DPROFILE1-DEFAULT", OPAL uses built-in Enge coefficients for both the entrance and exit fringe regions. The default map corresponds to a 2 cm gap, which may be overridden by the element GAP attribute.

The coefficients are: \[ \begin{aligned} c_0 &= 0.478959, & c_1 &= 1.911289, & c_2 &= -1.185953, \\ c_3 &= 1.630554, & c_4 &= -1.082657, & c_5 &= 0.318111. \end{aligned} \]

The equivalent explicit 1DProfile1 map is:

1DProfile1 5 5 2.0
 -10.0 0.0 10.0 1
 -10.0 0.0 10.0 1
  0.478959
  1.911289
 -1.185953
  1.630554
 -1.082657
  0.318111
  0.478959
  1.911289
 -1.185953
  1.630554
 -1.082657
  0.318111

10.16.9 SBEND3D

SBEND3D is the OPAL-cycl field-map bend. It is defined by:

label: SBEND3D, FMAPFN=string, LENGTH_UNITS=real, FIELD_UNITS=real;

FMAPFN

3D magnetic field-map file.

LENGTH_UNITS

scaling for the map coordinates.

FIELD_UNITS

scaling for the field values.

The field map is stored in Cartesian field components but arranged on a cylindrical (r, z, \theta) grid. The expected column ordering is \((x, z, y, B_x, B_z, B_y)\). SBEND3D assumes dipole symmetry across the median plane.

Example:

Dipole: SBEND3D, FMAPFN="90degree_Dipole_Magnet.out",
        LENGTH_UNITS=1000.0, FIELD_UNITS=-10.0;

10.20.1 Scaling FFA Magnet

The scaling FFA model is a fully scaling field model including scaling fringe fields. In cylindrical-polar notation it has the form \[ B_\phi = \sum_{n=0} f_{2n+1}(\psi)\, h(r) \left(\frac{z}{r}\right)^{2n+1}, \] \[ B_r = \sum_{n=0} \left[ \frac{k-2n}{2n+1} f_{2n} - \tan(\delta) f_{2n+1} \right] h(r) \left(\frac{z}{r}\right)^{2n+1}, \] \[ B_z = \sum_{n=0} f_{2n}(\psi)\, h(r) \left(\frac{z}{r}\right)^{2n}. \] Here \(r\) and \(z\) are cylindrical coordinates and \[ \psi = \phi - \tan(\delta)\ln(r/r_0) \] is the azimuth in the spiral coordinate system. \(r_0\), \(\delta\), \(k\), and \(B_0\) define the radial field scaling.

Important attributes are:

• B0: nominal dipole field at R0 in T
• R0: radial scale in m
• FIELD_INDEX: scaling field index
• TAN_DELTA: tangent of the spiral angle
• MAX_Y_POWER: highest retained vertical power in the expansion
• END_LENGTH, CENTRE_LENGTH: fringe and body lengths in m
• HEIGHT: full vertical aperture
• RADIAL_NEG_EXTENT, RADIAL_POS_EXTENT: radial tracking limits about R0
• MAGNET_START, MAGNET_END: placement of the effective magnet body within the element
• AZIMUTHAL_EXTENT: azimuthal support of the field model

10.20.2 Vertical FFA Magnet

VERTICALFFAMAGNET is also a fully scaling model including scaling fringe fields, but it uses a vertically scaling exponential field law, \[ B_x = \sum_n B_0 e^{mz}\,\frac{1}{m}\,\partial_x f_n\, y^n, \] \[ B_y = \sum_n B_0 e^{mz}\,\frac{n+1}{m}\, f_{n+1}\, y^n, \] \[ B_z = \sum_n B_0 e^{mz} f_n y^n. \]

Important attributes are:

• B0: nominal dipole field at z = 0
• FIELD_INDEX: vertical scaling index m in m^-1
• MAX_Y_POWER: maximum retained power in y
• END_LENGTH, CENTRE_LENGTH: fringe and body lengths
• WIDTH: full horizontal aperture
• HEIGHT_NEG_EXTENT, HEIGHT_POS_EXTENT: lower and upper vertical limits
• BB_LENGTH: bounding-box length used for placement of the next element

Both FFA families are cyclotron-side restricted features intended for specialized fixed-field ring studies.

10.21.1 Local Cartesian Offset

LOCAL_CARTESIAN_OFFSET places the next element at an arbitrary position in the coordinate system of the preceding element. It is mainly used to create drift gaps and overlapping placements.

• END_POSITION_X, END_POSITION_Y: displacement of the next element start
• END_NORMAL_X, END_NORMAL_Y: outgoing element normal in the preceding frame

10.21.2 Local Cylindrical Offset

LOCAL_CYLINDRICAL_OFFSET performs the same task in cylindrical coordinates.

• THETA_IN: angle from the previous element to the displacement vector
• THETA_OUT: angle from the displacement vector to the next element
• LENGTH: offset length

10.23.1 Time-dependence models

POLYNOMIAL_TIME_DEPENDENCE

defines \[ g(t) = p_0 + p_1 t + p_2 t^2 + p_3 t^3, \] either via P0..P3 or a longer COEFFICIENTS array.

SPLINE_TIME_DEPENDENCE

uses tabulated TIMES and VALUES with ORDER=1 or 3.

SINUSOIDAL_TIME_DEPENDENCE

sums one or more sine waves from arrays FREQUENCIES, AMPLITUDES, PHASE_OFFSETS, and DC_OFFSETS.

10.23.2 Soft-edged variable cavities

For soft-edged cavities, VARIABLE_RF_CAVITY_FRINGE_FIELD adds:

• CENTRE_LENGTH
• END_LENGTH
• CAVITY_CENTRE
• MAX_ORDER

The intention is to place a full cavity including the central flat-top field region and explicit fringe-field ends. VARIABLE_RF_CAVITY_FRINGE_FIELD is the legacy soft-edge companion of VARIABLE_RF_CAVITY.

Example:

RF_FREQUENCY: POLYNOMIAL_TIME_DEPENDENCE, P0=rf_p0, P1=rf_p1, P2=rf_p2, P3=rf_p3;
RF_AMPLITUDE: POLYNOMIAL_TIME_DEPENDENCE, P0=1.0;
RF_PHASE: POLYNOMIAL_TIME_DEPENDENCE, P0=phi;

HARD_RF_CAVITY: VARIABLE_RF_CAVITY,
                PHASE_MODEL="RF_PHASE", AMPLITUDE_MODEL="RF_AMPLITUDE",
                FREQUENCY_MODEL="RF_FREQUENCY", L=0.100, HEIGHT=0.200, WIDTH=2.000;

SOFT_RF_CAVITY: VARIABLE_RF_CAVITY_FRINGE_FIELD,
                PHASE_MODEL="RF_PHASE", AMPLITUDE_MODEL="RF_AMPLITUDE",
                FREQUENCY_MODEL="RF_FREQUENCY", L=0.200, HEIGHT=0.200, WIDTH=2.000,
                CENTRE_LENGTH=0.1, END_LENGTH=0.01, CAVITY_CENTRE=0.1, MAX_ORDER=4;