Parameter Groups

AlignmentParams

Describe the alignment of the element with respect to the nominal position. Rotations are applied in order: tilt, x_rot, y_rot.

Properties

• x_offset: Offset along x-axis [m]
• y_offset: Offset along y-axis [m]
• z_offset: Offset along z-axis [m]
• x_rot: Rotation around the x-axis [rad]
• y_rot: Rotation around the y-axis [rad]
• tilt: Rotation around the z-axis [rad]

ApertureParams

Describe a mechanical aperture.

Properties

• x1_limit: Left x-axis aperture edge [m]
• x2_limit: Right x-axis aperture edge [m]
• y1_limit: Lower y-axis aperture edge [m]
• y2_limit: Upper y-axis aperture edge [m]
• aperture_shape: Shape of the aperture, see ApertureShape
• aperture_at: Longitudinal aperture location(s), see ApertureAt
• aperture_shifts_with_body: true if the aperture position moves with element alignment, false otherwise. Default is true
• aperture_active: true if particles are collimated by aperture, false otherwise. Default is true

BMultipoleParams

Defines magnetic (B) multipoles for an element.

A given multipole can be set using any of the following:

• KnX: Order X normal strength in [1/m^X] (normalized, nonintegrated)
• KsX: Order X skew strength in [1/m^X] (normalized, nonintegrated)
• BnX: Order X normal strength in [T/m^X] (unnormalized, nonintegrated)
• BsX: Order X skew strength in [T/m^X] (unnormalized, nonintegrated)
• KnXL: Order X normal strength in [1/m^(X-1)] (normalized, integrated)
• KsXL: Order X skew strength in [1/m^(X-1)] (normalized, integrated)
• BnXL: Order X normal strength in [T/m^(X-1)] (unnormalized, integrated)
• BsXL: Order X skew strength in [T/m^(X-1)] (unnormalized, integrated)
• tiltX: Tilt to only order X multipole

The solenoidal multipole can be set using any of the above with X = sol and omitting the n/s, e.g. Ksol, Bsol, KsolL, BsolL.

ele = LineElement(Kn1=0.1, Ks1=0.2, L=0.4) # Order 1 is normalized, nonintegrated
ele.Kn1L = 0.3         # Order 1 independent variables are now normalized, integrated
ele.Ks1L == 0.2*0.4    # true
ele.Bn1 = 0.5          # Order 1 independent variables are now unnormalized, nonintegrated
ele.Bs1 == 0.2*0.5/0.3 # true, set so that (Bs1/Bn1)_new = (Ks1L/Kn1L)_old

BeamlineParams

Defines information for LineElements that are in a Beamline.

Properties

• beamline: Beamline that this LineElement is in
• beamline_index: Index of the line array of the Beamline that this element is at
• s: Longitudinal position from the start of the Beamline at the entrance of the element [m]
• s_downstream: Longitudinal position from the start of the Beamline at the exit of the element [m]
• line: A read-only array of LineElements in the beamline, in order
• branch: Branch that the beamline is placed in, if any
• branch_index: Index of the beamline in the Branch, if in a Branch

BendParams

Defines a curvature in the reference coordinate system throught the element, as well as the edge angles of the element at the entrance and exit of the element. Does not specify any magnetic field.

Properties

• g_ref: Coordinate system curvature [1 / m]
• tilt_ref: Tilt angle applied before the curvature, and undone after [rad]
• e1: Edge angle of the entrance of the element w.r.t. the entering coordinate system [rad]
• e2: Edge angle of the exit of the element w.r.t. the exit coordinate system [rad]
• edge1_int: Pole face field integral at the entrance [T * m]
• edge2_int: Pole face field integral at the exit [T * m]

FourPotentialParams

TODO

Properties

• four_potential: TODO
• four_potential_params: TODO
• four_potential_normalized: TODO

Examples

TODO

InitialBeamlineParams

Defines the reference species and energy of the beamline. These parameters may be "set" in the first element of the beamline or at the Beamline level, and retrieved at any element in the beamline. If the reference species or energy is not set, then it will inherit that quantity from an upstream beamline if in a Branch.

