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
`EnergyLoss`(family_name, energy_loss, **kwargs)	Energy loss element
`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
`SimpleQuantDiff`(family_name[, betax, betay, ...])	Linear tracking element for a simplified quantum diffusion, radiation damping and energy loss.
`SimpleRadiation`(family_name[, taux, tauy, ...])	Simple radiation damping and energy loss
`SliceMoments`(family_name, nslice, **kwargs)	Element to compute slices mean and std
`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

Default PassMethod: BeamMomentsPass

set_buffers(nturns, nbunch)[source]#

property means#: Beam 6d center of mass

property stds#: Beam 6d standard deviation

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)

Keyword Arguments:

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

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]
k (float) – Focusing strength [m^-2]

Keyword Arguments:

EntranceAngle=0.0 – entrance angle
ExitAngle=0.0 – exit angle
PolynomB – straight multipoles
PolynomA – skew multipoles
MaxOrder=0 – Number of desired multipoles
NumIntSt=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 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, Element | None]]) –

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

the location where the center of the element will be inserted, given as a fraction of the Drift length.
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.

static from_dict(elem_dict, index=None, check=True, quiet=False)#

Builds an Element from a dictionary of attributes

Parameters:

elem_dict (dict) – Dictionary of element attributes
index (int | None) – Element index
check (bool) – Check the compatibility of class and PassMethod
quiet (bool) – Suppress the warning for non-standard classes

Returns:

elem (Element) – new Element

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

to_dict(encoder=<function _no_encoder>)#

Convert a Element to a dict

Parameters:

elem (Element) – Element
encoder (Callable[[Any], Any]) – data converter

Returns:

dct (dict) – Dictionary of Element attributes

track(r_in, in_place=False, **kwargs)#

element_track() tracks particles through one element of a calling the element-specific tracking function specified in the Element’s PassMethod field

Usage:

>>> element_track(element, r_in)
>>> element.track(r_in)

Parameters:

element (Element) – element to track through
r_in – (6, N) array: input coordinates of N particles. For the best efficiency, r_in should be given as F_CONTIGUOUS numpy array.

Keyword Arguments:

in_place (bool) – If True r_in is modified in-place and reports the coordinates at the end of the element. (default: False)
omp_num_threads (int) – Number of OpenMP threads (default: automatic)
particle (Optional[Particle]) – circulating particle. Default: lattice.particle if existing, otherwise Particle('relativistic')
energy (Optiona[float]) – lattice energy. Default 0.

Returns:

r_out – (6, N, R, T) array containing output coordinates of N particles at R reference points for T turns

update(**kwargs)[source]#
update(mapping, **kwargs) → None
update(iterable, **kwargs) → None: Update the element attributes with the given arguments

property definition: tuple[str, tuple, dict]#: tuple (class_name, args, kwargs) defining the element

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 EnergyLoss(family_name, energy_loss, **kwargs)[source]#

Bases: _DictLongtMotion, Element

Energy loss element

Parameters:

family_name (str) – Name of the element
energy_loss (float) – Energy loss [eV]

default_pass = {False: 'IdentityPass', True: 'EnergyLossRadPass'}#

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 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 H: float#: Sextupolar strength [mˆ-3]

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 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(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]) – Focusing strength [mˆ-2]

Keyword Arguments:

PolynomB – straight 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 QuantumDiffusion(family_name, lmatp, **kwargs)[source]#

Bases: _DictLongtMotion, Element

Quantum diffusion element

Parameters:

family_name (str) – Name of the element
lmatp (numpy.ndarray) – Diffusion matrix for generation (see gen_quantdiff_elem())

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)
FieldScaling – Scaling factor applied to the magnetic field (PolynomA and PolynomB)

Default PassMethod: StrMPoleSymplectic4Pass

items()[source]#

Iterates through the data members

DefaultOrder = 2#

class SimpleQuantDiff(family_name, betax=1.0, betay=1.0, emitx=0.0, emity=0.0, espread=0.0, taux=0.0, tauy=0.0, tauz=0.0, **kwargs)[source]#

Bases: _DictLongtMotion, Element

Linear tracking element for a simplified quantum diffusion, radiation damping and energy loss.

Note: The damping times are needed to compute the correct kick for the emittance. Radiation damping is NOT applied.

Parameters:: family_name (str) – Name of the element

Optional Args:: betax: Horizontal beta function at element [m] betay: Vertical beta function at element [m] emitx: Horizontal equilibrium emittance [m.rad] emity: Vertical equilibrium emittance [m.rad] espread: Equilibrium energy spread taux: Horizontal damping time [turns] tauy: Vertical damping time [turns] tauz: Longitudinal damping time [turns]

Default PassMethod: SimpleQuantDiffPass

default_pass = {False: 'IdentityPass', True: 'SimpleQuantDiffPass'}#

class SimpleRadiation(family_name, taux=0.0, tauy=0.0, tauz=0.0, U0=0.0, **kwargs)[source]#

Bases: _DictLongtMotion, Radiative, Element

Simple radiation damping and energy loss

Parameters:: family_name (str) – Name of the element

Optional Args:: taux: Horizontal damping time [turns] tauy: Vertical damping time [turns] tauz: Longitudinal damping time [turns] U0: Energy loss per turn [eV]

Default PassMethod: SimpleRadiationPass

default_pass = {False: 'IdentityPass', True: 'SimpleRadiationPass'}#

class SliceMoments(family_name, nslice, **kwargs)[source]#

Bases: Element

Element to compute slices mean and std

Parameters:

family_name (str) – Name of the element
nslice (int) – Number of slices

Keyword Arguments:

startturn – Start turn of the acquisition (Default 0)
endturn – End turn of the acquisition (Default 1)

Default PassMethod: SliceMomentsPass

set_buffers(nturns, nbunch)[source]#

property endturn#: End turn of the acquisition

property means#: Slices x,y,dp center of mass

property spos#: Slices s position

property startturn#: Start turn of the acquisition

property stds#: Slices x,y,dp standard deviation

property weights#: Slices weights in mA if beam current >0, otherwise fraction of total number of particles in the bunch

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 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
FieldScaling – Scaling factor applied to the magnetic field (PolynomA and PolynomB)

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]#