at.lattice.elements.element_object#

Base Element object.

Classes

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

class Element(*args, **kwargs)[source]#

Bases: object

Base class for AT elements.

Parameters:: family_name – 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.

get_parameter(attrname, index=None)[source]#

Extract a parameter of an element.

Unlike getattr(), get_parameter() returns the parameter itself instead of its value. If the item is not a parameter, both functions are equivalent, the value is returned.

Parameters:

attrname (str) – Attribute name
index (int | None) – Index in an array attribute. If None, the whole attribute is returned

Returns:

The parameter object or attribute value.

is_compatible(other)[source]#

Checks if another Element can be merged.

is_parameterised(attrname=None, index=None)[source]#

Check for the parameterisation of an element.

Parameters:

attrname (str | None) – Attribute name. If None, checks if any attribute is parameterised
index (int | None) – Index in an array attribute. If None, tests the whole attribute

Returns:

True if the attribute, or array item is parameterised, False otherwise

items(freeze=True)[source]#

Iterates through the data members.

keys()[source]#: Return a set of all attribute names.

merge(other)[source]#

Merge another element.

parameterise(attrname, index=None, name='')[source]#

Convert attribute to parameter preserving value.

The value of the attribute is kept unchanged. If the attribute is already parameterised, the existing parameter is returned.

Parameters:

attrname (str) – Attribute name
index (int | None) – Index in an array. If None, the whole attribute is parameterised
name (str) – Name of the created parameter

Returns:

A :py:class:`.ParamArray` for an array attribute,
a :py:class:`.Param` for a scalar attribute or an item in an
array attribute

Raises:

TypeError – If the attribute value is not a valid parameter type (Number)
IndexError – If the index is out of bounds for an array attribute
AttributeError – If the attribute does not exist

set_parameter(attrname, value, index=None)[source]#

Set an element’s parameter.

This allows setting a parameter into an attribute or an item of an array attribute.

Parameters:

attrname (str) – Attribute name
value (Any) – Parameter or value to be set
index (int | None) – Index into an array attribute. If value is a parameter, the array attribute is converted to a ParamArray.

Raises:

IndexError – If the provided index is out of bounds for the array attribute
AttributeError – If the attribute doesn’t exist

swap_faces(copy=False)[source]#: Swap the faces of an element, alignment errors are ignored.

to_dict(freeze=True)[source]#

Return a copy of the element parameters.

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.

unparameterise(attrname=None, index=None)[source]#

Replace parameters with their current values.

This function replaces parameters with their current values, effectively “freezing” them. This is useful when you want to convert a parameterised element back to a regular element with fixed values.

Parameters:

attrname (str | None) – Attribute name. If None, freezes all attributes
index (int | None) – Index in an array. If None, freezes the whole attribute

Attributes which are not parameters are silently ignored.

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(value)[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.