Lattice Element Kinds

Lattice Element Kinds#

The following details the different kinds of lattice elements and the associated parameter groups. For documentation on lattice elements in general see here.

Magnets and RF Cavities#

The following element kinds involve applied electromagnetic fields in vacuum.

Beam and Plasma Elements#

The following element kinds involve interactions with the mean field of a particle distribution.

Sources and Collimation#

The following element kinds are for producing or removing beam particles.

Instrumentation and Diagnostics#

The following element kinds are for instrumentation and diagnostics.

Map Elements#

The following element kinds specify transport maps through an element without regard to the physical fields present.

Bookkeeping Elements#

The following element kinds provide relationships among branches and coordinate systems.

Structural and Grouping Elements#

The following element kinds describe composite elements and support structures.

External Circuits#

The following element kinds describe machine components “external” to any beam lines. For example, control or feedback circuits.

Kinds Definitions#

ACKicker Element#

An ACKicker element simulates a time-dependent kicker. It is like a Kicker element except that the field varies in time. This element requires a user supplied time-dependent expression.

Element parameter groups associated with this element kind are:

Example:

ack1:
  kind: ACKicker
  length: 0.3
  ACKickerP:

BeamBeam Element#

A BeamBeam element defines the parameters of a oppositely moving “strong” beam that generates electromagnetic fields at the interaction point. This strong beam is assumed to have a three-dimensional (3D) Gaussian density distribution.

Element parameter groups associated with this element kind are:

  • ApertureP: Aperture parameters.

  • BeamBeamP: Beam-beam interaction parameters.

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • FloorP: Floor position and orientation.

  • MetaP: Meta parameters.

  • ReferenceP: Output Parameters. Reference parameters.

  • TrackingP: Tracking parameters.

Example:

bb1:
  kind: BeamBeam
  BeamBeamP:
    sigma_x: 0.1e-3
    sigma_y: 0.1e-3
    sigma_z: 5.0e-2
    energy: 1.0e10
    N_particle: 1.0e11

The length of this element is considered to be zero so if length is specified, it must be zero.

BeginningEle Element#

A BeginningEle element is an initial element at start of a branch. Under Construction…

Element parameter groups associated with this element kind are:

  • ApertureP: Aperture parameters.

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • FloorP: Floor position and orientation.

  • MetaP: Meta parameters.

  • ReferenceP: Output Parameters. Reference parameters.

  • TrackingP: Tracking parameters.

The length of this element is considered to be zero so if length is specified, it must be zero.

Bend Elements: RBend and SBend#

Dipole bend. There are two kinds of bends depending upon the “logical shape”. The RBend element has a “rectangular” logical shape and the SBend element has a “sector” logical shape.

Element parameter groups associated with this element kind are:

RBend and SBend elements are parameterized exactly the same way by the BendP parameter group. For example, e1 and e1_rect have the same meaning for both kinds of bends.

The logical shape of a bend, in most situations, is irrelevant. The only case where the logical shape can be used by a program is when the bend angle is varied. In this case, for a SBend, the face angles e1 and e2 can be held constant and e1_rect and e2_rect can be varied to keep the relationship between e1 and e1_rect, and e2 and e2_rect satisfied as discussed in the BendP documentation. Similarly, for a RBend, the face angles e1_rect and e2_rect can be held constant and e1 and e2 can be varied to keep the relationship between e1 and e1_rect, and e2 and e2_rect satisfied.

Converter Element#

A Converter element represents a target (plate) onto which particles are slammed in order to generate particles of a different type. For example, a tungsten plate which is bombarded with electrons to generate positrons.

Under Construction…

Element parameter groups associated with this element kind are:

CrabCavity Element#

A CrabCavity element is an zero length RF cavity that gives a longitudinal dependent transverse kick.

Element parameter groups associated with this element kind are:

Example:

cc1:
  kind: CrabCavity
  RFP:
    frequency: 394.0e6 
    phase: 0.0
    voltage: 1.0e6

Drift Element#

A Drift element is a space free and clear of any fields.

Element parameter groups associated with this element kind are:

  • ApertureP: Aperture parameters.

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • FloorP: Floor position and orientation.

  • MetaP: Meta parameters.

  • ReferenceP: Output Parameters. Reference parameters.

  • TrackingP: Tracking parameters.

Example:

d01:
  kind: Drift
  length: 2.07
  MetaP:
    description: "Blueprint: 4596-32A"

EGun Element#

An EGun element represents an electron gun and encompasses a region starting from the cathode were the electrons are generated.

Under Construction…

Element parameter groups associated with this element kind are:

Feedback Circuit Element#

A Feedback element is an element used to simulate a feedback circuit. It gathers information about particle trajectories from the inputs and uses this to either adjust beam trajectories in the outputs and/or adjust parameters in the outputs. A feedback element could be used, for example, to simulate RF feedback systems or beam position feedback, or cooling of a proton beam by a beam of electrons.

