Full API

Documentation for Beamlines.

Beamlines.AlignmentParams — Type

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]

source

Beamlines.ApertureParams — Type

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

source

Beamlines.BMultipoleParams — Type

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.

Note

The last set for a given multipole defines if both the normal and skew strengths for a given multipole order are normalized and integrated. E.g.

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

source

Beamlines.Beamline — Type

Beamline

Structure containing a vector of LineElements in an ordered sequence. The reference species (specified as species_ref and reference energy (specified as one of E_ref, pc_ref, p_over_q_ref, dE_ref, dpc_ref, or dp_over_q_ref) is uniform over the entire beamline. The most-recently specified of these reference energy quantites will be stored as the independent variable, in the first LineElement of the Beamline.

Properties

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

source

Beamlines.Beamline — Method

Beamline(line; kwargs...)

Constructs a Beamline out of the LineElements in the vector line. The LineElements in the Beamline will be automatically constructed as children of those LineElements in line, inheriting all of their properties.

The reference energy of the beamline may be optionally specified using one of the keyword arguments: E_ref, pc_ref, p_over_q_ref, dE_ref, dpc_ref, or dp_over_q_ref. Whichever of these is specified will be the independent variable. The species of the beamline may be optionally specified using the species_ref keyword argument. Specifying either of these keyword arguments will permanently override both the reference species and energy defined in the first LineElement – see the warning below.

Examples

qf = Quadrupole(Kn1=0.36, L=0.5)
d = Drift(L=1)
qd = Quadrupole(Kn1=-0.36, L=0.5)

fodo = Beamline([qf, d, qd, d], species_ref=Species("electron"), E_ref=18e9)

Alternatively, one can specify the reference species/energy in the first element:

qf = Quadrupole(Kn1=0.36, L=0.5, species_ref=Species("electron"), E_ref=18e9)
d = Drift(L=1)
qd = Quadrupole(Kn1=-0.36, L=0.5)

fodo = Beamline([qf, d, qd, d])

Keyword arguments

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 in units [eV]
dpc_ref: Change in reference momentum w.r.t. the directly-upstream beamline in units [eV/c]
dp_over_q_ref: Change in signed reference magnetic rigidty w.r.t. the directly upstream beamline [T * m]

Warning

Keyword arguments specified to the Beamline constructor will permanently override any corresponding properties specified in the first LineElement of the beamline. E.g.,

beg = Marker(species_ref=Species("electron"), E_ref=18e9)

a = Beamline([beg])
b = Beamline([beg], species_ref=Species("proton"), E_ref=1e9)

a.E_ref == beg.E_ref == 18e9 # true
b.E_ref == 1e9               # true
b.E_ref != beg.E_ref         # true

# If `beg` is reset:
beg.species_ref = Species("positron")

# `a` will still inherit it, but `b` will not:
a.species_ref == beg.species_ref   # true
b.species_ref == Species("proton") # true
b.species_ref != beg.species_ref   # true

source

Beamlines.BeamlineParams — Type

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

source

Beamlines.BendParams — Type

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]

source

Beamlines.Branch — Type

Branch

Structure containing a vector of Beamlines, where currently each follows in-order, one after the other.

Properties

beamlines: Vector of the beamlines in the Branch

source

Beamlines.Branch — Method

Branch(beamlines)

Constructs a Branch given the vector of beamlines beamlines.

Example

ele = LineElement()
bl1 = Beamline([ele], E_ref=2e9, species_ref=Species("electron"))
bl2 = Beamline([ele], dE_ref=1e9)

branch = Branch([bl1, bl2])

Branch(elements; kwargs...)

Constructs a Branch given the vector of LineElements elements. This will automatically partition the given vector into separate Beamlines, which each have a uniform reference species and reference energy.

Example

beginning = Marker(E_ref=10e9, species_ref=Species("electron"))
rf0 = RFCavity(dE_ref=1e9)
next = LineElement()

branch = Branch([beginning, rf0, next]) # Partitioned into 2 `Beamline`s

source

Beamlines.Controller — Type

Controller

An eagerly-evaluated controller of LineElement properties or other Controller properties. Similar to classical Bmad's "Overlay" or "Group".

Also see set!.

Tip

In SciBmad, it is generally preferred to use the lazily-evaluated DefExpr for deferred expressions.

Examples

qf = Quadrupole(Kn1=0.36, L=0.5)
qd = Quadrupole(Kn1=-0.36, L=0.5)

c1 = Controller(
  (qf, :Kn1) => (ele; x) ->  x,
  (qd, :Kn1) => (ele; x) -> -x;
  vars = (; x = 0.0,)
)

# Now we can vary both simultaneously:
c1.x = 60.
qf.Kn1 == -qd.Kn1 == 60 # true

# Controllers also include the element itself. This can 
# be useful if the current elements' values should be 
# used in the function:
c2 = Controller(
  (qf, :Kn1) => (ele; dKn1) ->  ele.Kn1 + dKn1,
  (qd, :Kn1) => (ele; dKn1) ->  ele.Kn1 - dKn1;
  vars = (; dKn1 = 0.0,)
) 

c2.dKn1 = 20
qf.Kn1 == -qd.Kn1 == 80 # true

