at.lattice.elements.magnet_elements#

Element classes for magnets.

Expansion of the magnetic field in AT#

The multipole magnets are expressed according to the following expression for the multipole expansion of the magnetic field:

\[\frac{B_y + iB_x}{B\rho} = \sum_{n=0}^{MaxOrder}(b_n+ ia_n)(x+iy)^n\]

where \(n\) is the multipole order (0 for dipole, 1 for quadrupole…).

The \(b_n\) coefficients describe the “normal” magnetic field (mid-plane symmetry) and are given in the PolynomB sequence.

The \(a_n\) coefficients describe the “skew” magnetic field and are given in the PolynomA sequence.

Note

This field expansion differs from the one used in MAD or other programs. See PALS for a definition of the MAD/PALS field expansion. Practically, we have:

\[\begin{split}\begin{eqnarray} Kn_n &= n!\:b_n \\ Ks_n &= n!\:a_n \end{eqnarray}\end{split}\]

Classes

`Bend`	alias of `Dipole`
`Corrector`(family_name, length, kick_angle, ...)	Corrector element.
`Dipole`(family_name, length[, bending_angle, k])	Dipole element.
`Multipole`(family_name, length, poly_a, ...)	Multipole element.
`Octupole`(family_name, length, poly_a, ...)	Octupole element, with no changes from multipole at present.
`Quadrupole`(family_name, length[, k])	Quadrupole element.
`Sextupole`(family_name, length[, h])	Sextupole element.
`ThinMultipole`(family_name, poly_a, poly_b, ...)	Thin multipole element.
`Wiggler`(family_name, length, wiggle_period, ...)	Wiggler element.

Bend#: alias of Dipole

class Corrector(family_name, length, kick_angle, **kwargs)[source]#

Bases: LongElement

Corrector element.

Parameters:

family_name (str) – Name of the element
length (float) – Element length [m]
KickAngle – Correction deviation angles (H, V).

Keyword Arguments:

FieldScaling – Scaling factor applied to the magnetic field (KickAngle)

Default PassMethod: CorrectorPass

KickAngle: ndarray#: (H, V) deviation angles

property Kn0L: float#: Opposite of the horizontal momentum kick - \(\Delta p_x = -\mathrm{Kn0L}\).

property Ks0L: float#: Vertical momentum kick - \(\Delta p_y = \mathrm{Ks0L}\).

class Dipole(family_name, length, bending_angle=0.0, k=0.0, **kwargs)[source]#

Bases: Radiative, Multipole

Dipole element.

Parameters:

family_name (str) – Name of the element
length (float) – Element length [m]
bending_angle (float) – Bending angle [rd]
k (float) – Focusing strength [m^-2].

Keyword Arguments:

EntranceAngle=0.0 – entrance angle
ExitAngle=0.0 – exit angle
PolynomB – normal multipoles
PolynomA – skew multipoles
MaxOrder=0 – Number of desired multipoles
NumIntSteps=10 – Number of integration steps
FullGap – Magnet full gap
FringeInt1 – Extension of the entrance fringe field
FringeInt2 – Extension of the exit fringe field
FringeBendEntrance –
1: legacy version Brown First Order (default)

2: SOLEIL close to second order of Brown

3: THOMX
FringeBendExit – See FringeBendEntrance
FringeQuadEntrance –
0: no fringe field effect (default)

1: Lee-Whiting’s thin lens limit formula

2: elegant-like
FringeQuadExit – See FringeQuadEntrance
fringeIntM0 – Integrals for FringeQuad method 2
fringeIntP0
KickAngle – Correction deviation angles (H, V)
FieldScaling – Scaling factor applied to the magnetic field

Available PassMethods: BndMPoleSymplectic4Pass, BendLinearPass, ExactSectorBendPass, ExactRectangularBendPass, ExactRectBendPass, BndStrMPoleSymplectic4Pass

Default PassMethod: BndMPoleSymplectic4Pass

is_compatible(other)[source]#

Checks if another Element can be merged

items()[source]#

Iterates through the data members

merge(other)[source]#

Merge another element

rbendtune()#

Set X0ref and RefDZ for rectangular bending magnets

This method must be called after creating a rectangular bending magnet or after setting its PolynomA/B attributes. It will set the correct X0ref and RefDZ attributes to get a zero closed orbit for the reference particle.

