at.lattice.elements.element_object#

Base Element object.

Classes

`Element`(family_name, **kwargs)	Base class for AT elements.
`ReferencePoint`(*values)	Definition of the reference point for the geometric transformations.

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

classmethod from_file(elem_dict)[source]#

Generate an Element from a dictionary of attributes.

Parameters:: elem_dict (dict[str, Any]) – Dictionary of Element attributes
Returns:: elem (Element) – Element

classmethod subclasses()[source]#

Yields all the class subclasses.

Some classes may appear several times because of diamond-shape inheritance

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.

to_dict()[source]#

to_file(encoder=<function _no_encoder>)[source]#

Convert a Element to a dict.

Parameters:: 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

transform(dx=None, dy=None, dz=None, tilt=None, pitch=None, yaw=None, *, tilt_frame=None, reference=None, relative=False)#

Set the translations and rotations of an Element.

The tilt is a rotation around the s-axis, the pitch is a rotation around the x-axis, and the yaw is a rotation around the y-axis.

A positive angle represents a clockwise rotation when looking in the direction of the rotation axis.

The transformations are not all commutative. The translations are applied before the rotations. The rotations are applied in the order Z -> Y -> X (tilt -> yaw -> pitch). The element is rotated around its mid-point. The mid-point can either be the element entrance or its centre (axis joining the entry and exit points of the element).

If relative is True, the previous translations and angles are incremented by the input arguments.

PyAT describes the ultra-relativistic beam dynamics in 6D phase space coordinates, which differ from 3D spatial angles in an expansion with respect to the energy to first order by a factor \((1 + \delta)\), where \(\delta\) is the relative momentum deviation. This introduces spurious dispersion (angle proportional to \(\delta\)).

The implementation follows the one described in: https://doi.org/10.1016/j.nima.2022.167487 All the comments featuring ‘Eq’ point to the paper’s equations.

Parameters:

elem (Element) – Element to be transformed.
dx (float | None) – Horizontal shift [m]. Default: no change.
dy (float | None) – Vertical shift [m]. Default: no change.
dz (float | None) – Longitudinal shift [m]. Default: no change.
tilt (float | None) – Tilt angle [rad]. Default: no change.
pitch (float | None) – Pitch angle [rad]. Default: no change.
yaw (float | None) – Yaw angle [rad]. Default: no change
tilt_frame (float | None) – Tilt angle of the reference frame [rad]. Useful to generate vertical bending magnets for example Default no change
reference (ReferencePoint | None) – Transformation reference, either ReferencePoint.CENTRE or ReferencePoint.ENTRANCE. Default: ReferencePoint.CENTRE if the reference point was not previously set, otherwise to set reference point
relative (bool) – If True, the input values are added to the previous ones.

Attention

When combining several transformations by using multiple calls to transform_elem(), the reference argument must be identical for all. Setting the reference will therefore affect all transformations for this element.

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

property ReferencePoint: ReferencePoint#: Rotation reference point

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

property dx: float#: Horizontal element shift

property dy: float#: Vertical element shift

property dz: float#: Longitudinal element shift

property is_collective: bool#: True if the element involves collective effects.

property longt_motion: bool#: True if the element affects the longitudinal motion.

property pitch: float#: Element pitch

property tilt: float#: Element tilt

property tilt_frame: float#: Element tilt frame, different from tilt only for bends

property yaw: float#: Element yaw

class ReferencePoint(*values)[source]#

Bases: Enum

Definition of the reference point for the geometric transformations.

CENTRE = 0#: Origin at the centre of the element.

ENTRANCE = 1#: Origin at the entrance of the element.