12  Elements

Elements are named objects placed in three dimensions and assembled into a LINE. Shared concepts are described once; select OPALX or OPAL above for version-specific interfaces.

Type Regression use External data
DRIFT Field-free transport none
COLLIMATOR Source registered; no maintained regression input none
BOX Source registered; no maintained regression input none
BEAMBEAM Available soon. optional particle input files
CONSTANTEFIELDCAVITY Uniform electric field none
CONSTANTFOCUSING Collective linear focusing for DIH studies none
QUADRUPOLE Normalized quadrupole none
MULTIPOLE Normalized quadrupole to decapole arrays none
MULTIPOLET Physical multipole coefficients with fringe fields optional time model
SOLENOID Mapped solenoid field field map
FIELDMAP Static magnetic or electric field map; no maintained regression input field map
RFCAVITY Mapped standing-wave or ideal uniform RF field; cyclotron single-gap kick field map or voltage profile, except for TYPE="IDEAL"
TRAVELINGWAVE Traveling-wave RF field field map
CYCLOTRONSECTOR PSI-style cyclotron sector field field map and optional trim coils
LASER Source registered; TRACK rejects it none
MONITOR Source registered; no maintained regression input output file
MARKER Source registered; no maintained regression input none
PROBE Cyclotron segment recording; coasting and RF integration checks .h5/.loss, .hist, .peaks
RBEND, SBEND Source registered; no maintained regression input none
SCALINGFFAMAGNET Source registered; see scaling FFA interface optional end-field model
VARIABLE_RF_CAVITY Source registered; no maintained regression input time models

The Element Physics chapter contains derivations and benchmarks where available.

12.1 Common element syntax

Every element uses

name: ELEMENTTYPE, L=length, placement, type_specific_parameters;

and accepts the following common attributes.

Parameter Default Current behavior
L unset (\(0\,\mathrm m\) when read) Nominal element length. Use a positive value for the element kernels documented here.
ELEMEDGE unset Places the entrance at path length \(s\) in metres. May be combined with PSI, but not with absolute pose attributes.
X, Y, Z 0 m Absolute lab-frame origin. Explicitly set at least one of X, Y, Z, THETA, or PHI to select pose placement.
THETA, PHI, PSI 0 rad Absolute rotations about local \(y\), \(x\), and \(z\). PSI is also the optional roll for ELEMEDGE placement.
DX, DY, DZ 0 m Local translational misalignment applied after placement. It moves the element for the particles only; the reference particle sees the element at its nominal place.
DTHETA, DPHI, DPSI 0 rad Local rotational misalignment.
APERTURE none Transverse aperture string, for example CIRCLE(0.02), ELLIPSE(0.03,0.02), RECTANGLE(0.03,0.02), or SQUARE(0.02). Dimensions are full widths in metres. Other shapes and a third argument are rejected. Without it, the element has no transverse limit. See Particle removal.
DELETEONTRANSVERSEEXIT TRUE Requests particle deletion when an element reports a transverse aperture exit.
TYPE unset Type-specific selector, used by RFCAVITY and MONITOR below. Only listed values are accepted: STANDING, SINGLEGAP and IDEAL for RFCAVITY; RING, CARBONCYCL, CYCIAE, AVFEQ, FFA, BANDRF, SYNCHROCYCLOTRON, SINGLEGAP, STANDING, TEMPORAL and SPATIAL for other elements.

Exactly one placement strategy is required. Supplying both ELEMEDGE and an absolute pose fails; supplying neither also fails. PSI alone does not select absolute placement. All elements of one line must use the same strategy: a line that mixes ELEMEDGE and absolute poses is rejected. MARKER is the exception; its placement attributes are ignored.

These placement rules have element-specific exceptions: PROBE uses its detector endpoints, FIELDMAP requires an absolute pose, and SCALINGFFAMAGNET uses its dedicated aperture dimensions and rejects APERTURE. The following sections give those interfaces.

12.1.1 Particle removal: APERTURE, COLLIMATOR, and BOX

Three inputs delete particles from the beam.

Input Deletes particles Where Use it for
APERTURE outside the given shape most elements, see below the beam pipe or the bore of a magnet or cavity
COLLIMATOR outside its APERTURE a field-free element that must have APERTURE and L > 0 an aperture restriction with no field, such as an iris
BOX inside a block, \(\lvert x\rvert <\) WIDTH/2 and \(\lvert y\rvert <\) HEIGHT/2 a field-free element, moved and tilted by its placement a piece of material beside the beam, such as one collimator jaw

COLLIMATOR is a DRIFT with an APERTURE; it only refuses to run without one. BOX is the reverse of an aperture: the beam passes around it, not through it.

All three follow the same rules:

  • The check runs once per time step, after the particles are moved, in the element’s local frame. Only particles with \(0 \le z < L\) in that frame are checked.
  • A particle that moves more than L in one step can pass an element without being checked. Keep the step length \(\beta c\,\Delta t\) well below L.
  • The boundary itself counts as outside: a particle exactly on it is deleted by APERTURE and COLLIMATOR and kept by BOX.
  • DELETEONTRANSVERSEEXIT=FALSE turns deletion off for that element.
  • BOX rejects APERTURE. RBEND and SBEND accept it only with HGAP > 0 and a vertical half-width no larger than HGAP; see bends. MARKER ignores it.
  • MULTIPOLE, QUADRUPOLE, RBEND, SBEND and RFCAVITY with TYPE="IDEAL" apply their field only inside the aperture. With DELETEONTRANSVERSEEXIT=FALSE, a particle outside it is kept but sees no field from that element.
  • No loss file is written. Deleted particles reduce numParticles in the .stat file. With --info 2, the log reports how many particles were marked for deletion in each step.

12.2 DRIFT

DRIFT defines a field-free interval. It advances particles only through the normal tracker integration and provides the reference-path geometry between active elements.

D1: DRIFT, L=0.5, ELEMEDGE=0.0;
Parameter Default Current behavior
L unset Drift length in metres; use a positive value.

12.3 COLLIMATOR

COLLIMATOR is a field-free element that deletes every particle outside its APERTURE while the particle is inside the element body. It behaves like a DRIFT with an APERTURE, but an input without APERTURE or with L <= 0 is rejected.

C1: COLLIMATOR, L=0.1, ELEMEDGE=1.0, APERTURE="RECTANGLE(0.02,0.01)";
Parameter Default Current behavior
L required Body length in metres; must be positive.
APERTURE required Opening that particles must stay inside, as described under common element syntax. Dimensions are full widths.

The collimator models no material: particles are either kept or deleted. See Particle removal for how it differs from BOX.

12.4 BOX

BOX is a field-free solid block that deletes every particle inside it. In the element’s local frame the block covers \(\lvert x\rvert <\) WIDTH/2, \(\lvert y\rvert <\) HEIGHT/2, and \(0 \le z <\) L. Use it for material that the beam should pass around, such as a collimator jaw.

The block is centred on its local \(z\) axis. To move it beside the beam, use the normal placement: X, Y, Z and the angles for pose placement, or DX and DY with ELEMEDGE. This jaw covers \(0 < x < 20\,\mathrm{mm}\) and \(\lvert y\rvert < 5\,\mathrm{mm}\), so the reference particle passes along its \(-x\) face:

JAW: BOX, L=0.1, X=0.01, Z=0.5, WIDTH=0.02, HEIGHT=0.01;

Two blocks on either side of the beam form a jaw pair. This pair leaves a \(10\,\mathrm{mm}\) horizontal gap:

JAW_L: BOX, L=0.1, X=-0.015, Z=0.5, WIDTH=0.02, HEIGHT=0.05;
JAW_R: BOX, L=0.1, X= 0.015, Z=0.5, WIDTH=0.02, HEIGHT=0.05;
Parameter Default Current behavior
L required Block length along local \(z\) in metres; must be positive.
WIDTH required Full block width along local \(x\) in metres; must be positive.
HEIGHT required Full block height along local \(y\) in metres; must be positive.

BOX does not accept APERTURE. OPALX treats an element as present along the reference trajectory only where the reference particle is inside the element’s aperture, so the aperture of a block beside the beam must stay open. The block models no material: particles are either kept or deleted. See Particle removal for how it differs from APERTURE and COLLIMATOR.

12.5 BEAMBEAM

Availability: Available soon.

BEAMBEAM defines a single-pass interaction between a tracked primary bunch and its counter-propagating mirrored primary. Selected additional particle containers are passive witnesses: they receive the primary fields but do not contribute charge to this interaction. The mirror is not an additional BEAM.

ImportantExperimental, restricted collision model

Use one BEAMBEAM in a single-pass LINE, with an OPEN field solver. Multiple interaction occurrences and RING/TURNS tracking are rejected. The frozen/rigid-source approximation is intentional; this is not a general self-consistent simulation of two independently evolving bunches.

IP1: BEAMBEAM,
    L=0.32, ELEMEDGE=0.01,
    APERTURE="CIRCLE(0.30)",
    COPY_TIME=1.0e-30,
    BBRIGID=TRUE,
    WITNESS_CONTAINERS="1,2",
    VISUALIZE=FALSE;

