Lattice Element Parameters

The following discusses lattice element parameters in general. For details on the different parameter groups see here.

Parameter Groups

Lattice elements parameters are organized into parameter groups. All groups are organized as dictionaries (structures) and lists. At the top level, there are the groups with names like MagneticMultipoleP, ElectricMultipoleP, MetaP, AlignmentP, etc. By convention, group names use upper camel case and it is highly recommended that this convention be followed but it is not mandatory. Also, by convention, parameter groups end with a P. This is to distinguish between element kinds and parameter groups which might have similar names. For example, Fork is the name of an element kind and ForkP is the name of a parameter group which a Fork element will have.

For any given element, a given parameter group can only appear once. For example, the following is not allowed:

- q10w:
    kind: Quadrupole
    ApertureP: ...
    ApertureP: ...    # Second instance not allowed!

For details on the different parameter groups see here.

Element Parameters Not in any Element Group

There are element parameters that are common and do not naturally fit into any of the parameter groups. These parameters are not grouped. These element parameters are:

  field_master: NotSet  # [Boolean] See Below.
  is_on: true           # [Boolean] Turns on or off the fields in an element. When off, the element looks like a drift.
  kind: ""              # [enum] Kind of element (Quadrupole, etc.).
  length: 0             # [m] Length of element. For bends this is the arc length.
  name: ""              # [string] The name of element.
  s_position: 0         # [m] The longitudinal position of the element.

The setting of field_master matters when there is a change in reference energy during a simulation. In this case, if field_master = T, magnetic multipoles, RF, and Bend unnormalized fields will be held constant and normalized field strengths will be varied. And vice versa when field_master is F.

Example:

cleo:             # [string] user-defined name
  kind: Solenoid  # [string] element switch
  length: 3.74
  SolenoidP:
    Ksol: -0.15

Element Parameter Name Matching

For element parameters, the general syntax is

{beamline}>>{element}>{parameter-group}.{sub-group1}. ... .{sub-groupN}.{parameter}

where

{beamline}                      # Optional BeamLine or Branch name.
{element}                       # Optional lattice element name.
{parameter-group}               # Parameter group name.
{sub-group1}. ... .{sub-groupN} # Subgroups if they exist.
{parameter}                     # Parameter name.

Only {beamline} and {element} use PCRE2 syntax.

Example:

Qa.*>MagneticMultipoleP.Ks2L

This will match the Ks2L component of all elements whose name begins with Qa. Notice that since only {beamline} and {element} use PCRE2 syntax, the dot separating the parameter group and the parameter is unambiguous.

Naming and Inheriting Parameters

Parameters from one element may be inherited by another element wholesale as documented here. On a per parameter group basis, parameter groups may be inherited as follows.

Any group can be given a name and the values can be used in another group of the same type using import. For example:

- ap1:
    kind: ApertureP
    x_min: -0.03
    x_max:  0.04

The above defines an aperture with the name ap1.

- ap2:
    kind: ApertureP
    inherit: ap1
    y_min: -0.02
    y_max:  0.05

And the above defines a new aperture group which inherits from ap1.

Now we can use the aperture parameter group as follows:

- q0:
    kind: Quadrupole
    ApertureP:
      inherit: ap2

Naming a parameter group is only needed if the parameter group is defined outside of an element.

- q1:
    kind: Quadrupole
    ApertureP: 
      x_width: 0.03
      y_width: 0.02

And an element can inherit a parameter group from another element:

- q2:
    kind: Quadrupole
    ApertureP:
      inherit: q1.ApertureP

For an element to inherit all parameter groups from another element, just inherit the element itself:

- q3:
    kind: Quadrupole
    inherit: q2

User Settable (Input) and Dependent (Output) parameters.

Some parameters are set in the lattice file. These parameters are called “User settable” or “input”. Some parameters will be computed by the Translator during lattice expansion. These parameters are called “dependent” or “output” parameters. There is a third class of parameters that can be an input parameter if it is set in the lattice file or will be an output parameter if not set.

For example, the FloorP parameters can be set for the BeginningEle element which is the first element of any branch line. For most other elements, the FloorP parameters can be calculated starting at the BeginningEle and working forward computing the floor parameters element-by-element.