at.lattice.transformation#

Element translations and rotations.

Caution

The geometrical transformations are not commutative. When combining several transformations on the same element by using multiple function calls, the transformations are applied in a fixed order, independent of the order of the function calls:

translations -> tilt (z-axis) -> yaw (y-axis) -> pitch (x-axis)

Functions

get_offsets_rotations(elem[, reference, RB_half])

Return the offsets and rotations of a given element.

transform_elem(elem[, reference, dx, dy, ...])

Set the translations and rotations of an Element.

shift_elem(elem[, dx, dy, dz, relative])

Sets the translations of an Element

tilt_elem(elem, rots[, relative])

Set the tilt angle \(\theta\) of an Element

set_shift(ring, dxs, dys[, dzs, refpts, ...])

Sets the translations of a list of elements.

set_tilt(ring, tilts, *[, refpts, relative])

Sets the tilts of a list of elements.

set_rotation(ring[, tilts, pitches, yaws, ...])

Sets the rotations of a list of elements.

Classes

ReferencePoint(*values)

Definition of the reference point for the geometric transformations.
class ReferencePoint(*values)[source]#

Bases: Enum

Definition of the reference point for the geometric transformations.

CENTRE = 'CENTRE'#

Origin at the centre of the element.

ENTRANCE = 'ENTRANCE'#

Origin at the entrance of the element.

get_offsets_rotations(elem, reference=ReferencePoint.CENTRE, *, RB_half=None)[source]#

Return the offsets and rotations of a given element.

This function returns the offsets [dx, dy, dz] and angular rotations (tilt, yaw, pitch) of the element.

Parameters:
Returns:

  • offsets (np.ndarray) – [dx, dy, dz] array.

  • tilt (float) – Tilt angle (rotation about the Z-axis) in radians.

  • yaw (float) – Yaw angle (rotation about the Y-axis) in radians.

  • pitch (float) – Pitch angle (rotation about the X-axis) in radians.

Raises:

ValueError – If the reference argument is neither ReferencePoint.CENTRE nor ReferencePoint.ENTRANCE.

Attention

The reference argument must be identical to the one used when displacing the element. Otherwise, the result is unpredictable.

set_rotation(ring, tilts=0.0, pitches=0.0, yaws=0.0, *, refpts=RefptsCode.All, relative=False)[source]#

Sets the rotations of a list of elements.

Parameters:

  • ring (Sequence[Element]) – Lattice description.

  • tilts – Scalar or Sequence of tilt values applied to the selected elements. Use None to keep the current values.

  • pitches – Scalar or Sequence of pitch values applied to the selected elements. Use None to keep the current values.

  • yaws – Scalar or Sequence of yaw values applied to the selected elements. Use None to keep the current values.

  • refpts (Type[Element] | Element | Callable[[Element], bool] | str | None | int | Sequence[int] | bool | Sequence[bool] | RefptsCode) – Element selection key. See “Selecting elements in a lattice”

  • relative – If True, the rotations are added to the existing ones.

Added in version 0.7.0: The refpts argument

See also

set_tilt() set_shift()

set_shift(ring, dxs, dys, dzs=None, *, refpts=RefptsCode.All, relative=False)[source]#

Sets the translations of a list of elements.

Parameters:

  • ring (Sequence[Element]) – Lattice description.

  • dxs – Scalar or Sequence of horizontal translations values applied to the selected elements. Use None to keep the current values [m].

  • dys – Scalar or Sequence of vertical translations values applied to the selected elements. Use None to keep the current values [m].

  • dzs – Scalar or Sequence of longitudinal translations values applied to the selected elements. Use None to keep the current values [m].

  • refpts (Type[Element] | Element | Callable[[Element], bool] | str | None | int | Sequence[int] | bool | Sequence[bool] | RefptsCode) – Element selection key. See “Selecting elements in a lattice”

  • relative – If True, the translation is added to the existing one.

Added in version 0.7.0: The refpts argument

See also

set_rotation() set_tilt()

set_tilt(ring, tilts, *, refpts=RefptsCode.All, relative=False)[source]#

Sets the tilts of a list of elements.

Parameters:

Added in version 0.7.0: The refpts argument

See also

set_rotation() set_shift()

shift_elem(elem, dx=0.0, dy=0.0, dz=0.0, *, relative=False)[source]#

Sets the translations of an Element

The translation vectors are stored in the T1 and T2 attributes.

Parameters:

  • elem (Element) – Element to be shifted

  • dx (float | None) – Horizontal translation [m]. Use None to keep the current value.

  • dy (float | None) – Vertical translation [m]. Use None to keep the current value.

  • dz (float | None) – Longitudinal translation [m]. Use None to keep the current value.

  • relative (bool) – If True, the translation is added to the existing one

See also

tilt_elem() transform_elem()

tilt_elem(elem, rots, relative=False)[source]#

Set the tilt angle \(\theta\) of an Element

The rotation matrices are stored in the R1 and R2 attributes.

\(R_1=\begin{pmatrix} cos\theta & sin\theta \\ -sin\theta & cos\theta \end{pmatrix}\), \(R_2=\begin{pmatrix} cos\theta & -sin\theta \\ sin\theta & cos\theta \end{pmatrix}\)

Parameters:

  • elem (Element) – Element to be tilted

  • rots (float) – Tilt angle \(\theta\) [rd]. rots > 0 corresponds to a corkscrew rotation of the element looking in the direction of the beam. Use None to keep the current value.

  • relative (bool) – If True, the rotation is added to the existing one

See also

shift_elem() transform_elem()

transform_elem(elem, reference=ReferencePoint.CENTRE, dx=None, dy=None, dz=None, tilt=None, pitch=None, yaw=None, *, relative=False)[source]#

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 rebuilt from the r3d matrix and 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.

  • reference (ReferencePoint) – Transformation reference, either ReferencePoint.CENTRE or ReferencePoint.ENTRANCE.

  • 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

  • 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. Otherwise, the result is unpredictable.

See also

get_offsets_rotations()