This definition places the IP at \(s=0.17\,\mathrm m\). The aperture diameter is \(0.30\,\mathrm m\); its radius is \(0.15\,\mathrm m\). This is an element fragment: define the beams, distributions, field solver, and TRACK separately.

Parameter Default Unit Meaning
L unset m Physical element length; use a positive value. The IP is its placed midpoint.
COPY_TIME 0 s Positive absolute simulation-time threshold enabling the mirrored field during an active interaction. Zero disables the mirror, rather than activating it immediately. Negative values are rejected.
BBRIGID FALSE boolean Suppress the primary’s BeamBeam collective kick, but retain deposition and the mesh field for witnesses. Ordinary motion and external fields remain active.
WITNESS_CONTAINERS "NONE" string Comma-separated indices in TRACK.BEAMS, e.g. "1,2". Source index 0 is forbidden; indices must be below 53 and exist in the run.
VISUALIZE FALSE boolean Enable the ASCII interaction-window visualization, independently of field activation.
GEOMETRY unset string Accepted compatibility attribute; the current implementation does not apply a named boundary geometry through it.

Use a small positive COPY_TIME to enable the mirror at the first positive-time active solve. COPY, IP_S, and RETIRE_TIME are not supported controls.

12.5.1 Beams and timed witnesses

The list BEAMS={PrimaryElectrons, WitnessElectrons, WitnessPositrons} assigns indices 0, 1, and 2. Define separate witness BEAM objects with PARTICLE=ELECTRON and PARTICLE=POSITRON respectively, each using a distinct distribution object. Set ORBITTHREADER=FALSE on passive witness beams to reuse the primary reference-orbit map; their physical momenta and trajectories are still independent.

Use EMITTEDFROMFILE for individual birth times. Positions are in metres, momenta in \(p/(m_e c)\), and birth times in seconds. Set the emission-source position and T0 to align the input clock with primary overlap at the IP. A common FROMFILE/T0 injection is not equivalent to individually timed births.

12.5.2 Field region and restrictions

Physical length and aperture are not the numerical field box. The current longitudinal field window is fixed internally to IP \(\pm10\) mm. Transversely, the mesh uses a padded, non-shrinking primary-plus-witness envelope and a cell-aspect constraint.

For ELEMEDGE placement, the interaction owns collective-field policy before the primary reaches that window: ordinary space charge is suppressed while inactive. Once the primary tail passes the downstream boundary, the interaction completes, witness gathering stops, and ordinary space charge remains suppressed. Completion does not delete particles; normal transport, external fields, and aperture handling continue.

Use TYPE=OPEN with open boundaries; the validated relativistic setup uses GREENSF=INTEGRATED and one velocity bin. Do not combine this fixed-domain interaction with cathode/image-charge Dirichlet planes or FFT2D5. A larger physical aperture does not establish adequate field resolution. Check the witness trajectories against the numerical longitudinal region.

BB-DIAG messages identify Inactive, Active, and Completed and report source, copy, and witness status. Per-container outputs follow the normal diagnostic conventions. See Beam-Beam physics for equations, the precise activation rule, model limitations, and CAIN validation.

12.6 CONSTANTEFIELDCAVITY

CONSTANTEFIELDCAVITY adds a uniform Cartesian electric field over its local body interval. It is a DC element and is not processed by the RF autophaser.

Gun: CONSTANTEFIELDCAVITY,
    L=0.5, ELEMEDGE=0.0,
    EX=0.0, EY=0.0, EZ=-5.0;
Parameter Default Unit Current behavior
EX 0 MV/m Uniform local \(E_x\).
EY 0 MV/m Uniform local \(E_y\).
EZ 0 MV/m Uniform local \(E_z\). A negative value accelerates electrons toward local \(+z\).

The field is applied for local \(0<z\le L\) in the particle kernel. Use RFCAVITY or TRAVELINGWAVE when an oscillating mapped RF field is required.

12.7 CONSTANTFOCUSING

CONSTANTFOCUSING adds linear three-dimensional focusing about the current bunch centroid. It was introduced primarily for disorder-induced-heating (DIH) test cases.

Focus: CONSTANTFOCUSING,
    L=1.0e-2, ELEMEDGE=0.0,
    STRENGTH=1.5, RADIUS=1.774e-3;
Parameter Default Unit Current behavior
STRENGTH 1 none Multiplies the initial field scale.
RADIUS 0 m Reference beam radius; a positive value is required.

On its first application, the element fixes

\[ \overline{\mathbf E}_{\mathrm{abs}} =\frac{1}{N}\sum_{i=1}^{N} \begin{pmatrix}|E_{i,x}|\\|E_{i,y}|\\|E_{i,z}|\end{pmatrix}, \qquad g=\frac{\mathrm{STRENGTH}}{\mathrm{RADIUS}} \left\lVert\overline{\mathbf E}_{\mathrm{abs}}\right\rVert_2, \]

then adds

\[ \mathbf E_i \mathrel{+}=g\left(\mathbf R_i-\langle\mathbf R\rangle\right). \]

The gradient \(g\) remains fixed, while the bunch centroid is recomputed. The field is applied only for element-local \(0\le z<L\) and does not affect the reference particle. With positive STRENGTH, it focuses electrons; the force direction reverses with particle charge.

12.8 QUADRUPOLE

QUADRUPOLE is a convenience wrapper around MULTIPOLE. It converts normalized strengths to physical gradients with the rigidity \(B\rho = P_0/c\), where P0 is the global reference momentum in GeV/\(c\) (default 1). P0 is not taken from BEAM; set it with REAL P0 = ...; before the element definitions (see control statements).

Q1: QUADRUPOLE, L=0.5, ELEMEDGE=0.0, K1=0.54;
Parameter Default Unit Current behavior
K1 0 \(\mathrm m^{-2}\) Normalized normal quadrupole strength.
K1S 0 \(\mathrm m^{-2}\) Skew normalized quadrupole strength.
DK1 0 \(\mathrm m^{-2}\) Normal error, added to K1 for both particles and the reference particle.
DK1S 0 \(\mathrm m^{-2}\) Skew error, added to K1S in the same way.

Use a positive L. Although inherited help text mentions integrated zero-length strengths, the field is applied only on \(0\le z<L\), so L=0 gives no field.

The field does not depend on the beam’s charge: the gradient is \(g = B\rho\,K_1\) for every species. A positive K1 focuses positive particles horizontally and defocuses negative particles horizontally.

12.9 MULTIPOLE

MULTIPOLE is a straight multipole from quadrupole to decapole, defined by arrays of normalized normal and skew strengths. Index 0 is the dipole, index 1 the quadrupole, up to index 4, the decapole.

M1: MULTIPOLE, L=0.5, ELEMEDGE=0.0, KN={0.0,0.54,1.2};
Parameter Default Unit Current behavior
KN empty \(\mathrm m^{-(n+1)}\) Normal normalized strengths \(K_n\), index \(n\) from 0 (dipole) to 4 (decapole).
KS empty \(\mathrm m^{-(n+1)}\) Skew normalized strengths with the same indexing.
DKN empty \(\mathrm m^{-(n+1)}\) Normal errors, added to KN for both particles and the reference particle. Missing entries are padded with zero.
DKS empty \(\mathrm m^{-(n+1)}\) Skew errors, added to KS in the same way.

Each array may have at most five entries, and its first (dipole) entry must be zero; otherwise the element is rejected. MULTIPOLE is placed as a straight element, so a dipole field would steer the beam away from it. Use SBEND or RBEND for a dipole.

Particles and the reference particle use the same field for all orders. The strengths are converted with \(B\rho = P_0/c\) from the global P0, as for QUADRUPOLE, and do not depend on the beam’s charge. The field is described in Element Physics. As for QUADRUPOLE, use positive length; L=0 gives no field.

12.10 MULTIPOLET

MULTIPOLET defines straight or constant-radius curved magnetic multipoles using physical field coefficients and a smooth fringe model. It is distinct from the normalized MULTIPOLE interface.

MT1: MULTIPOLET,
    L=0.5, ELEMEDGE=0.0,
    TP={0.0,1.80},
    LFRINGE=0.05, RFRINGE=0.05,
    HAPERT=0.04, VAPERT=0.04;
Parameter Default Unit Current behavior
TP empty \(\mathrm T\,\mathrm m^{-k}\) Physical coefficients \(b_k\): index 0 dipole field, index 1 quadrupole gradient, and higher orders through index 5.
LFRINGE, RFRINGE unset m Left and right tanh-fringe length scales. Set positive values.
HAPERT, VAPERT unset m Internal horizontal and vertical aperture dimensions used by this field model.
MAXFORDER 3 terms Longitudinal fringe expansion order. Must be in \([1,9]\); real input is converted to an integer.
MAXXORDER 20 terms Polynomial expansion order used by the curved implementation; real input is converted to an integer.
ROTATION unset rad Rotation about the central axis for a straight skew element. Must be zero when ANGLE is nonzero.
EANGLE unset rad Entrance angle for curved geometry.
BBLENGTH unset m Half-length used for the field calculation’s bounding region.
ANGLE 0 rad Nonzero selects the constant-radius curved implementation; zero selects straight geometry.
VARRADIUS FALSE Boolean Variable-radius selector. Variable-radius curved magnets are currently rejected.
ENTRYOFFSET 0 m Accepted only with VARRADIUS=TRUE; there is no supported variable-radius curved configuration yet.
SCALING_MODEL unset name Optional TIMEDEPENDENCE object multiplying the magnetic field as a function of time.

