at.lattice.elements#

Module to define common elements used in AT.

Each element has a default PassMethod attribute for which it should have the appropriate attributes. If a different PassMethod is set, it is the caller’s responsibility to ensure that the appropriate attributes are present.

Functions

build_class_map()

get_class_map()

Classes

Aperture(family_name, limits, **kwargs)

Aperture element

BeamMoments(family_name, **kwargs)

Element to compute bunches mean and std

Bend

alias of Dipole

Collective()

Mixin class for elements representing collective effects

Collimator(family_name, length, limits, **kwargs)

Collimator element

Corrector(family_name, length, kick_angle, ...)

Corrector element

Dipole(family_name, length[, bending_angle, k])

Dipole element

Drift(family_name, length, **kwargs)

Drift space element

Element(family_name, **kwargs)

Base class for AT elements

LongElement(family_name, length, *args, **kwargs)

Base class for long elements

LongtMotion()

Abstract Base class for all Element classes whose instances may modify the particle momentum

M66(family_name[, m66])

Linear (6, 6) transfer matrix

Marker(family_name, **kwargs)

Marker element

Monitor(family_name, **kwargs)

Monitor 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(FamName, Length[, Strength])

Quadrupole element

QuantumDiffusion(family_name, lmatp, **kwargs)

Quantum diffusion element

RFCavity(family_name, length, voltage, ...)

RF cavity element

Radiative()

Mixin class for default radiating elements (Dipole, Quadrupole, Wiggler)

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
class Aperture(family_name, limits, **kwargs)[source]#

Bases: Element

Aperture element

Parameters:

  • family_name – Name of the element

  • limits – (4,) array of physical aperture: [xmin, xmax, zmin, zmax] [m]

Default PassMethod: AperturePass

class BeamMoments(family_name, **kwargs)[source]#

Bases: Element

Element to compute bunches mean and std

Parameters:

family_name (str) – Name of the element

All keywords will be set as attributes of the element

set_buffers(nturns, nbunch)[source]#
property means#
property stds#
Bend#

alias of Dipole

class Collective[source]#

Bases: _DictLongtMotion

Mixin class for elements representing collective effects

Derived classes will automatically set the is_collective property when the element is active.

The class must have a default_pass class attribute, a dictionary such that:

  • default_pass[False] is the PassMethod when collective effects are turned OFF,

  • default_pass[True] is the default PassMethod when collective effects are turned ON.

The Collective class must be set as the first base class.

Example

>>> class WakeElement(Collective, Element):
...
...     default_pass = {False: 'IdentityPass', True: 'WakeFieldPass'}

Defines a class where the is_collective property is handled

abstract clear_history()[source]#
class Collimator(family_name, length, limits, **kwargs)[source]#

Bases: Drift

Collimator element

Parameters:

  • family_name (str) – Name of the element

  • length (float) – Element length [m]

  • limits – (4,) array of physical aperture: [xmin, xmax, zmin, zmax] [m]

Default PassMethod: DriftPass

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)

Default PassMethod: CorrectorPass

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 (Optional[float]) – Bending angle [rd]

  • poly_a – Array of normal multipole components

  • poly_b – Array of skew multipole components

  • k=0 – Field index

Keyword Arguments:

  • EntranceAngle=0.0 – entrance angle

  • ExitAngle=0.0 – exit angle

  • PolynomB – straight multipoles

  • PolynomA – skew multipoles

  • MaxOrder – Number of desired multipoles

  • NumIntSt=10 – Number of integration steps

  • FullGap – Magnet full gap

  • FringeInt1 – Fringe field extension

  • FringeInt2 –

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

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

DefaultOrder = 0#
class Drift(family_name, length, **kwargs)[source]#

Bases: LongElement

Drift space element

Parameters:

  • family_name (str) – Name of the element

  • length (float) – Element length [m]

Default PassMethod: DriftPass

insert(insert_list)[source]#

insert elements inside a drift

Parameters:

insert_list (Iterable[Tuple[float, Optional[Element]]]) –

iterable, each item of insert_list is itself an iterable with 2 objects:

  1. the location where the center of the element will be inserted, given as a fraction of the Drift length.

  2. an element to be inserted at that location. If None, the drift will be divided but no element will be inserted.

Returns:

elem_list – a list of elements.

Drifts with negative lengths may be generated if necessary.

Examples

>>> Drift('dr', 2.0).insert(((0.25, None), (0.75, None)))
[Drift('dr', 0.5), Drift('dr', 1.0), Drift('dr', 0.5)]

>>> Drift('dr', 2.0).insert(((0.0, Marker('m1')),
... (0.5, Marker('m2'))))
[Marker('m1'), Drift('dr', 1.0), Marker('m2'), Drift('dr', 1.0)]

>>> Drift('dr', 2.0).insert(((0.5, Quadrupole('qp', 0.4, 0.0)),))
[Drift('dr', 0.8), Quadrupole('qp', 0.4), Drift('dr', 0.8)]
class Element(family_name, **kwargs)[source]#

Bases: object

Base class for AT elements

Parameters:

family_name (str) – Name of the element

All keywords will be set as attributes of the element

copy()[source]#

Return a shallow copy of the element

deepcopy()[source]#

Return a deep copy of the element

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)]
equals(other)[source]#

Whether an element is equivalent to another.

This implementation was found to be too slow for the generic __eq__ method when comparing lattices.

is_compatible(other)[source]#

Checks if another Element can be merged

items()[source]#

Iterates through the data members

merge(other)[source]#

Merge another element

swap_faces(copy=False)[source]#

Swap the faces of an element, alignment errors are ignored

update(**kwargs)[source]#
update(mapping, **kwargs) → None
update(iterable, **kwargs) → None

Update the element attributes with the given arguments