Under Construction…

Note: This element does not have a length nor an s_position.

Fiducial Element#

A Fiducial element is used to fix the position and orientation of the reference orbit within the global coordinate system at the location of the fiducial element. A fiducial element will affect the global floor coordinates of elements both upstream and downstream of the fiducial element.

Under Construction…

The length of this element is considered to be zero so if length is specified, it must be zero.

FloorShift Element#

Global coordinates shift.

A FloorShift element shifts the reference curve in the global coordinate system without affecting particle tracking. That is, in terms of tracking, a FloorShift element is equivalent to a Marker element where a particle’s position is unchanged going through the element.

Also see patch and fiducial elements.

Element parameter groups associated with this element kind are:

Foil Element#

A Foil element represents a planar sheet of material which can strip electrons from a particle. In conjunction, there will be scattering of the particle trajectory as well as an associated energy loss. Material that can strip electrons from a particle will also cause energy loss and diffusion.

Under Construction…

Element parameter groups associated with this element kind are:

  • ApertureP: Aperture parameters.

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • FloorP: Floor position and orientation.

  • FoilP: Foil parameters.

  • MetaP: Meta parameters.

  • ReferenceP: Output Parameters. Reference parameters.

  • TrackingP: Tracking parameters.

Fork Element#

A Fork element marks the start of an alternative branch for the beam or for X-rays or other particles generated by the beam to follow. This element is used to connect lattice branches together.

A Fork element has zero length and must always have a ForkP parameter group. Besides the ForkP documentation, see the Forking section for more details.

Element parameter groups associated with this element kind are:

  • ApertureP: Aperture parameters.

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • FloorP: Floor position and orientation.

  • ForkP: Required. Fork element parameters.

  • MetaP: Meta parameters.

  • ReferenceP: Output Parameters. Reference parameters.

  • TrackingP: Tracking parameters.

Girder Element#

A Girder element is a support structure that orients the elements that are attached to it in space. This element can be used to simulate any rigid support structure and there are no restrictions on how the lattice elements that are supported are oriented with respect to one another.

Under Construction…

Note: This element does not have a length nor an s_position.

Instrument Element#

An Instrument element is a measurement element for diagnostics.

Under Construction…

Element parameter groups associated with this element kind are:

Kicker Element#

A Kicker element is an element that can deflect a beam transversely in both planes. It uses a zero-order (electric or magnetic) multipole field, determined by parameters in MagneticMultipoleP or ElectricMultipoleP such as Kn0, to deflect the beam in horizontal and vertical directions.

Under Construction…

Element parameter groups associated with this element kind are:

Marker Element#

A Marker element is a zero length element to mark a particular position. The main purpose of this element is to name a position in the beamline. Marker elements has a unit transport map. That is, a particle’s phase space coordinates are not altered with passage through the element

Element parameter groups associated with this element kind are:

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • FloorP: Floor position and orientation.

  • MetaP: Meta parameters.

  • ReferenceP: Output Parameters. Reference parameters.

The length of this element must be zero.

Marker elements can be used, for example, to designate beam position monitor locations. In such a case, the BodyShiftP parameter group can be used to misalign the BPM.

Mask Element#

A Mask element defines an aperture where the mask area can essentially have an arbitrary shape. It is a collimation element to remove unwanted particles.

Under Construction…

Element parameter groups associated with this element kind are:

Match Element#

A Match element is used to match the orbit, Twiss, and dispersion parameters between two locations.

Under Construction…

Element parameter groups associated with this element kind are:

  • ApertureP: Aperture parameters.

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • FloorP: Floor position and orientation.

  • MetaP: Meta parameters.

  • ReferenceP: Output Parameters. Reference parameters.

  • TrackingP: Tracking parameters.

The length of this element is considered to be zero so if length is specified, it must be zero.

Multipole Element#

A general multipole element. The fields are assumed to be uniform along the longitudinal direction, and may contain (magnetic or electric) multipole contributions of any order.

Element parameter groups associated with this element kind are:

Octupole Element#

An octupole is an element whose major field has a cubic field dependence with transverse offset. Both electric and magnetic fields can be defined and additional multipole contributions are allowed. In terms of functionality, an octupole is equivalent to a Multipole element.

Element parameter groups associated with this element kind are:

Example:

oct01w:
  kind: Octupole
  length: 0.4
  MagneticMultipoleP:
    Kn3: 1.0

Placeholder Element#

Placeholder element used for bookkeeping when constructing the expanded lattice. This element has zero length and does nothing. This element can be used as a base_item element for superpositions. Additionally, this element can be used, for example, to denote an invalid element in the internal structures defined by a program.

Placeholder elements present in a lattice file will, as a part of lattice expansion, be removed. That is, Placeholder elements will never be present in the final expanded lattice and tracking through a Placeholder will never be needed.