The dedicated HAPERT and VAPERT values configure this model’s internal aperture; do not substitute the common APERTURE string for them. The six-entry TP capacity is a runtime limit even though the parser accepts a longer array.

12.11 SOLENOID

SOLENOID loads a magnetic field map. The current mapped-field calculation multiplies the loaded field directly by KS (and by KS+DKS for tracked particles), despite the normalized-strength wording in the input help. The map defines the actual longitudinal field-support interval, which may differ from nominal L.

S1: SOLENOID,
    L=0.5, ELEMEDGE=0.0,
    KS=0.12, FMAPFN="solenoid.T7";
Parameter Default Current behavior
KS unset (\(0\) when read) Direct multiplier on the loaded magnetic field in the current mapped-field calculation. Check the map normalization; the input-help label \(\mathrm m^{-1}\) does not describe the applied scale.
DKS unset (\(0\) when read) Additive scale error for tracked particles; the reference-particle field omits this error.
FMAPFN unset Required field-map filename. Tracking cannot apply a solenoid without a loaded map.
FAST TRUE Parsed but not used.
ZREVERSE FALSE Reverse the map longitudinally and negate its longitudinal magnetic field. Supported only by G4beamline cylinder maps; see field-map restrictions.

The element does not generate an analytic hard-edge solenoid when FMAPFN is missing. Keep the field map beside the input or use an unambiguous relative path.

12.12 FIELDMAP

FIELDMAP places a static field map in the lattice. The map can hold a magnetic field, an electric field, or both. The element has no field of its own: the field comes from the map, and the map’s z range sets the element’s start and length.

The element’s local frame is the map’s own coordinate frame. The 6D pose places the map’s origin, which need not be the start of the map.

ASR61: FIELDMAP,
    X=0.0699, Y=0.0, Z=2.9745,
    THETA=0.349066, PHI=0.0, PSI=0.0,
    FMAPFN="asr61_300d_track.g4blmap", BSCALE=-0.99528;

This places a G4beamline grid map of a bending magnet with its origin at the given lab point, rotated by \(20^\circ\) about \(y\). The map covers \(z=-1.38\) to \(+1.38\,\mathrm m\) in its own frame, so the element starts \(1.38\,\mathrm m\) before its origin and is \(2.76\,\mathrm m\) long. The field is the map times \(-0.99528\).

Parameter Default Unit Current behavior
FMAPFN unset path Required static field map. Accepted types are 2DMagnetoStatic, AstraMagnetoStatic, and G4beamline cylinder and grid maps. Time-dependent maps are rejected; use RFCAVITY or TRAVELINGWAVE for those.
BSCALE 1 none Multiplier on the magnetic field. G4beamline maps are read in tesla as written, so 1 reproduces the map; this is the current= given where G4beamline places the map. 2DMagnetoStatic and AstraMagnetoStatic maps are normalized to an on-axis peak of 1 T unless their header turns that off; for them BSCALE is the peak field in tesla.
ESCALE 1 none Multiplier on the electric field, for a map that holds one (currently G4beamline grid maps only). This is the gradient= given where G4beamline places the map. No effect on a map without an electric field.
ZREVERSE FALSE Boolean Mirror the map in z and negate the longitudinal field, as when the magnet is turned around. This is G4beamline’s rotation=Y180. Only G4beamline cylinder maps accept it.

Restrictions:

  • Place FIELDMAP with a 6D pose (X, Y, Z, THETA, PHI, PSI). ELEMEDGE is rejected. A line uses one placement form, so every other element in the line must use a 6D pose too.
  • L is rejected; the length comes from the map.
  • A particle outside the map’s transverse range gets no field from it. This is not counted as a loss; use APERTURE to remove particles.
  • APERTURE is checked over the map’s z range.
  • AstraMagnetoStatic maps have no transverse range. Give an APERTURE if the beam can leave the region the map describes.
  • A file is loaded once per run, so one file cannot be used with both ZREVERSE settings in the same run.
  • COF and localized TURNS do not accept FIELDMAP.
  • Every MPI rank holds its own copy of the map. See memory use for the size of a grid map.

12.13 RFCAVITY

RFCAVITY selects an RF model with TYPE:

  • STANDING (default): a standing-wave field from a dynamic field map.
  • IDEAL: a uniform longitudinal RF field over the element length, without a field map.
  • SINGLEGAP: a discrete cyclotron voltage-profile kick, described in Accelerated Beam.

The parameters below describe STANDING and IDEAL. The autophased mapped example shows the complete connection to a beam and tracker.

Gun: RFCAVITY,
    L=0.2927, ELEMEDGE=0.0,
    TYPE="STANDING", VOLT=60.0,
    FREQ=1300.0, LAG=0.0,
    FMAPFN="fieldmaps/DriveGun.T7";
Parameter Default Unit Current behavior
TYPE unset (STANDING behavior) name Accepted values are STANDING, SINGLEGAP, and IDEAL. Other input values are rejected.
L unset m IDEAL requires a finite positive length and applies its field on local \(0\le z<L\).
VOLT, DVOLT unset MV/m Nominal peak electric-field amplitude and additive amplitude error for IDEAL; field-map amplitude and additive amplitude error for STANDING.
FREQ unset MHz RF frequency. For STANDING, a field-map value differing by more than 1% replaces it with a warning. IDEAL requires a finite, nonnegative value; zero selects a static field.
LAG, DLAG unset rad Nominal phase and additive phase error, using a cosine convention.
FMAPFN unset path Required for STANDING; supported maps are FM2DDynamic, FM3DDynamic, and Astra1DDynamic. Must be omitted for IDEAL.
FAST TRUE Boolean Parsed but not used.
APVETO FALSE Boolean If true, excludes this cavity from automatic phase optimization.
DESIGNENERGY -1 MeV Positive target exit kinetic energy; the autophaser also adjusts amplitude to reach it. Negative disables the target.
GEOMETRY unset name Parsed boundary-geometry compatibility attribute; not connected by the current element update.
RMIN, RMAX, ANGLE, PDIS, GAPWIDTH, PHI0 unset model-specific Used by the separate SINGLEGAP interface; see the cyclotron guide. They do not configure the STANDING or IDEAL field.
PHASE_MODEL, AMPLITUDE_MODEL, FREQUENCY_MODEL unset name Rejected for IDEAL. For STANDING, names are stored but not resolved into time-dependence objects. Use VARIABLE_RF_CAVITY when RF parameters must vary with time.

The instantaneous electric map scale uses the configured amplitude and \(\cos(2\pi f t+\mathrm{LAG})\); the magnetic map component uses the corresponding sine factor. OPTION.AUTOPHASE>0 searches the reference-particle phase for maximum exit energy, using the option value as the number of refinement passes. This also applies to IDEAL, including amplitude adjustment when DESIGNENERGY>0. Set APVETO=TRUE to retain the specified phase, or OPTION, AUTOPHASE=0; to disable the normal phase search. To preserve a cavity phase also during advancement to TRACK.ZSTART, set APVETO=TRUE on that cavity; the global option is not honored during that initial advancement.

12.13.1 Ideal uniform RF field

RF1: RFCAVITY,
    TYPE="IDEAL", L=0.2, ELEMEDGE=0.0,
    VOLT=5.0, FREQ=100.0, LAG=0.0,
    APVETO=TRUE;

Here VOLT=5.0 sets a peak longitudinal field of 5 MV/m. With L=0.2, the peak integrated voltage is \(5.0\times0.2=1\) MV. At fixed VOLT, changing L changes the field extent and integrated voltage. The field is uniform transversely inside APERTURE and zero outside the cavity’s longitudinal interval. Without APERTURE, there is no transverse field limit. The model adds no magnetic field, fringe fields, or transverse RF focusing.

With \(t\) in seconds, the longitudinal field inside the cavity is

\[ E_z(t)=10^6(\mathrm{VOLT}+\mathrm{DVOLT}) \cos\!\left(2\pi\,10^6\mathrm{FREQ}\,t+\mathrm{LAG}+\mathrm{DLAG}\right) \quad[\mathrm{V/m}]. \]

The reference particle uses the nominal VOLT and LAG, excluding DVOLT and DLAG. All RF parameters must be finite. FMAPFN and named time models are not accepted. The nominal peak integrated voltage is VOLT times L in MV; the actual energy gain also depends on charge, RF phase, and transit time through the cavity.

VARIABLE_RF_CAVITY instead takes an amplitude model in MV/m and uses a sine phase convention. For constant parameters and zero errors, the corresponding amplitude is VOLT and its phase is LAG plus \(\pi/2\). See the ideal RF field model for sampling and transit-time details.

12.14 TRAVELINGWAVE

