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

`set_rotation`(ring[, tilts, pitches, yaws, ...])	Sets the rotations of a list of elements.
`set_shift`(ring, dxs, dys[, dzs, refpts, ...])	Sets the translations of a list of elements.
`set_tilt`(ring[, tilts, tilts_frame, refpts, ...])	Sets the tilts of a list of elements.
`shift_elem`(elem[, dx, dy, dz, reference, ...])	Sets the translations of an `Element`
`tilt_elem`(elem[, rots, rots_frame, ...])	Set the tilt angle \(\theta\) of an `Element`
`transform_elem`(elem[, dx, dy, dz, tilt, ...])	Set the translations and rotations of an `Element`.

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

Sets the rotations of a list of elements.

Parameters:

ring (Sequence[Element]) – Lattice description.
tilts (Sequence[float] | float | None) – Scalar or Sequence of tilt values applied to the selected elements. Use None to keep the current values.
tilts_frame (Sequence[float] | float | None) – Scalar or Sequence of reference frame tilt values applied to the selected elements. Use None to keep the current values.
pitches (Sequence[float] | float | None) – Scalar or Sequence of pitch values applied to the selected elements. Use None to keep the current values.
yaws (Sequence[float] | float | None) – 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 “:ref: Selecting elements in a lattice <refpts>”
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 – 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, reference=None, 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”
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 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=None, *, tilts_frame=None, refpts=RefptsCode.All, reference=None, relative=False)[source]#

Sets the tilts of a list of elements.

Parameters:

ring (Sequence[Element]) – Lattice description.
tilts (Sequence[float] | float | None) – Scalar or Sequence of tilt values applied to the selected elements. Use None to keep the current values.
tilts_frame (Sequence[float] | float | None) – Scalar or Sequence of reference frame tilt 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”
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 rotation is added to the existing one.

Added in version 0.7.0: The refpts argument

See also

set_rotation() set_shift()

shift_elem(elem, dx=None, dy=None, dz=None, *, reference=None, 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]. Default no change.
dy (float | None) – Vertical translation [m]. Default no change.
dz (float | None) – Longitudinal translation [m]. 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 translation is added to the existing one

See also

tilt_elem() transform_elem()

tilt_elem(elem, rots=None, rots_frame=None, relative=False, reference=None)[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 | None) – 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.
rots_frame (float | None) – Tilt angle \(\theta\) [rd]. rots > 0 corresponds to a corkscrew rotation of the reference frame 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
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

See also

shift_elem() transform_elem()

transform_elem(elem, dx=None, dy=None, dz=None, tilt=None, pitch=None, yaw=None, *, tilt_frame=None, reference=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 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.