Properties

• species_ref: Reference species of the beamline
• E_ref: Total reference energy [eV]
• pc_ref: Reference momentum [eV/c]
• p_over_q_ref: A signed reference magnetic rigidity [T * m]
• dE_ref: Change in total reference energy w.r.t. the directly-upstream beamline [eV]
• dpc_ref: Change in reference momentum w.r.t. the directly-upstream beamline [eV/c]
• dp_over_q_ref: Change in signed reference magnetic rigidty w.r.t. the directly-upstream beamline [T * m]

MapParams

Defines any arbitrary function to transport particle coordinates' and optionally spin quaternions. This could be a matrix, a neural network, a phase trombone, etc.

The input for the transport_map must be (v, q, p=nothing), where v is a tuple of the input phase space coordinates (x, px, y, py, z, pz) and q is nothing is there is no spin tracking, else q is a tuple of the input quaternion (q0, q1, q2, q3). p may be a tuple of parameters that can be used inside of the transport_map. This might be neural network weights, for example, or perhaps phase evolutions for a phase trombone.

For GPU compatibility, it is necessary that your function transport_map is GPU compatible: there should be no type instabilities. You should also try to make your transport_map be branchless, so both the CPU and GPU can vectorize it.

transport_map_params should contain the tuple that is passed into p at the time of tracking.

Properties:

• transport_map: Arbitrary function that transports particles' coordinates v, and optionally spin quaternions q. Must have the signature <your map name>(v, q, p=nothing) and returns the output as a tuple (v, q)
• transport_map_params: Parameters of the transport map that will be inputted as the p variable in transport_map

Example

using StaticArrays
random_matrix = @SMatrix rand(6,6) # use StaticArrays for GPU compatibility

function matrix(v, q::Nothing, p) # `q::Nothing` -> no spin tracking
  # Vectorizable matrix multiplication by `p`:
  vx  = sum(p[1,:] .* v)
  vpx = sum(p[2,:] .* v)
  vy  = sum(p[3,:] .* v)
  vpy = sum(p[4,:] .* v)
  vz  = sum(p[5,:] .* v)
  vpz = sum(p[6,:] .* v)
  return ((vx, vpx, vy, vpy, vz, vpz), q)
end

m = LineElement(transport_map=matrix, transport_map_params=random_matrix)

MetaParams

Defines extra String properties that may be useful for pattern matching or storing extra information about a given element.

Properties

• alias: Alternate name for the element as a string
• label: A label string
• description: A descriptive string

PatchParams

Defines properties for patches, which change the reference coordinate system. Rotations are applied in order: dz_rot, dx_rot, dy_rot.

Properties

• dt: Reference time shift [s]
• dx: New coordinate system offset in the x-direction [m]
• dy: New coordinate system offset in the y-direction [m]
• dz: New coordinate system offset in the z-direction [m]
• dx_rot: Rotation of coordinate system around the initial x-axis [rad]
• dy_rot: Rotation of coordinate system around the initial y-axis [rad]
• dz_rot: Rotation of coordinate system around the initial z-axis [rad]

RFParams

Defines parameters generally associated with radiofrequency (RF) cavities. The frequency of the oscillating electromagnetic field may be optionally specified using the property rf_frequency or harmon; whichever of these is set last will be the independent variable.

Properties

• rf_frequency: Frequency of the oscillating electromagnetic field [Hz]
• harmon: Harmonic number of the oscillating electromagnetic field w.r.t. the length of the entire containing Beamline [1]
• phi0: Phase offset of the oscillating field w.r.t. zero_phase [rad]
• zero_phase: A PhaseRef that specifies what phi0 should mean, see PhaseRef
• traveling_wave: true if traveling wave, false if standing wave
• is_crabcavity: true if this is a crab cavity, false otherwise

UniversalParams

Describes the kind, name, length, and tracking method for a LineElement.

Properties

• kind: String specifing the "kind", of an element, e.g. "Quadrupole"
• name: The name of an element as a string
• L: Length of the element [m]
• tracking_method: Tracking method for the element, defaults to SciBmadStandard()