TRAVELINGWAVE applies a mapped traveling-wave RF structure. It shares the autophase controls with RFCAVITY and additionally describes the repeated-cell geometry.

TW1: TRAVELINGWAVE,
    L=2.8, ELEMEDGE=0.5,
    VOLT=15.0, FREQ=2998.0, LAG=0.0,
    FMAPFN="traveling-wave.T7",
    NUMCELLS=84, MODE=0.3333333333;
Parameter Default Unit Current behavior
VOLT, DVOLT unset MV/m Nominal field-map amplitude and additive error.
FREQ unset MHz RF frequency converted internally to angular frequency.
LAG, DLAG unset rad Nominal phase and additive phase error.
FMAPFN unset path Required traveling-wave field map. It must be an Astra1DDynamic map whose \(z\) range starts at 0.
FAST TRUE Boolean Parsed but not used.
APVETO FALSE Boolean Excludes the structure from automatic phase optimization when true.
NUMCELLS unset cells Number of cells, converted from real input to an integer. Use a positive integer.
MODE 1/3 turns RF phase advance between neighboring cells, expressed as a fraction of \(2\pi\).
DESIGNENERGY -1 MeV Positive autophaser target exit kinetic energy; negative disables the target. Traveling-wave target-energy tuning is incomplete; do not rely on it to set a consistent field amplitude throughout the structure.

Use a regression-matched map, cell count, and mode as one consistent set. As with RFCAVITY, use APVETO=TRUE to preserve this element’s prescribed phase, including advancement to TRACK.ZSTART. AUTOPHASE=0 disables the normal search but is not honored during that initial advancement.

12.15 CYCLOTRONSECTOR

CYCLOTRONSECTOR loads a PSI median-plane magnetic sector map and applies it as one explicitly placed sector of a cyclotron RING. It may reference named TRIMCOIL definitions that add full-azimuth radial correction fields.

TC1: TRIMCOIL, TYPE="PSI-BFIELD-MIRRORED",
     RMIN=4.350, RMAX=4.470, BMAX=1.4E-3, SLPTC=600.0;

SM0: CYCLOTRONSECTOR, FMAPFN="bfield.dat", SYM=8,
     RMIN=1.9, RMAX=4.7, VMIN=-0.05, VMAX=0.05,
     BSCALE=1, TRIMCOIL={"TC1"}, X=3.3, Y=0, Z=0, THETA=0;
Parameter Default Unit Current behavior
FMAPFN unset path Required PSI sector field-map filename.
SYM 8 count Integer sector symmetry; must be at least 2 and match the map span.
RMIN, RMAX map bounds m Optional bounds. If supplied, they must match the field-map radii.
VMIN, VMAX -0.05, 0.05 m Vertical support range for field evaluation.
BSCALE 1 none Multiplier applied to the base sector map.
TRIMCOIL empty names String array naming previously defined TRIMCOIL objects.

A TRIMCOIL definition currently supports TYPE="PSI-BFIELD-MIRRORED" with finite SI parameters 0<RMIN<RMAX, BMAX in tesla, and positive SLPTC in inverse metres. The trim-coil profile has tails; RMIN and RMAX describe the shape radii, not hard field-support cutoffs.

Use explicit absolute placement for each sector occurrence. The common ELEMEDGE placement form is not appropriate for cyclotron sectors in new input files.

12.16 LASER

LASER defines an analytic laser pulse. The definition is accepted, but a TRACK whose line contains a LASER stops with the error Tracking of the "LASER" element is not implemented yet.

L1: LASER, L=0.0, ELEMEDGE=0.0,
    WAVELENGTH=800e-9, PULSEENERGY=1.0,
    PULSELENGTH=30e-15, WAISTX=20e-6, WAISTY=20e-6,
    DIR={0,0,-1}, STOKES={1,0,0};
Parameter Unit Constraint
WAVELENGTH m Required and greater than zero.
PULSEENERGY J Required and greater than zero.
PULSELENGTH s Required and greater than zero.
WAISTX, WAISTY m Required and greater than zero.
DIR none Required nonzero three-vector; OPALX normalizes it.
STOKES none Optional three-vector with \(\xi_1^2+\xi_2^2+\xi_3^2\le1\).
L m Optional non-negative body length.

12.17 MONITOR

MONITOR samples the bunch at a placed diagnostic plane. It adds no field and does not remove the particles it records.

M1: MONITOR, L=0.01, ELEMEDGE=0.5, TYPE=SPATIAL, OUTFN="monitor.h5";
Parameter Default Current behavior
L at least 0.01 m at update Element geometry length. Sampling takes place at the local \(z=0\) plane, rather than throughout this length.
TYPE spatial collection TEMPORAL selects a bunch snapshot triggered by the reference crossing; SPATIAL, another value from the common TYPE list, or no value selects individual spatial crossings. Values outside that list are rejected. Use SPATIAL explicitly for clarity.
OUTFN element name Output stem. A supplied extension is stripped before .h5 or .loss is added.

The monitor accepts the common placement attributes. Its sampling plane is the origin of the placed element frame. Increasing L does not average the bunch over a thicker detector.

12.17.1 Spatial and temporal sampling

Mode What is sampled Longitudinal interpretation
SPATIAL Each particle’s forward crossing of the monitor plane, estimated by a straight drift with its current momentum. Records lie at local \(z=0\), at different arrival times.
TEMPORAL The primary container’s particles, drifted to a common snapshot when the reference particle crosses the plane. Particles retain longitudinal offsets within the bunch; they need not lie on the plane.

For positive timesteps, spatial sampling requires a strict negative-to-positive crossing in local \(z\). A state exactly on either predicted endpoint is not selected by this test. The monitor retains the current momentum; there is no additional field integration to the crossing. See the MONITOR sampling model for the intersection and drift formulas.

Spatial records use the monitor-local coordinates. Temporal positions use a reference-aligned snapshot frame, while the stored momenta and spins are taken from the current particle container, along the bunch-frame axes. These records should not be interpreted as laboratory coordinates without accounting for the corresponding frame.

12.17.2 Output files and timestamps

With OPTION, ASCIIDUMP=FALSE, ENABLEHDF5=TRUE, the particle file is <OUTFN>.h5. With ASCIIDUMP=TRUE, it is <OUTFN>.loss, an ASCII file with position, normalized momentum, particle ID and time. The .loss extension comes from the shared output writer; monitor records are sampled particles, not particle losses.

HDF5 particle datasets include id, x, y, z, px, py, pz, q, m, and time. Positions use metres, normalized momentum is dimensionless, and times use seconds. For a beam with POLARIZATION, the HDF5 file also holds polx, poly and polz, and the ASCII file adds the columns polx, poly and polz after time. The recorded spin is the value at the start of the crossing step; it is not turned to the crossing time. See Spin Tracking. Each saved set also carries reference TIME, mean particle time meanTime, and time spread rmsTime.

HDF5 quantity SPATIAL Current TEMPORAL convention
TIME Reference particle’s estimated crossing time. Reference crossing time, corresponding to the drifted snapshot positions.
Particle time Individual estimated crossing time. Bunch timestep-end time, shared by the snapshot’s particle records.
meanTime Mean of the particle crossing times. Mean of the saved particle timestamps, hence the timestep-end time.
rmsTime Spread of the particle crossing times. Zero for a snapshot with one common saved timestamp; it is not the bunch arrival-time spread.

The temporal timestamp distinction is retained for legacy compatibility: TIME and particle time / meanTime can differ. Use TIME to identify the instant represented by the temporal snapshot positions. For example, a reference crossing at 267.543 ps during a timestep ending at 270 ps can produce positions for 267.543 ps and particle timestamps of 270 ps.

The modes also retain different legacy mass and energy conventions. The HDF5 m, TotalMass, and ENERGY values should not be compared between spatial and temporal records as if they represented the same physical quantities. This distinction does not change the dimensionless momentum components.

The moment and emittance definitions explain the population averages and projected RMS estimators. Applied to spatial records, the \((z,\widetilde p_z)\) emittance is approximately zero because the sampled positions lie on one plane; use the crossing-time distribution for longitudinal arrival information.

12.18 MARKER

MARKER identifies a lattice location without adding a field. It accepts the common placement attributes but ignores them: a MARKER is not placed and does nothing during tracking. Built-in #S and #E markers denote the start and end of a line.

IP: MARKER;

12.19 PROBE

PROBE records crossings of a finite detector segment without removing particles or changing their integration steps. It supports cyclotron-sector tracking and RING particle tracking, including scaling FFAs.

P1: PROBE, XSTART=1900, XEND=4700, YSTART=0, YEND=0,
    STEP=1, OUTFN="radial-probe";
Parameter Unit Behavior
XSTART, XEND mm Segment endpoint laboratory X coordinates.
YSTART, YEND mm Segment endpoint laboratory Z coordinates (legacy cyclotron names).
STEP mm Positive finite width; default 1. Used for cyclotron radial histograms only.
WIDTH — Legacy attribute, unused.
OUTFN path Output basename; defaults to the element name. A supplied extension is removed.