# Controllers can also be used to control other controllers:
c3 = Controller(
  (c1, :x) => (ctrl; dx) -> ctrl.x + dx;
  vars = (; dx = 0.0,)
)

source

Beamlines.DefExpr — Type

DefExpr{T}

A lazily-evaluated deferred expression returning type T. Deferred expressions are lambda functions that "close" over a variable in the current scope. They can be used to specify inter-dependent parameters in an accelerator and guarantee that no parameter ever becomes "stale".

Examples

julia> a = 0.36;

julia> qf = Quadrupole(Kn1L=DefExpr(()->a)); # captures variable a

julia> qf.Kn1L
0.36

julia> a = 0.7
0.7

julia> qf.Kn1L
0.7

Slightly better performance may be achieved by explicitly typing the captured variable:

julia> b::Float64 = 0.2;

julia> qf = Quadrupole(Kn1L=DefExpr(()->b)); # captures variable b with known type

julia> qf.Kn1L
0.2

julia> b = 0.4
0.4

julia> qf.Kn1L
0.4

Deferred expressions can be treated and operated with as regular numbers, even outside the context of Beamlines, and can be evaluated by calling it like a function with no arguments (with ()):

julia> c = 64;

julia> cd = DefExpr(()->sin(c));

julia> c = pi;

julia> cd = DefExpr(()->sin(c));

julia> cd()
0.0

julia> c = pi/2;

julia> cd()
1.0

julia> dd = cd + 5;

julia> dd()
6.0

source

Beamlines.FourPotentialParams — Type

FourPotentialParams

TODO

Properties

four_potential: TODO
four_potential_params: TODO
four_potential_normalized: TODO

Examples

TODO

source

Beamlines.InheritParams — Type

InheritParams

Stores a parent LineElement through which any parameter groups NOT present in the "child" element containing the InheritParams would inherit. E.g., if the child element has its own BeamlineParams, then any property from the BeamlineParams parameter group would be read/ write to the child's BeamlineParams.

Properties:

parent: Parent LineElement to inherit parameter groups from for both reading and writing.

source

Beamlines.InitialBeamlineParams — Type

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]

source

Beamlines.LineElement — Type

LineElement

The basic building block which makes up a Beamline. May be something physical like a quadrupole magnet, or something non-physical like a point in the accelerator you want to mark. A LineElement may define a region in space distinguished by the presence of (possibly time-varying) electromagnetic fields, materials, apertures and other possible properties.

LineElement properties are split into "parameter groups" for convenient organization:


  AlignmentParams         ApertureParams               BMultipoleParams
   x_offset                x1_limit                     KnX
   y_offset                x2_limit                     KsX
   z_offset                y1_limit                     BnX
   x_rot                   y2_limit                     BsX
   y_rot                   aperture_shape               KnXL
   tilt                    aperture_at                  KsXL
                           aperture_shifts_with_body    BnXL
                           aperture_active              BsXL
                                                        tiltX

  BeamlineParams          BendParams                   FourPotentialParams
   beamline                g_ref                        four_potential
   beamline_index          tilt_ref                     four_potential_params
   s                       e1                           four_potential_normalized
   s_downstream            e2
   line                    edge1_int
   branch                  edge2_int
   branch_index

  InitialBeamlineParams   MapParams                    MetaParams
   species_ref             transport_map                alias
   E_ref                   transport_map_params         label
   pc_ref                                               description
   p_over_q_ref
   dE_ref
   dpc_ref
   dp_over_q_ref

  PatchParams             RFParams                     UniversalParams
   dt                      rf_frequency                 kind
   dx                      harmon                       name
   dy                      phi0                         L
   dz                      zero_phase                   tracking_method
   dx_rot                  traveling_wave
   dy_rot                  is_crabcavity
   dz_rot

To set a property, use the natural syntax:

ele = LineElement()
ele.L = 1   # Length 
ele.Kn1 = 2 # Normal quadrupole strength
ele.rf_frequency = 1e6

For detailed descriptions of properties in a given parameter group, see the documentation for that parameter group.

source

Beamlines.MapParams — Type

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)

source

Beamlines.MetaParams — Type

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

source

Beamlines.PatchParams — Type

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]

source

Beamlines.RFParams — Type

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

source

Beamlines.SciBmadStandard — Type

SciBmadStandard

Default tracking method that uses exact transport maps when solvable, else uses the symplectic integrator Yoshida(order=4, num_steps=1) which chooses an appropriate split for each element.

Properties

radiation_damping_on: true if the deterministic effect of synchrotron radiation is included, false otherwise. Defaults to false
radiation_fluctuations_on: true if the stochastic radiation kicks are included, false otherwise. Defaults to false
ibs_damping_on: true if the deterministic effect of intrabeam scattering (IBS) is included, false otherwise. Defaults to false.
ibs_fluctuations_on: true if the stochastic kicks of intrabeam scattering (IBS) is included, false otherwise. Defaults to false.

source

Beamlines.UniversalParams — Type

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()

source

Base.empty! — Method

empty!(::Beamline)

Removes BeamlineParams from all elements in the Beamline and empties the array of LineElements.

WARNING: this is irreversible.

source

Beamlines.CrabCavity — Method

CrabCavity(; kwargs...) = LineElement(; kind="CrabCavity", is_crabcavity = true, kwargs...)