This element does not have any associated parameter groups.

For other purposes, for example, to mark reference points, Marker elements may be used.

Patch Element#

A Patch element is an element used to shift the reference orbit and time. A common application of this element is to orient two lines with respect to each other. For example, to orient an injection line with the ring it is injecting into.

Under Construction…

Element parameter groups associated with this element kind are:

  • ApertureP: Aperture parameters.

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • FloorP: Floor position and orientation.

  • MetaP: Meta parameters.

  • PatchP: Exit coordinates with respect to entrance coordinates.

  • ReferenceP: Output Parameters. Reference parameters.

  • TrackingP: Tracking parameters.

Important: By convention, the energy shift is applied after a particle reaches the exit face. This matters due to the dependence of the reference velocity on the the reference energy.

Quadrupole Element#

A Quadrupole is an element whose major field has a linear field dependence .with transverse offset. Both electric and magnetic fields can be defined and the field is not restricted to be linear. In terms of functionality, a quadrupole is equivalent to a Multipole element

Element parameter groups associated with this element kind are:

Example:

q01w:
  kind: Quadrupole
  length: 0.6
  MagneticMultipoleP:
    Kn1: 0.37

ReferenceChange Element#

A ReferenceChange element is used to adjust reference parameters at any location in a branch. These adjusted reference parameters will then be used to calculate the reference parameters for the downstream elements of the ReferenceChange element.

Element parameter groups associated with this element kind are:

RFCavity Element#

An RFCavity element represents an RF cavity that accelerates or decelerates, and focuses or defocuses, a charged particle beam longitudinally and transversely using RF fields.

Under Construction…

Element parameter groups associated with this element kind are:

Note: Multipole parameters represent DC fields. A common example is a DC solenoid field which helps focusing.

Sextupole Element#

A sextupole is an element whose major field has a quadratic field dependence with transverse offset. Both electric and magnetic fields can be defined and additional multipole contributions are allowed. In terms of functionality, a sextupole is equivalent to a Multipole element.

Element parameter groups associated with this element kind are:

Example:

s01w:
  kind: Sextupole
  length: 0.5
  MagneticMultipoleP:
    Kn2: 0.28

Solenoid Element#

A solenoid is an element whose magnetic field is dominated by a field whose direction is aligned with the magnetic axis. Additional magnetic (or electric) multipole contributions are allowed.

Element parameter groups associated with this element kind are:

Example:

sol01w:
  kind: Solenoid  
  length: 3.74
  SolenoidP:   
    Ksol: -0.15

Taylor Element#

A Taylor element is a Taylor map that maps the input orbital phase space and possibly spin coordinates of a particle at the entrance end of the element to the output orbital phase space and spin coordinates at the exit end of the element.

Under Construction…

Element parameter groups associated with this element kind are:

  • ApertureP: Aperture parameters.

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • FloorP: Floor position and orientation.

  • MetaP: Meta parameters.

  • ReferenceP: Output Parameters. Reference parameters.

  • TaylorP: Orbital and spin Taylor map.

  • TrackingP: Tracking parameters.

The length of this element is considered to be zero so if length is specified, it must be zero.

UnionEle Element#

The UnionEle element holds a set of overlapping elements.

Element parameter groups associated with this element kind are:

  • ApertureP: Aperture parameters.

  • BodyShiftP: Orientation of element with respect to its nominal position.

  • elements: A list of contained element kinds.

  • FloorP: Floor position and orientation.

  • MetaP: Meta parameters.

  • ReferenceP: Output Parameters. Reference parameters.

  • TrackingP: Tracking parameters.

For each element contained in the UnionEle, the nominal position of the contained element is such that the center of the contained element is at the center of the UnionEle with the body coordinates of the contained element aligned with the body coordinates of the UnionEle. Any contained element can be shifted from the nominal position by setting the contained element’s BodyShiftP parameters. The entire collection of elements can be oriented using the UnionEle’s BodyShiftP parameters.

Example:

MMM:
  kind: UnionEle
  length: 2.1
  BodyShiftP:           # The UnionEle itself can be oriented.
    ...
  elements:
    Sa:
      kind: Solenoid    # Contained elements can be named.
      length: 1.3
      BodyShiftP:       # Orient the Solenoid
        x_offset: 0.03
        ...
    Ra:
      kind: RFCavity
      BodyShiftP:       # Orient the RFCavity
        y_rot: 0.012
        ...

Note: UnionEle shares the feature of describing elements that overlap physically, together with the placement construct within a BeamLine and the superposition construct.

Wiggler Element#

A Wiggler element consists of a periodic array of alternating bending magnets. From a particle tracking perspective, it is equivalent to an undulator. Hereafter, the term “wiggler” will be used to denote either a wiggler or an undulator.

Under Construction…

Element parameter groups associated with this element kind are: