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
Lin one step can pass an element without being checked. Keep the step length \(\beta c\,\Delta t\) well belowL. - The boundary itself counts as outside: a particle exactly on it is deleted by
APERTUREandCOLLIMATORand kept byBOX. DELETEONTRANSVERSEEXIT=FALSEturns deletion off for that element.BOXrejectsAPERTURE.RBENDandSBENDaccept it only withHGAP > 0and a vertical half-width no larger thanHGAP; see bends.MARKERignores it.MULTIPOLE,QUADRUPOLE,RBEND,SBENDandRFCAVITYwithTYPE="IDEAL"apply their field only inside the aperture. WithDELETEONTRANSVERSEEXIT=FALSE, a particle outside it is kept but sees no field from that element.- No loss file is written. Deleted particles reduce
numParticlesin the.statfile. 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.
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
FIELDMAPwith a 6D pose (X,Y,Z,THETA,PHI,PSI).ELEMEDGEis rejected. A line uses one placement form, so every other element in the line must use a 6D pose too. Lis 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
APERTUREto remove particles. APERTUREis checked over the map’s z range.AstraMagnetoStaticmaps have no transverse range. Give anAPERTUREif the beam can leave the region the map describes.- A file is loaded once per run, so one file cannot be used with both
ZREVERSEsettings in the same run. COFand localizedTURNSdo not acceptFIELDMAP.- Every MPI rank holds its own copy of the map. See memory use for the size of a
gridmap.
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, orradial-probe.losswithOPTION, 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.

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 eitherP0throughP3orCOEFFICIENTS, not both. SINUSOIDAL_TIME_DEPENDENCE-
Sums components \(\tfrac{a_i}{2}\sin(2\pi f_i t + \phi_i) + o_i\). The length of
FREQUENCIESsets the number of components.PHASE_OFFSETS,AMPLITUDES(peak-to-peak) andDC_OFFSETSare optional; missing entries default to 0, 1 and 0, and extra entries are ignored. With the cavity’s time in seconds,FREQUENCIESare in Hz; these are modulation frequencies, distinct from the MHz output expected byFREQUENCY_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
VALUESat strictly increasingTIMES, in seconds when used byVARIABLE_RF_CAVITY.ORDER=1selects linear interpolation andORDER=3selects cubic interpolation with quadratic smoothing. TheORDERattribute 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,RBENDandSBENDtake their rigidity from the globalP0, not fromBEAM. SetP0to the beam’s reference momentum.RBENDandSBENDapply dipole and quadrupole fields only;K2andK3are ignored.LASERcannot be tracked, andMARKERplacement 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
K1means 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
KSand positive particle charge, the solenoid field points in the direction of increasings.
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
T7format. TYPE-
cavity type, either
STANDING(default) orSINGLEGAP. 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 equalsLAGat 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.
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:
- entrance fringe field,
- repeated accelerating-cell region,
- 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, soLis 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
T7format. FREQ-
traveling-wave frequency in
MHz. As forRFCAVITY, 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 example1/3stands for a2π/3structure. FAST-
if
TRUEand 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
LAGdirectly 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 apertureRCOLLIMATOR: rectangular apertureFLEXIBLECOLLIMATOR: arbitrary aperture descriptionCCOLLIMATOR: 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
ASCIIDUMPis 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
PBMbitmap 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
command1but notcommand2. 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
Ntimes with a translational offset. repeat(command, N, angle)-
repeat a shape
Ntimes with successive rotation.
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
)
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 correctorVKICKER: vertical correctorKICKER: 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
radforHKICKERorVKICKER. HKICK,VKICK-
horizontal and vertical kick angles for
KICKER. DESIGNENERGY-
if set, fixes the magnetic field magnitude using the given design energy in
MeVand 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:
RBENDfor rectangular bends in OPAL-TRBEND3Dfor rectangular bends with field-map support in OPAL-TSBENDfor 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.
12.39.1 RBEND
Key attributes are:
L: physical magnet lengthGAP: full vertical gapHAPERT: non-bend-plane apertureANGLE: bend angle inradK0,K0S: normal and skew dipole field amplitudes inTE1: entrance edge angleDESIGNENERGY: reference-particle energy inMeVFMAPFN: fringe-field map, typically1DProfile1
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.
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:
- Internally OPAL-T treats all bends as positive bends in the local reference frame and then uses
ROTATIONto orient them in the laboratory transverse plane. - If
ANGLEis nonzero,K0andK0Sare ignored. - When
ANGLEis used to define the bend strength, the actual beam bend still depends on whether the bunch energy matchesDESIGNENERGY. - The hard-edge geometry defines the ideal reference trajectory, while the
FMAPFNfield map defines the soft-edge magnet seen by tracked particles. - If the default field map
1DPROFILE1-DEFAULTis 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:
- the map defines both the fringe fields and the magnet length,
- the map defines only the fringe fields and the element
Ldefines 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:
- entrance fringe field
- central field region
- 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 fromK1,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..P3or a longerCOEFFICIENTSarray. SPLINE_TIME_DEPENDENCE-
uses tabulated
TIMESandVALUESwithORDER=1or3. SINUSOIDAL_TIME_DEPENDENCE-
sums one or more sine waves from arrays
FREQUENCIES,AMPLITUDES,PHASE_OFFSETS, andDC_OFFSETS.
12.40.2 Soft-edged variable cavities
For soft-edged cavities, VARIABLE_RF_CAVITY_FRINGE_FIELD adds:
CENTRE_LENGTHEND_LENGTHCAVITY_CENTREMAX_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,XENDYSTART,YENDWIDTH
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,XENDYSTART,YENDSTEP: histogram step size for the associated probe histogram and peak files
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: usesXSTART,XEND,YSTART,YENDCENTRE_NORMAL: usesCENTRE,NORMAL, together with optionalWIDTH,HEIGHT, andRADIUS
Additional controls include:
REFERENCE_ALIGNMENT_PARTICLETOLERANCEALGORITHM = INTERPOLATION | RK4VERBOSE
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,YENDOPCHARGE: output charge stateOPMASS: output particle massOPYIELD: number of outgoing particles per incoming particleSTOP: ifTRUE, 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 inmbarTEMPERATURE: gas temperature inKGAS = H2 | AIRSTOP: whether the interacting particle is deleted immediately
Cyclotron mode additionally supports a pressure map through:
PMAPFN: mid-plane pressure-map filePSCALE: 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:
- install the MITHRA library,
- set
MITHRA_PREFIXto its installation path, - 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 parameterLAMBDA: undulator periodNUMPERIODS: number of periodsANGLE: polarization angleMESHLENGTH: computational-domain size in the moving bunch frameMESHRESOLUTION: computational-grid spacingDTBUNCH: particle update timestepTRUNORDER: absorbing-boundary truncation orderTOTALTIME: total full-wave simulation timeFNAME: 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";