The OPALX cyclotron machine plane is laboratory X–Z; laboratory Y is vertical and is unrestricted by the probe. Endpoints are global laboratory coordinates, independent of the containing sequence’s pose. L, ELEMEDGE and the common placement attributes do not position the probe. Endpoints must be finite and distinct. Cyclotron radial histograms are limited to 10 million bins per probe.

Both crossing directions are recorded; segment endpoints are included. A particle initially on the detector is not recorded until it leaves and returns. A 1 nm excursion from the detector plane arms the next crossing and suppresses near-plane jitter. Crossings are interpolated between accepted particle states. Choose DT small enough to resolve each crossing and keep the probe away from RF kick planes; see crossing accuracy.

For basename radial-probe, crossing output is available for both cyclotron and other supported ring tracking. The radial summaries below are produced only when the lattice contains cyclotron sectors:

  • radial-probe.h5, or radial-probe.loss with OPTION, ASCIIDUMP=TRUE: particle ID, laboratory position [m], mechanical momentum normalized by \(mc\), crossing time [s], zero-based reference turn and container (bunchNumber). HDF5 also stores particle charge [C] and mass [GeV/\(c^2\)].
  • radial-probe.hist (cyclotrons only): counts in radial bins, with bounds and bin width in mm. Radius is measured from the laboratory origin in the X–Z plane.
  • radial-probe.peaks (cyclotrons only): mean crossing radius [mm] for each reference turn with hits, in increasing turn order. These are radial means, not fitted histogram peak locations. Hits from multiple containers with the same turn are pooled.

Accepted probe hits are flushed collectively every 100 tracking steps and at normal completion. HDF5/ASCII records are appended; .hist and .peaks remain cumulative summaries. A collectively reported SINGLEGAP transport error flushes previously accepted crossings before aborting; the failed step is not recorded. A hard process termination can still lose the unflushed batch. Periodic flushing does not enable checkpoint restart.

A cyclotron run without hits writes a zero histogram and header-only .peaks, and no crossing phase-space file. Other rings write crossing .h5 or .loss records only, and create no crossing file when there are no hits. Probe output basenames must be unique and existing probe files are rejected.

Use fresh particle tracking; restart and continuation are unsupported because probe histories and output rewind are not checkpointed. Spectral-tune trial tracking cannot contain PROBE. Independent fresh runs need fresh output basenames. COF skips probes without opening probe output files, so the same RING may be used for the orbit solve and subsequent particle tracking.

For example use four-sector FFA example, and replace its FFA_RING with:

OPTION, ASCIIDUMP=TRUE;
PFFA: PROBE, XSTART=-4420, XEND=-4420,
      YSTART=4000, YEND=4800, STEP=1, OUTFN="ffa-station";
FFA_RING: RING=(M0,M1,M2,M3,PFFA);

Use this same FFA_RING for both COF and TRACK. Endpoints are global X–Z values in millimetres; ring poses do not replicate or reposition the station. The laboratory Y coordinate remains unrestricted. ASCIIDUMP=TRUE selects ffa-station.loss for the example, which disables HDF5. HDF5 probe output requires ENABLEHDF5=TRUE. No .hist or .peaks is produced for this FFA ring.

12.20 RBEND and SBEND

RBEND defines rectangular bend geometry whose L is the straight body length. SBEND defines sector geometry whose L is the design-orbit arc length. Both apply normal and skew dipole and quadrupole fields.

REAL P0 = 0.1;   // GeV/c, reference momentum for the strengths
B1: SBEND, L=0.5, ELEMEDGE=1.0, ANGLE=0.1,
    K1=0.0, HGAP=0.02, FINT=0.5;
Parameter Unit Current behavior
ANGLE rad Bend angle of the design orbit.
K0, K0S \(\mathrm m^{-1}\) Normal and skew dipole strengths. If K0 is omitted, it is derived from ANGLE: ANGLE/L for SBEND, \(2\sin(\mathrm{ANGLE}/2)/L\) for RBEND (ANGLE divided by the arc length when E1 or E2 is given). A given K0 replaces this value.
K1, K1S \(\mathrm m^{-2}\) Normal and skew quadrupole strengths.
K2, K2S, K3, K3S \(\mathrm m^{-3}\), \(\mathrm m^{-4}\) Parsed but not applied: the field has dipole and quadrupole terms only.
HGAP m Half gap, default 0. HGAP > 0 gives an Enge fringe field reaching five full gaps past each face and a vertical aperture of \(\pm\)HGAP. HGAP = 0 gives a hard edge and no aperture.
FINT none Fringe integral, default 0.5. Used only with HGAP > 0, for the vertical edge focusing.
HAPERT m Horizontal half-aperture. Must be positive, needs HGAP > 0, and cannot be combined with APERTURE.
E1, E2 rad RBEND only: entrance and exit pole-face angles, default ANGLE/2 each. They must satisfy E1 + E2 = ANGLE; give one and the other is derived. Each must lie strictly between \(-\pi/2\) and \(\pi/2\). SBEND rejects them.
FMAPFN path RBEND only: a 1DProfile1 fringe-profile file, or "1DPROFILE1-DEFAULT" for OPAL’s default profile. The dipole is then calibrated to ANGLE; K0…K3S and FINT are rejected. SBEND ignores it.
DESIGNENERGY MeV RBEND only: kinetic energy the field is set for. The field is scaled by \(p(\mathrm{DESIGNENERGY})/P_0\). Must be positive. SBEND rejects it.
H1, H2 \(\mathrm m^{-1}\) Pole-face curvature: rejected by RBEND, ignored by SBEND.
GAP, GREATERTHANPI m / — GAP is the full gap for RBEND, instead of HGAP; giving both is rejected. SBEND rejects GAP. GREATERTHANPI is rejected by SBEND and ignored by RBEND.
SLICES, STEPSIZE - Parsed but not used.

The strengths are converted with \(B\rho = P_0/c\) from the global P0 (GeV/\(c\), default 1), as for QUADRUPOLE; set P0 to the beam’s reference momentum. Unlike MULTIPOLE, the bend divides the field by the charge of the beam, so the bend direction is the same for either sign of charge.

APERTURE is accepted only with HGAP > 0, and its vertical half-width must not exceed HGAP. Particles are removed only inside the body, \(0\le s<L\), while the field also acts in the fringe regions.

The classes are registered but currently lack maintained regression inputs. Treat pole-face, fringe, aperture, and sign conventions as experimental until validated for the intended lattice. See Element Physics for the field model.

12.21 SCALINGFFAMAGNET

SCALINGFFAMAGNET defines a horizontal fixed-field alternating-gradient magnet.

SCALINGFFAMAGNET is supported in RING particle tracking, including the TURNS stopping condition, and in static closed-orbit calculations with COF. Use TRACK, INITIALORBIT=... to launch a generated bunch around the solved orbit. See the complete ring example for placement, source definition and orbit handover.

Parameter Unit Default Meaning
B0 T Nominal dipole field at zero height.
R0 m Radial scale \(R_0\). If positive, curvature is towards negative x i.e. anticlockwise. If negative, curvature is towards positive x i.e. clockwise.
FIELD_INDEX The scaling magnet field index \(k\).
TAN_DELTA 0 Spiral factor \(\tan(\delta)\).
MAX_Y_POWER integer 3 Maximum power of \(y\) in the field expansion, limited to 20; real input is rounded down to an integer.
FRINGE_LENGTH m 0.1 Exponential decay constant for the fringe field.
RADIAL_NEG_EXTENT m 1 Field width, from the reference point towards the middle of the ring.
RADIAL_POS_EXTENT m 1 Field width, from the reference point towards the outside of the ring.
HEIGHT m 1 Full height of the field element.
AZIMUTHAL_EXTENT m * Field map cut off in \(\psi\) direction from the element centre. Without a named end-field model, the default is L/2 + 5*FRINGE_LENGTH; with a named model, it is derived from that model’s centre and fringe lengths.
END_FIELD_MODEL If set, enables a field model plugin like ENGE function. Set to the name of the EndFieldModel element.

The SCALINGFFAMAGNET element defines a FFA scaling magnet. Horizontal scaling FFA magnets are defined having a field on the midplane given by

\(B_y = B_0(\psi) \left(\frac{r}{R_0}\right)^k\)

where \(\psi\) is an azimuthal coordinate in the spiral coordinate system, given by

\(\psi = \phi - tan(\delta) \ln\left(\frac{r}{R_0}\right)\)

Normally horizontal FFAs are circular so ScalingFFAMagnet elements are placed using ELEMEDGE on a circle of radius R0 with ELEMEDGE = 0.0 corresponding to (x, y, z) = (0, 0, 0). If R0 is positive, the placements will have an anticlockwise arrangement; the ring curves towards the negative x direction. If R0 is negative, placements will have a clockwise arrangement.

In FFAs the fringe field is particularly important. By default ScalingFFAMagnet applies a tanh fringe field. The e-fold length of the tanh function is defined by FRINGE_LENGTH parameter. Note that if the FRINGE_LENGTH is comparable to L, the field at the magnet centre may never reach B0; the magnet in this case is fringe-field dominated. The END_FIELD_MODEL parameter is a string that selects a named model such as an Enge function. This model replaces the default tanh model and supersedes both L and FRINGE_LENGTH. See End Field Models below for options.

A diagram of the field generated by a SCALINGFFAMAGNET is shown below.

FFA Field Map showing geometrical interpretation of commands. Note that POS and NEG are abbreviations for RADIAL_POS_EXTENT and RADIAL_NEG_EXTENT respectively

This field map was generated from:

FFAMagnet : SCALINGFFAMAGNET, L=0.5, ELEMEDGE=0.5,
            B0=+1.0, R0=R0, FIELD_INDEX=1, TAN_DELTA=0.0, MAX_Y_POWER=5,
            FRINGE_LENGTH=0.05,
            RADIAL_NEG_EXTENT=0.2, RADIAL_POS_EXTENT=0.4, HEIGHT=0.5;

12.22 End Field models

ScalingFFAMagnets use plugin end field models to determine the shape of the fringe field, smoothly varying into the body of the element. Three models are implemented:

  • Tanh
  • Enge
  • AsymmetricEnge

The model’s name is used as a string unique identifier to identify it for later lookup by a field element.

12.22.1 TANH

Parameter Unit Default Meaning
LENGTH m Length of the field model \(L\).
FRINGE_LENGTH m E-fold distance \(\lambda_f\).

TANH end field model generates an end field like

\(f(x) = tanh\left( \frac{x+L/2}{\lambda_f} \right)/2-tanh\left( \frac{x-L/2}{\lambda_f} \right)/2\)

This is implemented in ScalingFFAMagnet by default.

12.22.2 ENGE

Parameter Unit Default Meaning
LENGTH m Length of the field model \(L\).
FRINGE_LENGTH m E-fold distance \(\lambda_f\).
COEFFICIENTS Polynomial coefficients \(c_n\).

Enge end field model generates an end field like

\(f(x) = \frac{1}{1+e^{p(-x - L/2)}}+\frac{1}{1+e^{p(x + L/2)}} - 1\)

where \(p(x)\) is a polynomial like

\(p(x) = c_0 + c_1 \left(\frac{x}{\lambda_f}\right) + c_2 \left(\frac{x}{\lambda_f}\right)^2 + \ldots\)

12.22.3 ASYMMETRIC_ENGE

Parameter Unit Default Meaning
START_HALF_LENGTH m Half length of the end of the field model \(L_s\).
START_FRINGE_LENGTH m E-fold distance \(\lambda_s,f\).
START_COEFFICIENTS List of polynomial coefficients \(c_s,n\).
END_HALF_LENGTH m Half length of the start of the field model \(L_e\).
END_FRINGE_LENGTH m E-fold distance for the end field \(\lambda_e,f\).
END_COEFFICIENTS List of polynomial coefficients for the end field \(c_e,n\).

ASYMMETRIC_ENGE end field model generates an end field like

\(f(x) = \frac{1}{1+e^{p_s(-x - L_s)}}+\frac{1}{1+e^{p(x + L_e)}} - 1\)

where \(p_s(x)\) is a polynomial like

\(p_s(x) = c_s,0 + c_s,1 \left(\frac{x}{\lambda_s,f}\right) + c_s,2 \left(\frac{x}{\lambda_s,f}\right)^2 + \ldots\)

\(p_e(x) = c_e,0 + c_e,1 \left(\frac{x}{\lambda_e,f}\right) + c_e,2 \left(\frac{x}{\lambda_e,f}\right)^2 + \ldots\)

12.23 VARIABLE_RF_CAVITY

VARIABLE_RF_CAVITY applies an ideal, spatially uniform longitudinal electric field within a finite rectangular cavity. Named time-dependence definitions supply its amplitude, frequency, and explicit phase. It is registered for ordinary PARALLEL particle tracking and compatible analytic RING tracking, including the TURNS stopping condition.

Amplitude: POLYNOMIAL_TIME_DEPENDENCE, P0=0.05;  // MV/m
Frequency: POLYNOMIAL_TIME_DEPENDENCE, P0=3.0;   // MHz
Phase: POLYNOMIAL_TIME_DEPENDENCE, P0=0.0;       // rad
VC1: VARIABLE_RF_CAVITY, L=0.2, ELEMEDGE=0.0,
     PHASE_MODEL=Phase, AMPLITUDE_MODEL=Amplitude,
     FREQUENCY_MODEL=Frequency, WIDTH=0.1, HEIGHT=0.1,
     APERTURE="RECTANGLE(0.1,0.1)";
Parameter Expected model output
PHASE_MODEL Phase in radians.
AMPLITUDE_MODEL Electric field in MV/m.
FREQUENCY_MODEL Frequency in MHz.
WIDTH, HEIGHT, L Full cavity dimensions in metres. WIDTH and HEIGHT are required; zero or unset values are rejected when tracking starts.

The field support is \(0\le z<L\), \(|x|\le\mathrm{WIDTH}/2\), and \(|y|\le\mathrm{HEIGHT}/2\) in the element frame. The entrance and transverse faces are included; the longitudinal exit is excluded. Outside this support the cavity adds no field. WIDTH and HEIGHT define field support; the generic APERTURE independently controls particle-loss checks. Set it explicitly when aperture losses should use the same dimensions.

The time models receive the physical time in seconds. Device particle fields and host reference fields use the same Boris midpoint time, \(t+\Delta t/2\), for each accepted step. The cavity adds only local \(E_z\); it has no fringe fields or transverse RF focusing. Its phase is not changed by automatic cavity phasing. For a stationary bunch, choose the RF harmonic from the measured reference return time and set each cavity’s phase using its actual transit time; a zero field at the entrance does not establish zero net energy gain through a finite cavity. See the RF field model.

COF remains a fixed-energy static magnetic calculation and does not accept this element, even with zero amplitude. See the tracking restrictions and orbit handover requirements.

12.23.1 Time-dependence definitions

POLYNOMIAL_TIME_DEPENDENCE
Defines \(f(t)=\sum_i c_i t^i\). When used by VARIABLE_RF_CAVITY, time is in seconds, so coefficient \(c_i\) has model-output units per \(\mathrm{s}^i\). Use either P0 through P3 or COEFFICIENTS, not both.
SINUSOIDAL_TIME_DEPENDENCE
Sums components \(\tfrac{a_i}{2}\sin(2\pi f_i t + \phi_i) + o_i\). The length of FREQUENCIES sets the number of components. PHASE_OFFSETS, AMPLITUDES (peak-to-peak) and DC_OFFSETS are optional; missing entries default to 0, 1 and 0, and extra entries are ignored. With the cavity’s time in seconds, FREQUENCIES are in Hz; these are modulation frequencies, distinct from the MHz output expected by FREQUENCY_MODEL. The current sinusoidal integral has an inconsistent oscillating-amplitude normalization; use a polynomial frequency model when the RF phase must be the integral of its specified frequency.
SPLINE_TIME_DEPENDENCE
Interpolates VALUES at strictly increasing TIMES, in seconds when used by VARIABLE_RF_CAVITY. ORDER=1 selects linear interpolation and ORDER=3 selects cubic interpolation with quadratic smoothing. The ORDER attribute accepts only those two values.

12.24 Current limitations

  • Registration establishes accepted input syntax, not numerical validation. Elements without a maintained regression input are identified above.
  • QUADRUPOLE, MULTIPOLE, RBEND and SBEND take their rigidity from the global P0, not from BEAM. Set P0 to the beam’s reference momentum.
  • RBEND and SBEND apply dipole and quadrupole fields only; K2 and K3 are ignored.
  • LASER cannot be tracked, and MARKER placement attributes have no effect.
  • Field-map elements require their external maps; generated maps and large binary support data belong outside the manual repository.
  • Establish step-size, placement, aperture, and field-map convergence for each production lattice rather than treating a regression configuration as an accuracy prescription.

The following retained OPAL material covers the non-OPAL-CYCL element interfaces from the legacy manual. It is not a statement that these types or attributes are accepted by OPALX.

This chapter is the first mixed migration chapter in the Quarto pilot. It combines:

  • legacy OPAL element semantics ported from the Asciidoctor manual
  • OPALX-native analytic element descriptions already written directly in Quarto

12.25 Element Input Format

All physical elements are defined by statements of the form

label:keyword, attribute,..., attribute

where:

label
is the name given to the element, for example QF. It is an identifier.
keyword
is an element-type keyword, for example QUADRUPOLE.
attribute
usually has the form
attribute-name=attribute-value

Omitted attributes are assigned a default value, normally zero.

Example:

QF: QUADRUPOLE, L=1.8, K1=0.015832;

12.26 Common Attributes for All Elements

The following attributes are shared by all elements.

Attribute Meaning
TYPE Engineering type string used for element selection.
APERTURE Aperture specification such as SQUARE(a,f), RECTANGLE(a,b,f), CIRCLE(d,f), or ELLIPSE(a,b,f).
L Physical element length.
ELEMEDGE Position of the physical start of the element in s.
X, Y, Z Absolute position components when absolute placement is used.
THETA, PHI, PSI Orientation angles relative to the first beamline using absolute positioning.
DX, DY, DZ Position errors that do not affect the design trajectory.
DTHETA, DPHI, DPSI Rotation errors that do not affect the design trajectory.
OUTFN Base file name for element-generated output.
DELETEONTRANSVERSEEXIT Control whether particles exiting on the transverse sides are deleted in OPAL-T.