The method will do nothing on dipoles with a non-rectangular passmethod.

Example

>>> # Identify the rectangular bends
>>> rbends = ring.get_bool_index(...)
>>> # Set their correct attributes
>>> for dip in ring.select(rbends):
...     dip.rbendtune()

DefaultOrder = 0#

class Multipole(family_name, length, poly_a, poly_b, **kwargs)[source]#

Bases: _Radiative, LongElement, ThinMultipole

Multipole element.

Parameters:

family_name (str) – Name of the element
length (float) – Element length [m]
poly_a – Array of skew multipole components
poly_b – Array of normal multipole components.

Keyword Arguments:

MaxOrder – Number of desired multipoles. Default: highest index of non-zero polynomial coefficients
NumIntSteps – Number of integration steps (default: 10)
KickAngle – Correction deviation angles (H, V)
FieldScaling – Scaling factor applied to the magnetic field (PolynomA and PolynomB)

Default PassMethod: StrMPoleSymplectic4Pass

is_compatible(other)[source]#

Checks if another Element can be merged

property IntegratedPolynomA: ndarray#: Integrated skew strengths.

property IntegratedPolynomB: ndarray#: Integrated normal strengths.

property Kn0: float#: Normal dipolar strength [m^-1].

property Kn1: float#: Normal quadrupolar strength [m^-2].

property Kn2: float#

Normal sextupolar m^-3].

The AT field expansion differs from the MAD expansion by a factor n!. See here for the definition of the AT field expansion and PALS for the MAD/PALS field expansion.

property Kn3: float#

Normal octupolar strength [m^-4].

The AT field expansion differs from the MAD expansion by a factor n!. See here for the definition of the AT field expansion and PALS for the MAD/PALS field expansion.

property Ks0: float#: Skew dipolar strength [m^-1].

property Ks1: float#: Skew quadrupolar strength [m^-2].

property Ks2: float#

Skew sextupolar m^-3].

The AT field expansion differs from the MAD expansion by a factor n!. See here for the definition of the AT field expansion and PALS for the MAD/PALS field expansion.

property Ks3: float#

Skew octupolar strength m^-4].

The AT field expansion differs from the MAD expansion by a factor n!. See here for the definition of the AT field expansion and PALS for the MAD/PALS field expansion.

MaxOrder: int#: Highest multipole order

NumIntSteps: int#: Number of integration slices

PolynomA: ndarray#: Skew strengths

PolynomB: ndarray#: Normal strengths

property Strength: float#: Strength of the main field component.

class Octupole(family_name, length, poly_a, poly_b, **kwargs)[source]#

Bases: Multipole

Octupole element, with no changes from multipole at present.

Parameters:

family_name (str) – Name of the element
length (float) – Element length [m]
poly_a – Array of skew multipole components
poly_b – Array of normal multipole components.

Keyword Arguments:

MaxOrder – Number of desired multipoles. Default: highest index of non-zero polynomial coefficients
NumIntSteps – Number of integration steps (default: 10)
KickAngle – Correction deviation angles (H, V)
FieldScaling – Scaling factor applied to the magnetic field (PolynomA and PolynomB)

Default PassMethod: StrMPoleSymplectic4Pass

DefaultOrder = 3#

class Quadrupole(family_name, length, k=0.0, **kwargs)[source]#

Bases: Radiative, Multipole

Quadrupole element.

Parameters:

family_name (str) – Name of the element
length (float) – Element length [m]
k (float) – Focusing strength [m^-2]

Keyword Arguments:

PolynomB – normal multipoles
PolynomA – skew multipoles
MaxOrder=1 – Number of desired multipoles
NumIntSteps=10 – Number of integration steps
FringeQuadEntrance –
0: no fringe field effect (default)

1: Lee-Whiting’s thin lens limit formula

2: elegant-like
FringeQuadExit – See FringeQuadEntrance
fringeIntM0 – Integrals for FringeQuad method 2
fringeIntP0
KickAngle – Correction deviation angles (H, V)
FieldScaling – Scaling factor applied to the magnetic field (PolynomA and PolynomB)

Default PassMethod: StrMPoleSymplectic4Pass

items()[source]#

Iterates through the data members

DefaultOrder = 1#

