Lattice Elements

Lattice Elements#

The following discusses lattice elements in general. For details on the different element kinds see here.

Lattice Elements#

The basic building block used to describe an accelerator is the lattice element. Typically, a lattice element is something physical like a bending magnet or an electrostatic quadrupole, or a diffracting crystal. A lattice element may define a region in space distinguished by the presence of (possibly time-varying) electromagnetic fields, materials, apertures and other possible engineered structures. However, lattice elements are not restricted to being something physical and may, for example, just mark a particular point in space (EG: Marker elements), or may designate where beamlines intersect (Fork elements). By convention, element names in PALS will be upper camel case. The different kinds of elements are discussed in the Element Kinds section.

Lattice Element Definition#

Lattice element definition syntax is:

<element-name>:
  kind: <kind-of-element>
  ... other parameters ...

where <element-name> is the name of the element, and <kind-of-element> is the element kind. Example:

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

Lattice element definitions may only be placed as a child node of the facility node or “in place” in a line within a BeamLine. Example:

PALS:
  facility:
    - Q1:                 # An element defined under the facility node.
        kind: Quadrupole
        ...

    - myline:
        kind: BeamLine
        line:
          - thingT:     # An element defined within a line.
             kind: Marker
          ...

Element parameters from one element may be inherited by another using an inherit node. Example:

S2: 
  kind: Sextupole
  length: 0.45
  MagneticMultipoleP:
    Kn2L: 0.56
    tilt2: 0.12

S3:
  inherit: S2        # Inherits parameters from S2
  length: 0.55       # And any inherited parameter may be modified.

Inheritance may also be done on the parameter group level. See here.

To avoid confusion, lattice elements may not be redefined. That is, two lattice element definitions that use the same element name is not allowed.

Element Name Matching#

Lattice element name matching is the process of finding the set of lattice elements that are matched to a given string. Name matching is important in a number of instances including lattice expansion where there are Fork elements and for evaluating mathematical expressions.

The simplist form of name matching is if the string matches the name field of an element or elements. For example, the string "Q1" will match to all elements named Q1.

Element matches may be restricted to a given element kind using the notation

{kind}::{name}

where {kind} is the element kind and {name} is the element name. Example:

Marker::bpm.

This will match to all Marker elements whose name is four characters starting with bpm (since a dot matches to any single character, see below).

The N^th element with a given name can be matched to by appending the character "#" followed by an integer N. For example, "Quadrupole::Q1#3" will match to the third element that matches "Quadrupole::Q1". The N^th instance selection is always applied last. Thus with this example, the element kind selector :: is applied first to get a list of all quadrupole elements named Q1 and then the #3 selection is used to get the third instance.

In the discussion below, all of the above constructs will be called an “element name”.

The names of an element may be “qualified” by prepending a branch or BeamLine name (henceforth just referred to as a branch name) to the string, using the string ">>" as a separator. For example, "B1>>Sextupole::Saf" would match to all Sextupole elements in a branch or BeamLine named "B1" whose name was "Saf". This includes sublines of BeamLines. Thus if B1 is a BeamLine that contains a subline B2 that in turn contains a Sextupole element named Saf, the string "B1>>Sextupole::Saf" will match to this element.

Lattice elements can also be referred to by the index in which they appear in a branch with the first element having index one, etc. For example, "B1>>7" matches the seventh element in branch B1.

Branches do not get an index since the PALS standard does not mandate that the branches of a lattice be stored in an array (it could, for example, be a linked list).

If there are multiple Lattice constructs, the element name may be qualified using the lattice name with ">>>" as a separator. There are several permutations where >> and >>> are used:

{lattice-name}>>>{branch-name}>>{element-name}
{lattice-name}>>>{element-name}
{branch-name}>>{element-name}

Regular expressions can be used. Regular expressions must conform to the PCRE2 standard. Regex matching is applied to the lattice name, branch name, and element name separately and a match to the string requires all the individual names to match. When applying regex to a lattice name, any prefix (anything before and including a "::") and any suffix (anything after and including a "#" character) is not included in the regex match. For example, "B.4>>Quadrupole::Qaf.*" would match to all Quadrupole elements in branches which have three characters beginning in “B” and ending in “4” with the element name beginning with “Qaf”. And "B.4>>Quadrupole::Qaf.*#2" would match to the second element matched to.

Elements can be matched using a range construct which has the form

{ele1}:{ele2}

where {ele1} marks the beginning of the range and {ele2} marks the end of the range. Example:

Q1:Q2

In this example, the range matches all elements from Q1 to Q2 inclusive of Q1 and Q2. If {ele2} comes before {ele1} the range “wraps around” the branch or beamline. For example, if Q2 comes before Q1 in the above example, the range matches all elements from Q1 to the end of the line plus all elements from the beginning of the line to Q2.

Commas , can be used to form the union of element sets. The syntax is

{element-set1}, {element-set2}, ... , {element-setN}

where {element-set1}, … {element-setN} are element sets. Example:

A, B, Q.*

This will match to all elements named A, B, and all elements whose name begins with Q.

Ampersands & can be used to form the intersection of element sets. The syntax is

{element-set1} & {element-set2} & ... & {element-setN}

where {element-set1}, … `{element-setN} are element sets. Example:

Marker::.* & Q1:Q2

This will match to all Marker elements that are in the range from Q1 to Q2.

Order of precedence:

>>>     # Highest
>>
::      
#
:
,
&      # Lowest

Lattice Elements

Contents

Lattice Elements#