property is_collective: bool#

True if the element involves collective effects

property longt_motion: bool#

True if longitudinal motion is affected by the element

class LongElement(family_name, length, *args, **kwargs)[source]#

Bases: Element

Base class for long elements

Parameters:

  • family_name (str) – Name of the element

  • length (float) – Element length [m]

Other arguments and keywords are given to the base class

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)]
is_compatible(other)[source]#

Checks if another Element can be merged

merge(other)[source]#

Merge another element

class LongtMotion[source]#

Bases: ABC

Abstract Base class for all Element classes whose instances may modify the particle momentum

Allows to identify elements potentially inducing longitudinal motion.

Subclasses of LongtMotion must provide two methods for enabling longitudinal motion:

  • _get_longt_motion(self) must return the activation state,

  • set_longt_motion(self, enable, new_pass=None, copy=False, **kwargs) must enable or disable longitudinal motion.

abstract set_longt_motion(enable, new_pass=None, copy=False, **kwargs)[source]#

Enable/Disable longitudinal motion

Parameters:

  • enable – True: for enabling, False for disabling

  • new_pass –

    New PassMethod:

    • None: makes no change,

    • 'auto': Uses the default conversion,

    • Anything else is used as the new PassMethod.

  • copy – If True, returns a modified copy of the element, otherwise modifies the element in-place

class M66(family_name, m66=None, **kwargs)[source]#

Bases: Element

Linear (6, 6) transfer matrix

Parameters:

  • family_name (str) – Name of the element

  • m66 – Transfer matrix. Default: Identity matrix

Default PassMethod: Matrix66Pass

class Marker(family_name, **kwargs)[source]#

Bases: Element

Marker element

Parameters:

family_name (str) – Name of the element

All keywords will be set as attributes of the element

class Monitor(family_name, **kwargs)[source]#

Bases: Element

Monitor element

Parameters:

family_name (str) – Name of the element

All keywords will be set as attributes of the element

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 normal multipole components

  • poly_b – Array of skew 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)

Default PassMethod: StrMPoleSymplectic4Pass

is_compatible(other)[source]#

Checks if another Element can be merged

property H: float#

Sextupolar strength

property K: float#

Focusing strength [mˆ-2]

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 normal multipole components

  • poly_b – Array of skew 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)

Default PassMethod: StrMPoleSymplectic4Pass

DefaultOrder = 3#
class Quadrupole(FamName, Length, Strength=0, **keywords)[source]#

Bases: Radiative, Multipole

Quadrupole element

Parameters:

  • family_name (str) – Name of the element

  • length (float) – Element length [m]

  • k (Optional[float]) – strength [mˆ-2]

Keyword Arguments:

  • PolynomB – straight multipoles

  • PolynomA – skew multipoles

  • MaxOrder – 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)

Default PassMethod: StrMPoleSymplectic4Pass

items()[source]#

Iterates through the data members

DefaultOrder = 1#
class QuantumDiffusion(family_name, lmatp, **kwargs)[source]#

Bases: _DictLongtMotion, Element

Quantum diffusion element

Parameters:

Default PassMethod: QuantDiffPass

default_pass = {False: 'IdentityPass', True: 'QuantDiffPass'}#
class RFCavity(family_name, length, voltage, frequency, harmonic_number, energy, **kwargs)[source]#

Bases: LongtMotion, LongElement

RF cavity element

Parameters:

  • family_name (str) – Name of the element

  • length (float) – Element length [m]

  • voltage (float) – RF voltage [V]

  • frequency (float) – RF frequency [Hz]

  • harmonic_number (int) –

  • energy (float) – ring energy [eV]

Keyword Arguments:

TimeLag=0 – Cavity time lag

Default PassMethod: RFCavityPass

is_compatible(other)[source]#

Checks if another Element can be merged

merge(other)[source]#

Merge another element

set_longt_motion(enable, new_pass=None, **kwargs)[source]#

Enable/Disable longitudinal motion

Parameters:

  • enable – True: for enabling, False for disabling

  • new_pass –

    New PassMethod:

    • None: makes no change,

    • 'auto': Uses the default conversion,

    • Anything else is used as the new PassMethod.

  • copy – If True, returns a modified copy of the element, otherwise modifies the element in-place

default_pass = {False: 'DriftPass', True: 'RFCavityPass'}#
class Radiative[source]#

Bases: _Radiative

Mixin class for default radiating elements (Dipole, Quadrupole, Wiggler)

Radiative is a base class for the subset of radiative elements considered as the ones to be turned on by default: Dipole, Quadrupole and Wiggler, excluding the higher order multipoles.

Radiative inherits from _Radiative and does not add any new functionality. Its purpose is to identify the default set of radiating elements.

Example

>>> class Dipole(Radiative, Multipole):

Defines a class belonging to the default radiating elements. It converts the PassMethod according to the “*Pass” or “*RadPass” suffix.

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 (Optional[float]) – strength [mˆ-3]

Keyword Arguments:

  • PolynomB – straight multipoles

  • PolynomA – skew multipoles

  • MaxOrder – Number of desired multipoles

  • NumIntSteps=10 – Number of integration steps

  • KickAngle – Correction deviation angles (H, V)

Default PassMethod: StrMPoleSymplectic4Pass

items()[source]#

Iterates through the data members

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 normal multipole components

  • poly_b – Array of skew multipole components

Keyword Arguments:

MaxOrder – Number of desired multipoles. Default: highest index of non-zero polynomial coefficients

Default PassMethod: ThinMPolePass

class Wiggler(family_name, length, wiggle_period, b_max, energy, 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) – beam energy [eV]

  • Nstep (Optional[int]) – number of integration steps.

  • Nmeth (Optional[int]) – 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

build_class_map()[source]#
get_class_map()[source]#