class Sextupole(family_name, length, h=0.0, **kwargs)[source]#

Bases: Multipole

Sextupole element.

Parameters:

family_name (str) – Name of the element
length (float) – Element length [m]
h (float) – Sextupolar strength [m^-3].

Keyword Arguments:

PolynomB – normal multipoles
PolynomA – skew multipoles
MaxOrder – Number of desired multipoles
NumIntSteps=10 – Number of integration steps
KickAngle – Correction deviation angles (H, V)
FieldScaling – Scaling factor applied to the magnetic field (PolynomA and PolynomB)

Default PassMethod: StrMPoleSymplectic4Pass

DefaultOrder = 2#

class ThinMultipole(family_name, poly_a, poly_b, **kwargs)[source]#

Bases: Element

Thin multipole element.

Parameters:

family_name (str) – Name of the element
poly_a – Array of integrated skew multipole components
poly_b – Array of integrated normal multipole components.

Keyword Arguments:

MaxOrder – Number of desired multipoles. Default: highest index of non-zero polynomial coefficients
FieldScaling – Scaling factor applied to the magnetic field (PolynomA and PolynomB)

Default PassMethod: ThinMPolePass

property H: float#: Sextupolar strength [m^-3].

property IntegratedPolynomA: ndarray#: Integrated skew strengths.

property IntegratedPolynomB: ndarray#: Integrated normal strengths.

property IntegratedStrength: float#: Integrated strength of the main field component.

property K: float#: Focusing strength [m^-2].

property Kn0L: float#

Integrated normal dipolar strength.

Kn0L is the opposite of the horizontal momentum kick: \(\Delta p_x = -\mathrm{Kn0L}\)

property Kn1L: float#: Integrated normal quadrupolar strength [m^-1].

property Kn2L: float#

Integrated normal sextupolar strength [m^-2].

The AT field expansion differs from the MAD expansion by a factor n!. See here for the definition of the AT field expansion and PALS for the MAD/PALS field expansion.

property Kn3L: float#

Integrated normal octupolar strength [m^-3].

The AT field expansion differs from the MAD expansion by a factor n!. See here for the definition of the AT field expansion and PALS for the MAD/PALS field expansion.

property Ks0L: float#

Integrated skew dipolar strength.

Ks0L is the vertical momentum kick: \(\Delta p_y = \mathrm{Ks0L}\)

property Ks1L: float#: Integrated skew quadrupolar strength [m^-1].

property Ks2L: float#

Integrated skew sextupolar strength [m^-2].

The AT field expansion differs from the MAD expansion by a factor n!. See here for the definition of the AT field expansion and PALS for the MAD/PALS field expansion.

property Ks3L: float#

Integrated skew octupolar strength [m^-3].

The AT field expansion differs from the MAD expansion by a factor n!. See here for the definition of the AT field expansion and PALS for the MAD/PALS field expansion.

MaxOrder: int#: Highest multipole order

PolynomA: ndarray#: Integrated skew strengths

PolynomB: ndarray#: Integrated normal strengths

class Wiggler(family_name, length, wiggle_period, b_max, energy=0.0, *, Nstep=5, Nmeth=4, By=(1, 1, 0, 1, 1, 0), Bx=(), **kwargs)[source]#

Bases: Radiative, LongElement

Wiggler element.

See atwiggler.m

Parameters:

length (float) – total length of the wiggler
wiggle_period (float) – length must be a multiple of this
b_max (float) – peak wiggler field [Tesla]
energy (float) – kept for backwards compatibility but always ignored
Nstep (int | None) – number of integration steps.
Nmeth (int | None) – symplectic integration order: 2 or 4
Bx – harmonics for horizontal wiggler: (6, nHharm) array-like object
By – harmonics for vertical wiggler (6, nHharm) array-like object.

Default PassMethod: GWigSymplecticPass

divide(frac)[source]#

split the element in len(frac) pieces whose length is frac[i]*self.Length

Parameters:: frac – length of each slice expressed as a fraction of the initial length. sum(frac) may differ from 1.
Returns:: elem_list – a list of elements equivalent to the original.

Example

>>> Drift("dr", 0.5).divide([0.2, 0.6, 0.2])
[Drift('dr', 0.1), Drift('dr', 0.3), Drift('dr', 0.1)]