Dipoles are a special case because GAP and HGAP define their aperture instead of the generic APERTURE attribute.

Default aperture for all other elements is a circle of 1E6 m.

12.27 Drift Spaces

label: DRIFT, TYPE=string, APERTURE=string, L=real;

A DRIFT space has no additional attributes.

Examples:

DR1: DRIFT, L=1.5;
DR2: DRIFT, L=DR1->L, TYPE=DRF;

The length of DR2 will always be equal to the length of DR1. The reference system for a drift space is a Cartesian coordinate system.

12.28 Quadrupole

label: QUADRUPOLE, TYPE=string, APERTURE=real-vector,
      L=real, K1=real, K1S=real;

A QUADRUPOLE is a straight Cartesian magnet with normal and skew quadrupole components.

K1
normal quadrupole gradient \(K_1 = \partial B_y / \partial x\) in \(\mathrm{Tm^{-1}}\). Positive K1 means horizontal focusing for positively charged particles moving in the positive design direction.
K1S
skew quadrupole component \(K_{1s} = - \partial B_x / \partial x\) in \(\mathrm{Tm^{-1}}\).
DK1, DK1S
normalized strength errors for the normal and skew component.

Example:

QP1: QUADRUPOLE, L=1.20, ELEMEDGE=-0.5265, K1=0.11;

12.29 Sextupole

label: SEXTUPOLE, TYPE=string, APERTURE=real-vector,
       L=real, K2=real, K2S=real;

A SEXTUPOLE is a straight Cartesian element with second-order normal and skew components.

K2
normal sextupole strength \(K_2 = \partial^2 B_y / \partial x^2\) in \(\mathrm{Tm^{-2}}\).
K2S
skew sextupole strength \(K_{2s} = - \partial^2 B_x / \partial x^2\) in \(\mathrm{Tm^{-2}}\).
DK2, DK2S
normalized strength errors.

Example:

S1: SEXTUPOLE, L=0.4, K2=0.00134;

12.30 Octupole

label: OCTUPOLE, TYPE=string, APERTURE=real-vector,
      L=real, K3=real, K3S=real;
K3
normal octupole strength \(K_3 = \partial^3 B_y / \partial x^3\) in \(\mathrm{Tm^{-3}}\).
K3S
skew octupole strength \(K_{3s} = - \partial^3 B_x / \partial x^3\) in \(\mathrm{Tm^{-3}}\).
DK3, DK3S
normalized strength errors.

Example:

O3: OCTUPOLE, L=0.3, K3=0.543;

12.31 General Multipole

The legacy MULTIPOLE element defines a thick straight multipole of arbitrary order.

label: MULTIPOLE, TYPE=string, APERTURE=real-vector,
      L=real, KN=real-vector, KS=real-vector;
KN
array of normal coefficients \(K_n = \partial^n B_y / \partial x^n\).
KS
array of skew coefficients \(K_{ns} = - \partial^n B_x / \partial x^n\).
DKN, DKS
normalized strength-error arrays for the normal and skew coefficients.

If L != 0, the strengths are interpreted per unit length. If L == 0, they are integrated strengths. The multipole order of coefficient n corresponds to 2n+2 poles. Superposition of several orders is allowed.

Example:

M27: MULTIPOLE, L=1.0, ELEMEDGE=3.8, KN={0.0, 0.11};

12.32 General Multipole With Fringe Field Model

MULTIPOLET is the extended cyclotron-side multipole element with explicit fringe fields. It can represent either a straight magnet or a curved magnet with a prescribed bend angle.

label: MULTIPOLET, L=real, TP=real-vector,
       LFRINGE=real, RFRINGE=real,
       VAPERT=real, HAPERT=real,
       MAXFORDER=real, ROTATION=real,
       EANGLE=real, BBLENGTH=real, ANGLE=real,
       MAXXORDER=real, VARRADIUS=bool,
       ENTRYOFFSET=real, SCALING_MODEL=string;

The most important attributes are:

TP
transverse mid-plane polynomial coefficients \(T(x) = B_0 + B_1 x + B_2 x^2 + \dots\).
LFRINGE, RFRINGE
left and right fringe-field lengths.
ANGLE
physical bend angle of the magnet.
VARRADIUS
when TRUE, the bend radius can vary so that the reference path remains in the magnet center. This is a cyclotron-side restricted feature.
ROTATION
roll of a straight magnet about its central axis to obtain skew fields.
SCALING_MODEL
optional time-dependent scaling model for the multipole coefficients.

This element uses a fringe-field model based on a scalar-potential expansion with a mid-plane profile multiplied by a longitudinal fringe function.

Example:

M30: MULTIPOLET, L=1, RFRINGE=0.3, LFRINGE=0.2,
     ANGLE=PI/6, TP={2.0, 0.1}, VARRADIUS=TRUE, BBLENGTH=2;

12.33 Solenoid

label: SOLENOID, TYPE=string, APERTURE=real-vector,
      L=real, KS=real;

A SOLENOID has one principal strength attribute:

KS
the solenoid strength \(K_s = \frac{\partial B_s}{\partial s}\), in \(\mathrm{Tm^{-1}}\). For positive KS and positive particle charge, the solenoid field points in the direction of increasing s.

The reference system for a solenoid is a Cartesian coordinate system.

In OPAL-T mode, field maps are specified through:

FMAPFN
file name of the field map.

Example:

SP1: SOLENOID, L=1.20, ELEMEDGE=-0.5265, KS=0.11,
     FMAPFN="1T1.T7";

12.34 RF Cavities

An RFCAVITY is the legacy standing-wave cavity element used in both beamline and cyclotron workflows. The common syntax is:

label: RFCAVITY, APERTURE=real-vector, L=real,
       VOLT=real, LAG=real;
L
cavity length in m.
VOLT
peak RF voltage in MV. The cavity kick is parameterized as \(\delta E = \mathrm{VOLT}\cdot\sin(2\pi(\mathrm{LAG}-\mathrm{HARMON}\cdot f_0 t))\).
LAG
phase lag in rad. In OPAL-T this is generally measured relative to the phase that maximizes the reference-particle energy gain. That phase is found by the auto-phasing algorithm unless the cavity is vetoed.
DLAG
phase-lag error in rad.

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

12.35 Traveling Wave Structure

A TRAVELINGWAVE structure is an OPAL-T element reconstructed from a one-dimensional standing-wave field map and a repeated-cell model.

Figure 12.1: The on-axis field of an S-band TRAVELINGWAVE structure. The field of a single cavity is shown between its entrance and exit fringe fields.

An example of a 1D traveling-wave field map is shown in Figure 12.1. The map itself is a standing-wave solution for a single accelerating cavity. OPAL-T reconstructs the full traveling-wave tank in three parts:

  1. entrance fringe field,
  2. repeated accelerating-cell region,
  3. exit fringe field.

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

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

12.36 Monitor

A MONITOR detects all particles passing it and writes the position, momentum, and time of impact into an H5hut file. It always has an effective length of 1 cm, consisting of a 0.5 cm drift, the monitor of zero length, and another 0.5 cm drift. This prevents OPAL-T from missing particles.

The positions of the particles on the monitor are interpolated from the current position and momentum one step before they would pass the monitor.

OUTFN
file name into which the monitor writes the collected data.

If TYPE=TEMPORAL, the data of all particles are written when the reference particle hits the monitor.

12.37 Collimators

Four collimator families exist in the legacy manual:

  • ECOLLIMATOR: elliptic aperture
  • RCOLLIMATOR: rectangular aperture
  • FLEXIBLECOLLIMATOR: arbitrary aperture description
  • CCOLLIMATOR: cyclotron-specific radial rectangular collimator

The common OPAL-T beamline syntax is:

label: ECOLLIMATOR, TYPE=string, APERTURE=real-vector,
       L=real, XSIZE=real, YSIZE=real;

label: RCOLLIMATOR, TYPE=string, APERTURE=real-vector,
       L=real, XSIZE=real, YSIZE=real;

label: FLEXIBLECOLLIMATOR, APERTURE=real-vector,
       L=real, DESCRIPTION=string, FNAME=string, OUTFN=string;

Common attributes:

OUTFN
file name for lost-particle output. If omitted, the element label is used. The output is written as H5hut, or ASCII when ASCIIDUMP is enabled.

12.37.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.
Figure 12.2: Illustration of a difference between two circles.
Figure 12.3: Illustration of a symmetric difference between two circles.
Figure 12.4: Illustration of an intersection between two circles.

The expression language supports the following constants and functions:

Constants and functions Constants and functions Constants and functions Constants and functions
e pi abs(x) acos(x)
acosh(x) asin(x) asinh(x) atan(x)
atanh(x) cbrt(x) ceil(x) cos(x)
cosh(x) deg2rad(x) erf(x) erfc(x)
exp(x) exp2(x) floor(x) isinf(x)
isnan(x) log(x) log2(x) log10(x)
rad2deg(x) round(x) sgn(x) sin(x)
sinh(x) sqrt(x) tan(x) tanh(x)
tgamma(x) atan2(y,x) max(x,y) min(x,y)
pow(x,n)

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
      )
Figure 12.5: Pepper-pot with rectangular holes.

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.

12.38 Correctors

Three types of correctors are available:

  • HKICKER: horizontal corrector
  • VKICKER: vertical corrector
  • KICKER: combined horizontal and vertical corrector

They are defined as:

label: HKICKER, TYPE=string, APERTURE=real-vector,
      L=real, KICK=real;
label: VKICKER, TYPE=string, APERTURE=real-vector,
      L=real, KICK=real;
label: KICKER, TYPE=string, APERTURE=real-vector,
      L=real, HKICK=real, VKICK=real;

Attributes:

KICK
kick angle in rad for HKICKER or VKICKER.
HKICK, VKICK
horizontal and vertical kick angles for KICKER.
DESIGNENERGY
if set, fixes the magnetic field magnitude using the given design energy in MeV and the requested kick angle.

A positive kick increases \(p_x\) or \(p_y\) respectively.

Examples:

HK1: HKICKER, KICK=0.001;
VK3: VKICKER, KICK=0.0005;
KHV: KICKER,  HKICK=0.001, VKICK=0.0005;

Correctors do not change the reference trajectory. Otherwise they are implemented like RBEND with E1 = 0 and without fringe fields.

12.39 Bending Magnets

The legacy bend families described here are:

  • RBEND for rectangular bends in OPAL-T
  • RBEND3D for rectangular bends with field-map support in OPAL-T
  • SBEND for sector bends in OPAL-T

RBEND and SBEND share the same basic dipole semantics but differ in their reference geometry. RBEND has parallel pole faces and an exit angle fixed by ANGLE - E1; SBEND uses a sector reference arc and supports independent entrance and exit edge angles.

Figure 12.6: Rectangular bend geometry with positive bend angle and positive entrance edge angle.

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

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

Figure 12.7: Sector bend geometry with independent entrance and exit edge angles.

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

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

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

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

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

Figure 12.8: Entrance fringe field profile corresponding to the default Enge parameters.

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.

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

12.40 Variable RF Cavities

VARIABLE_RF_CAVITY extends the hard-edge cavity model by making frequency, amplitude, and phase explicit functions of time:

FREQUENCY_MODEL=string, AMPLITUDE_MODEL=string, PHASE_MODEL=string

The field is modeled as \[ E(t) = a(t)\,\sin\!\left(2\pi \int_0^t f(\tau)\,d\tau + \phi(t)\right) \] with no field outside the cavity boundary and no transverse dependence in the hard-edge model.

Important geometry attributes are WIDTH, HEIGHT, and L.

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

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

12.41 Septum

SEPTUM is a cyclotron-side extraction element. Particles hitting the septum are removed from the bunch and written to the element output file.

Main geometric attributes:

  • XSTART, XEND
  • YSTART, YEND
  • WIDTH
Figure 12.9: Cyclotron SEPTUM geometry.

Example:

eec2: SEPTUM, XSTART=4100.0, XEND=4300.0,
      YSTART=-1200.0, YEND=-150.0, WIDTH=0.05;

Lost particles are written to OUTFN.h5 or ASCII when ASCIIDUMP is enabled. ## Probe {#opal-probe}

PROBE records particles crossing a line-like detector while leaving them in the simulation.

Main attributes:

  • XSTART, XEND
  • YSTART, YEND
  • STEP: histogram step size for the associated probe histogram and peak files
Figure 12.10: Cyclotron PROBE geometry.

Example:

prob1: PROBE, XSTART=4166.16, XEND=4250.0,
       YSTART=-1226.85, YEND=-1241.3;

The hit particles are recorded in OUTFN.h5 (or ASCII with ASCIIDUMP). The same crossings are also accumulated into the .hist and .peaks files that mimic measured probe histograms and their derived peak locations. ## Output Plane {#opal-output-plane}

OUTPUTPLANE records particles crossing a plane in space. Unlike PROBE, the plane can be defined either by a probe-style segment or by an explicit center and normal.

Two placement styles are available:

  • PROBE: uses XSTART, XEND, YSTART, YEND
  • CENTRE_NORMAL: uses CENTRE, NORMAL, together with optional WIDTH, HEIGHT, and RADIUS

Additional controls include:

  • REFERENCE_ALIGNMENT_PARTICLE
  • TOLERANCE
  • ALGORITHM = INTERPOLATION | RK4
  • VERBOSE

In CENTRE_NORMAL mode the plane may realign itself on the first crossing of REFERENCE_ALIGNMENT_PARTICLE so that the plane center and normal follow that reference trajectory.

Example:

outplane1: OUTPUTPLANE, PLACEMENT_STYLE=CENTRE_NORMAL,
           CENTRE={10, 13.5, 0}, NORMAL={1,0,0},
           WIDTH=1.5, HEIGHT=0.8, RADIUS=1,
           ALGORITHM=RK4, VERBOSE=1,
           REFERENCE_ALIGNMENT_PARTICLE=0, OUTFN="FileName.txt";

12.42 Stripper

STRIPPER is the cyclotron extraction element that changes particle charge and mass when a particle hits the stripping foil geometry.

Important attributes are:

  • XSTART, XEND, YSTART, YEND
  • OPCHARGE: output charge state
  • OPMASS: output particle mass
  • OPYIELD: number of outgoing particles per incoming particle
  • STOP: if TRUE, stop the particle after stripping

The geometry matches the PROBE-style line segment. The struck particles are always written to the output file, regardless of STOP. The legacy manual also states explicitly that this element changes charge and mass but does not yet model the full microscopic stripping process.

Example:

prob1: STRIPPER, XSTART=4166.16, XEND=4250.0,
                 YSTART=-1226.85, YEND=-1241.3,
                 OPCHARGE=1, OPMASS=PMASS,
                 OPYIELD=2, STOP=FALSE;

12.43 Degrader

DEGRADER is an OPAL-T particle-matter interaction element with an elliptical transverse profile and length L.

Important attributes are:

  • XSIZE, YSIZE: ellipse axes

If no particle-matter interaction handler is attached, particles hitting the degrader are simply recorded and deleted.

12.44 Vacuum

VACUUM represents interactions with residual gas and, when configured, the associated stripping physics. When an interaction occurs, the particle state at that instant is written out.

MINR and MAXR specify the limits. In OPAL-T, placement is described by the usual L and ELEMEDGE parameters.

Important attributes are:

  • PRESSURE: average residual-gas pressure in mbar
  • TEMPERATURE: gas temperature in K
  • GAS = H2 | AIR
  • STOP: whether the interacting particle is deleted immediately

Cyclotron mode additionally supports a pressure map through:

  • PMAPFN: mid-plane pressure-map file
  • PSCALE: scale factor applied to that map

If PMAPFN is supplied, PRESSURE acts as the default value outside the map extent.

The particles stripped in the residual gas are written to the configured output file regardless of the value of STOP. ## Undulator {#opal-undulator}

UNDULATOR couples the beamline to OPAL’s full-wave FEL solver path. In the legacy implementation the field solve switches from Poisson to a Finite-Difference Time-Domain full-wave model while the bunch traverses the undulator. This path relies on the external MITHRA library.

To use this feature, OPAL must be built with MITHRA support:

  1. install the MITHRA library,
  2. set MITHRA_PREFIX to its installation path,
  3. configure OPAL with -DENABLE_OPAL_FEL=yes.

When the head of the bunch crosses the undulator start, the solver switches to full-wave and returns to Poisson once the bunch has passed the undulator and its fringe fields.

The effective undulator length is determined by the number of periods and the built-in fringe extent, \[ L = N\lambda + 2\,\mathrm{fringe}, \qquad \mathrm{fringe} = 2\lambda, \] so there is no separate user-supplied L parameter.

The idealized planar-undulator field is \[ B_x = B_0\cosh(kr)\sin(kz)\cos(\alpha), \] \[ B_y = B_0\cosh(kr)\sin(kz)\sin(\alpha), \] \[ B_z = B_0\sinh(kr)\cos(kz), \] with \(k = 2\pi/\lambda\) and polarization angle \(\alpha\).

Important attributes are:

  • K: undulator strength parameter
  • LAMBDA: undulator period
  • NUMPERIODS: number of periods
  • ANGLE: polarization angle
  • MESHLENGTH: computational-domain size in the moving bunch frame
  • MESHRESOLUTION: computational-grid spacing
  • DTBUNCH: particle update timestep
  • TRUNORDER: absorbing-boundary truncation order
  • TOTALTIME: total full-wave simulation time
  • FNAME: optional job/output description file for the full-wave solver

Example:

UND: UNDULATOR, ELEMEDGE = 44.0e-2, K = 10.81, LAMBDA = 8.5e-2, NUMPERIODS = 10, ANGLE = PI/2,
     MESHLENGTH = { 12e-3, 12e-3, 4e-3 }, MESHRESOLUTION = { 1e-5, 1e-5, 8e-6},
     FNAME = "wiggler_sims_July_2020/mithra_output.job";