dipas.elements module¶

Accelerator lattice elements represented by PyTorch Modules.

The various element classes are made available together with the corresponding MADX command name in the following dicts.

dipas.elements.elements¶

Maps MADX command names to corresponding Element backend classes.

Type: dict

dipas.elements.alignment_errors¶

Maps MADX EALIGN command attributes to corresponding AlignmentError backend classes.

Type: dict

dipas.elements.aperture_types¶

Maps MADX apertypes definitions to corresponding Aperture backend classes.

Type: dict

class dipas.elements.ApertureCircle(aperture: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = <MagicMock name='mock.tensor()' id='139994648198112'>, padding: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = <MagicMock name='mock.tensor()' id='139994648198112'>, offset: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>] = <MagicMock name='mock.zeros()' id='139994648164560'>)¶

Bases: dipas.elements.Aperture

Circular aperture.

Parameters: aperture (Tensor, scalar (shape [])) – Radius of the circle.

classmethod loss(xy: <MagicMock name='mock.Tensor' id='139994648269432'>, aperture: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶

Compute the loss values for the given xy-positions.

Parameters

xy (Tensor) – Tensor of shape (2, N) where N is the number of particles and rows are x- and y-positions, respectively, centered within the aperture.
aperture (Tensor) – The effective aperture of the element, interpreted by the particular subclass.

Returns

loss_val – Tensor of shape (N,), zero where positions are inside the aperture (including exactly at the aperture) and greater than zero where positions are outside the aperture.

Return type

Tensor

class dipas.elements.ApertureEllipse(aperture: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = <MagicMock name='mock.tensor()' id='139994648198112'>, padding: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>] = <MagicMock name='mock.zeros()' id='139994648164560'>, offset: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>] = <MagicMock name='mock.zeros()' id='139994648164560'>)¶

Bases: dipas.elements.Aperture

Elliptical aperture.

Parameters: aperture (Tensor, shape (2,)) – Horizontal and vertical semi-axes of the ellipse.

classmethod loss(xy: <MagicMock name='mock.Tensor' id='139994648269432'>, aperture: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶

Compute the loss values for the given xy-positions.

Parameters

xy (Tensor) – Tensor of shape (2, N) where N is the number of particles and rows are x- and y-positions, respectively, centered within the aperture.
aperture (Tensor) – The effective aperture of the element, interpreted by the particular subclass.

Returns

loss_val – Tensor of shape (N,), zero where positions are inside the aperture (including exactly at the aperture) and greater than zero where positions are outside the aperture.

Return type

Tensor

class dipas.elements.ApertureRectangle(aperture: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = <MagicMock name='mock.tensor()' id='139994648198112'>, padding: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>] = <MagicMock name='mock.zeros()' id='139994648164560'>, offset: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>] = <MagicMock name='mock.zeros()' id='139994648164560'>)¶

Bases: dipas.elements.Aperture

Rectangular aperture.

Parameters: aperture (Tensor, shape (2,)) – Half width (horizontal) and half height (vertical) of the rectangle.

classmethod loss(xy: <MagicMock name='mock.Tensor' id='139994648269432'>, aperture: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶

Compute the loss values for the given xy-positions.

Parameters

xy (Tensor) – Tensor of shape (2, N) where N is the number of particles and rows are x- and y-positions, respectively, centered within the aperture.
aperture (Tensor) – The effective aperture of the element, interpreted by the particular subclass.

Returns

loss_val – Tensor of shape (N,), zero where positions are inside the aperture (including exactly at the aperture) and greater than zero where positions are outside the aperture.

Return type

Tensor

class dipas.elements.ApertureRectEllipse(aperture: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = <MagicMock name='mock.tensor()' id='139994648198112'>, padding: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>] = <MagicMock name='mock.zeros()' id='139994648164560'>, offset: Union[List[Union[int, float]], Tuple[Union[int, float], ...], <MagicMock name='mock.Tensor' id='139994648269432'>] = <MagicMock name='mock.zeros()' id='139994648164560'>)¶

Bases: dipas.elements.Aperture

Overlay of rectangular and elliptical aperture.

Parameters: aperture (Tensor, shape (4,)) – Half width (horizontal) and half height (vertical) of the rectangle followed by horizontal and vertical semi-axes of the ellipse.

classmethod loss(xy: <MagicMock name='mock.Tensor' id='139994648269432'>, aperture: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶

Compute the loss values for the given xy-positions.

Parameters

xy (Tensor) – Tensor of shape (2, N) where N is the number of particles and rows are x- and y-positions, respectively, centered within the aperture.
aperture (Tensor) – The effective aperture of the element, interpreted by the particular subclass.

Returns

loss_val – Tensor of shape (N,), zero where positions are inside the aperture (including exactly at the aperture) and greater than zero where positions are outside the aperture.

Return type

Tensor

class dipas.elements.Marker(**kwargs)¶

Bases: dipas.elements.Element

Marker element.

exact(x: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶: Exact analytic solution for tracking through the element.

linear(x: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶: Linear tracking through the element.

class dipas.elements.Drift(l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], *, beam: dict, **kwargs)¶

Bases: dipas.elements.Element

Drift space.

Note

Unlike in MADX, drift spaces feature aperture checks here.

Parameters: l (Number) – Length of the drift [m].

exact(x)¶: Exact analytic solution for tracking through the element.

makethin(n: int, *, style: Optional[str] = None) → dipas.elements.Drift¶: Drift spaces are not affected by makethin.

update_transfer_map(*, reset=False) → None¶

Update the element’s transfer map coefficients (d, R, T) to correspond to the elements’ parameters.

This method should be called after any of the elements’ parameters have been modified in order to update the transfer map to correspond to the new values.

Parameters: reset (bool) – If True then the tensors corresponding to transfer map coefficients are replaced by new tensor objects before their values are updated. In this case the resulting tensors guarantee to reflect any change in the elements attribute, parametrized and non-parametrized (see notes below).

Notes

This method guarantees to incorporate the values of all parameters but not for non-parameter attributes (such as the length of an element; these are only guaranteed to be incorporated if reset=True). For reset=False these non-parameter attributes might be reflected in the transfer map update but this is an implementation detail that should not be relied on. Even though this method is only relevant for elements that cache their transfer map and for others it is a no-op, this caching property also is an implementation detail that should not be relied on. Hence after having modified an element the update_transfer_map method should be called.

class dipas.elements.Instrument(l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], *, beam: dict, **kwargs)¶

Bases: dipas.elements.Drift

A place holder for any type of beam instrumentation.

class dipas.elements.Placeholder(l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], *, beam: dict, **kwargs)¶

Bases: dipas.elements.Drift

A place holder for any type of element.

class dipas.elements.Monitor(l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], *, beam: dict, **kwargs)¶

Bases: dipas.elements.Drift

Beam position monitor.

class dipas.elements.HMonitor(l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], *, beam: dict, **kwargs)¶

Bases: dipas.elements.Monitor

Beam position monitor for measuring horizontal beam position.

class dipas.elements.VMonitor(l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], *, beam: dict, **kwargs)¶

Bases: dipas.elements.Monitor

Beam position monitor for measuring horizontal beam position.

class dipas.elements.Kicker(hkick: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, vkick: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, *, beam: Optional[dict] = None, **kwargs)¶

Bases: dipas.elements.Element

Combined horizontal and vertical kicker magnet.

Parameters

hkick (Number or Parameter) – Horizontal kick [rad].
vkick (Number or Parameter) – Vertical kick [rad].

property d¶

linear(x: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶: Linear tracking through the element.

reset_transfer_map()¶

second_order(x: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶: Second order tracking through the element.

property transfer_map¶

class dipas.elements.HKicker(kick: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>], l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, *, beam: Optional[dict] = None, **kwargs)¶

Bases: dipas.elements.Kicker

Horizontal kicker magnet.

property kick¶

class dipas.elements.VKicker(kick: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>], l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, *, beam: Optional[dict] = None, **kwargs)¶

Bases: dipas.elements.Kicker

Vertical kicker magnet.

property kick¶

class dipas.elements.TKicker(hkick: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, vkick: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, *, beam: Optional[dict] = None, **kwargs)¶

Bases: dipas.elements.Kicker

Similar to Kicker (see Chapter 10.12, MADX User’s Guide).

class dipas.elements.Quadrupole(k1: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>], l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], *, beam: dict, dk1: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, **kwargs)¶

Bases: dipas.elements.Element

Quadrupole magnet.

Whether this is a (horizontally) focusing or defocusing magnet is determined from the value of k1 (k1 > 0 indicates a horizontally focusing quadrupole). Hence, in case k1 is a Parameter, it always must be non-zero. For that reason it is convenient to use boundaries e.g. [eps, k1_max] with a small number eps (e.g. 1e-16) and clip the value of k1 accordingly. If k1 is not a Parameter it can be zero and a corresponding Drift transformation will be used.

Parameters

k1 (Number or Parameter) – Normalized quadrupole gradient strength [1/m^2].
dk1 (Number or Parameter) – Absolute error of k1 [1/m^2].

field_errors = {'k1': 'dk1'}¶

makethin(n: int, *, style: Optional[str] = None) → Union[dipas.elements.Quadrupole, dipas.elements.ThinElement]¶

Transform element to a sequence of n thin elements using the requested slicing style.

Important

If optimization of parameters is required then it is important to call makethin before each forward pass in order to always use the up-to-date parameter values from the original elements. Calling makethin only once at the beginning and then reusing the resulting sequence on every iteration would reuse the initial parameter values and hence make the optimization ineffective.

Parameters

n (int) – The number of slices (thin elements).
style (str, optional) – The slicing style to be used. For available styles see ThinElement.create_thin_sequence().

Returns

A segment containing the slices (thin elements) separated by drifts.

Return type

ThinElement

See also

ThinElement.create_thin_sequence()

update_transfer_map(*, reset=False) → None¶

Update the element’s transfer map coefficients (d, R, T) to correspond to the elements’ parameters.

This method should be called after any of the elements’ parameters have been modified in order to update the transfer map to correspond to the new values.

Parameters: reset (bool) – If True then the tensors corresponding to transfer map coefficients are replaced by new tensor objects before their values are updated. In this case the resulting tensors guarantee to reflect any change in the elements attribute, parametrized and non-parametrized (see notes below).

Notes

This method guarantees to incorporate the values of all parameters but not for non-parameter attributes (such as the length of an element; these are only guaranteed to be incorporated if reset=True). For reset=False these non-parameter attributes might be reflected in the transfer map update but this is an implementation detail that should not be relied on. Even though this method is only relevant for elements that cache their transfer map and for others it is a no-op, this caching property also is an implementation detail that should not be relied on. Hence after having modified an element the update_transfer_map method should be called.

class dipas.elements.Sextupole(k2: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>], l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], *, beam: dict, dk2: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, **kwargs)¶

Bases: dipas.elements.Element

Sextupole magnet.

Parameters

k2 (Number or Parameter) – Normalized sextupole coefficient [1/m^3].
dk2 (Number or Parameter) – Absolute error of k2 [1/m^3].

field_errors = {'k2': 'dk2'}¶

makethin(n: int, *, style: Optional[str] = None) → Union[dipas.elements.Sextupole, dipas.elements.ThinElement]¶

Transform element to a sequence of n thin elements using the requested slicing style.

Important

If optimization of parameters is required then it is important to call makethin before each forward pass in order to always use the up-to-date parameter values from the original elements. Calling makethin only once at the beginning and then reusing the resulting sequence on every iteration would reuse the initial parameter values and hence make the optimization ineffective.

Parameters

n (int) – The number of slices (thin elements).
style (str, optional) – The slicing style to be used. For available styles see ThinElement.create_thin_sequence().

Returns

A segment containing the slices (thin elements) separated by drifts.

Return type

ThinElement

See also

ThinElement.create_thin_sequence()

update_transfer_map(*, reset=False) → None¶

Update the element’s transfer map coefficients (d, R, T) to correspond to the elements’ parameters.

This method should be called after any of the elements’ parameters have been modified in order to update the transfer map to correspond to the new values.

Parameters: reset (bool) – If True then the tensors corresponding to transfer map coefficients are replaced by new tensor objects before their values are updated. In this case the resulting tensors guarantee to reflect any change in the elements attribute, parametrized and non-parametrized (see notes below).

Notes

This method guarantees to incorporate the values of all parameters but not for non-parameter attributes (such as the length of an element; these are only guaranteed to be incorporated if reset=True). For reset=False these non-parameter attributes might be reflected in the transfer map update but this is an implementation detail that should not be relied on. Even though this method is only relevant for elements that cache their transfer map and for others it is a no-op, this caching property also is an implementation detail that should not be relied on. Hence after having modified an element the update_transfer_map method should be called.

class dipas.elements.SBend(angle: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], e1: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, e2: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, fint: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, bool] = 0.0, fintx: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, None] = None, hgap: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, h1: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, h2: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, *, beam: dict, dk0: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, aperture: Optional[dipas.elements.Aperture] = None, label: Optional[str] = None, **kwargs)¶

Bases: dipas.elements.CompoundElement

Sector bending magnet.

Parameters

angle (Number) – Bending angle of the dipole [rad].
e1 (Number) – Rotation angle for the entrance pole face [rad]. e1 = e2 = angle/2 turns an SBEND into a RBEND.
e2 (Number) – Rotation angle for the exit pole face [rad].
fint (Number) – Fringing field integral at entrance. If fintx is not specified then fint is also used at the exit.
fintx (Number) – Fringing field integral at exit.
hgap (Number) – Half gap of the magnet [m].
h1 (Number) – Curvature of the entrance pole face [1/m].
h2 (Number) – Curvature of the exit pole face [1/m].

property angle¶

property dk0¶

property e1¶

property e2¶

field_errors = {'k0': 'dk0'}¶

property fint¶

property fintx¶

flatten() → Iterator[dipas.elements.SBend]¶: Retrieve a flat representation of the segment (with sub-segments flattened as well).

property h1¶

property h2¶

property hgap¶

property k0¶

class dipas.elements.RBend(angle: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], e1: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, e2: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, fint: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, bool] = 0.0, fintx: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, None] = None, hgap: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, h1: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, h2: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, *, beam: dict, dk0: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, aperture: Optional[dipas.elements.Aperture] = None, label: Optional[str] = None, **kwargs)¶

Bases: dipas.elements.SBend

Sector bending magnet with parallel pole faces (see SBend).

class dipas.elements.Dipedge(h: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], e1: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], fint: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], hgap: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>], he: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>] = 0, *, entrance: bool = True, **kwargs)¶

Bases: dipas.elements.Element

Fringing fields at the entrance and exit of dipole magnets.

Parameters

h (Number) – Curvature of the associated dipole magnet body.
e1 (Number) – The rotation angle of the pole face.
fint (Number) – The fringing field integral.
hgap (Number) – The half gap height of the associated dipole magnet.
he (Number) – The curvature of the pole face.

makethin(n: int, *, style: Optional[str] = None) → Union[dipas.elements.Element, dipas.elements.ThinElement]¶

Transform element to a sequence of n thin elements using the requested slicing style.

Important

If optimization of parameters is required then it is important to call makethin before each forward pass in order to always use the up-to-date parameter values from the original elements. Calling makethin only once at the beginning and then reusing the resulting sequence on every iteration would reuse the initial parameter values and hence make the optimization ineffective.

Parameters

n (int) – The number of slices (thin elements).
style (str, optional) – The slicing style to be used. For available styles see ThinElement.create_thin_sequence().

Returns

A segment containing the slices (thin elements) separated by drifts.

Return type

ThinElement

See also

ThinElement.create_thin_sequence()

update_transfer_map(*, reset=False) → None¶

Update the element’s transfer map coefficients (d, R, T) to correspond to the elements’ parameters.

This method should be called after any of the elements’ parameters have been modified in order to update the transfer map to correspond to the new values.

Parameters: reset (bool) – If True then the tensors corresponding to transfer map coefficients are replaced by new tensor objects before their values are updated. In this case the resulting tensors guarantee to reflect any change in the elements attribute, parametrized and non-parametrized (see notes below).

Notes

This method guarantees to incorporate the values of all parameters but not for non-parameter attributes (such as the length of an element; these are only guaranteed to be incorporated if reset=True). For reset=False these non-parameter attributes might be reflected in the transfer map update but this is an implementation detail that should not be relied on. Even though this method is only relevant for elements that cache their transfer map and for others it is a no-op, this caching property also is an implementation detail that should not be relied on. Hence after having modified an element the update_transfer_map method should be called.

class dipas.elements.ThinQuadrupole(k1l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>], *, dk1l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, **kwargs)¶

Bases: dipas.elements.Element

Thin lens representation of a quadrupole magnet.

Parameters

k1l (Number or Parameter) – Integrated quadrupole gradient strength [1/m].
dk1l (Number or Parameter) – Absolute error of k1l [1/m].

field_errors = {'k1l': 'dk1l'}¶

makethin(n: int, *, style: Optional[str] = None) → NoReturn¶

Transform element to a sequence of n thin elements using the requested slicing style.

Important

If optimization of parameters is required then it is important to call makethin before each forward pass in order to always use the up-to-date parameter values from the original elements. Calling makethin only once at the beginning and then reusing the resulting sequence on every iteration would reuse the initial parameter values and hence make the optimization ineffective.

Parameters

n (int) – The number of slices (thin elements).
style (str, optional) – The slicing style to be used. For available styles see ThinElement.create_thin_sequence().

Returns

A segment containing the slices (thin elements) separated by drifts.

Return type

ThinElement

See also

ThinElement.create_thin_sequence()

update_transfer_map(*, reset=False) → None¶

Update the element’s transfer map coefficients (d, R, T) to correspond to the elements’ parameters.

This method should be called after any of the elements’ parameters have been modified in order to update the transfer map to correspond to the new values.

Parameters: reset (bool) – If True then the tensors corresponding to transfer map coefficients are replaced by new tensor objects before their values are updated. In this case the resulting tensors guarantee to reflect any change in the elements attribute, parametrized and non-parametrized (see notes below).

Notes

This method guarantees to incorporate the values of all parameters but not for non-parameter attributes (such as the length of an element; these are only guaranteed to be incorporated if reset=True). For reset=False these non-parameter attributes might be reflected in the transfer map update but this is an implementation detail that should not be relied on. Even though this method is only relevant for elements that cache their transfer map and for others it is a no-op, this caching property also is an implementation detail that should not be relied on. Hence after having modified an element the update_transfer_map method should be called.

class dipas.elements.ThinSextupole(k2l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>], *, dk2l: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, **kwargs)¶

Bases: dipas.elements.Element

Thin lens representation of a sextupole magnet.

Parameters

k2l (Number or Parameter) – Integrated sextupole coefficient [1/m^2].
dk2l (Number or Parameter) – Absolute error of k2l [1/m^2].

field_errors = {'k2l': 'dk2l'}¶

makethin(n: int, *, style: Optional[str] = None) → NoReturn¶

Transform element to a sequence of n thin elements using the requested slicing style.

Important

If optimization of parameters is required then it is important to call makethin before each forward pass in order to always use the up-to-date parameter values from the original elements. Calling makethin only once at the beginning and then reusing the resulting sequence on every iteration would reuse the initial parameter values and hence make the optimization ineffective.

Parameters

n (int) – The number of slices (thin elements).
style (str, optional) – The slicing style to be used. For available styles see ThinElement.create_thin_sequence().

Returns

A segment containing the slices (thin elements) separated by drifts.

Return type

ThinElement

See also

ThinElement.create_thin_sequence()

update_transfer_map(*, reset=False) → None¶

Update the element’s transfer map coefficients (d, R, T) to correspond to the elements’ parameters.

This method should be called after any of the elements’ parameters have been modified in order to update the transfer map to correspond to the new values.

Parameters: reset (bool) – If True then the tensors corresponding to transfer map coefficients are replaced by new tensor objects before their values are updated. In this case the resulting tensors guarantee to reflect any change in the elements attribute, parametrized and non-parametrized (see notes below).

Notes

This method guarantees to incorporate the values of all parameters but not for non-parameter attributes (such as the length of an element; these are only guaranteed to be incorporated if reset=True). For reset=False these non-parameter attributes might be reflected in the transfer map update but this is an implementation detail that should not be relied on. Even though this method is only relevant for elements that cache their transfer map and for others it is a no-op, this caching property also is an implementation detail that should not be relied on. Hence after having modified an element the update_transfer_map method should be called.

class dipas.elements.Tilt(target: Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, dipas.elements.AlignmentError], psi: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0)¶

Bases: dipas.elements.LongitudinalRoll

The tilt of an element represents the roll about the longitudinal axis.

Note

MADX uses a right-handed coordinate system (see Fig. 1.1, MADX User’s Guide), therefore x = x*cos(psi) - y*sin(psi) describes a clockwise rotation of the trajectory.

psi¶

Rotation angle about s-axis.

Type: Number or Parameter

Notes

Tilt is only a subclass of AlignmentError for technical reasons and has no meaning beyond that. A Tilt is not considered an alignment error from the simulation point of view.

triggers = ('tilt',)¶

class dipas.elements.Offset(target: Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, dipas.elements.AlignmentError], dx: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, dy: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0)¶

Bases: dipas.elements.AlignmentError

AlignmentError representing the xy-offset of an element.

dx¶

Horizontal offset.

Type: Number or Parameter

dy¶

Vertical offset.

Type: Number or Parameter

property d_enter¶

property d_exit¶

triggers = ('dx', 'dy')¶

class dipas.elements.LongitudinalRoll(target: Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, dipas.elements.AlignmentError], psi: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0)¶

Bases: dipas.elements.AlignmentError

AlignmentError representing the roll about the longitudinal axis of an element.

Note

MADX uses a right-handed coordinate system (see Fig. 1.1, MADX User’s Guide), therefore x = x*cos(psi) - y*sin(psi) describes a clockwise rotation of the trajectory.

psi¶

Rotation angle about s-axis.

Type: Number or Parameter

property R_enter¶

property R_exit¶

triggers = ('dpsi',)¶

class dipas.elements.BPMError(target: Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, dipas.elements.AlignmentError], ax: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, ay: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, rx: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0, ry: Union[int, float, <MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.nn.Parameter' id='139994650427520'>] = 0)¶

Bases: dipas.elements.AlignmentError

BPM readout errors.

The actual BPM reading is computed as (for both horizontal and vertical plane separately): rx * (x + ax).

ax¶

Horizontal absolute read error.

Type: Tensor or Parameter

ay¶

Vertical absolute read error.

Type: Tensor or Parameter

rx¶

Horizontal relative read error.

Type: Tensor or Parameter

ry¶

Vertical relative read error.

Type: Tensor or Parameter

enter(x: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶: Applies linear coordinate transformation at the entrance of the wrapped element.

exit(x: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶: Applies linear coordinate transformation at the exit of the wrapped element.

readout(x: <MagicMock name='mock.Tensor' id='139994648269432'>) → <MagicMock name='mock.Tensor' id='139994648269432'>¶

Return BPM readings for the given coordinates.

Parameters: x (Tensor) – 6D phase-space coordinates of shape (6, N).
Returns: xy – BPM readings in x- and y-dimension of shape (2, N).
Return type: Tensor

triggers = ('mrex', 'mrey', 'mscalx', 'mscaly')¶

class dipas.elements.Segment(elements: Sequence[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]])¶

Bases: object

Wrapper class representing a sequence of elements (possibly a segment of the lattice).

Elements or sub-segments can be selected via __getitem__, i.e. segment[item] notation. Here item can be one of the following:

int - indicating the index position in the segment.
str - will be compared for equality against element labels; if a single element with that label is found it is returned otherwise all elements with that label are returned as a list. An exception are strings containing an asterisk which will be interpreted as a shell-style wildcard and converted to a corresponding regex Pattern.
re.Pattern - will be matched against element labels; a list of all matching elements is returned.
instance of Element or AlignmentError - the element itself (possibly wrapped by other AlignmentError instances is returned.
subclass of Element or AlignmentError - a list of elements of that type (possibly wrapped by AlignmentError instances) is returned.
tuple - must contain two elements, the first being one of the above types and the second an integer; the first element is used to select a list of matching elements and the second integer element is used to select the corresponding element from the resulting list.
slice - start and stop indices can be any of the above types that selects exactly a single element or None; a corresponding sub-Segment is returned. The step parameter of the slice is ignored. In case the stop marker is not None, the corresponding element is included in the selection.

An element of a segment can be updated by using __setitem__, i.e. segment[item] = ... notation, where item can be any of the above types that selects exactly a single element.

elements¶

Type: list of LatticeElement

compute_transfer_maps(method: typing_extensions.Literal['accumulate', 'reduce', 'local'][accumulate, reduce, local], *, order: typing_extensions.Literal[1, 2][1, 2] = 2, index: Optional[typing_extensions.Literal[0, 1, 2][0, 1, 2]] = None, symplectify: bool = True, unfold_alignment_errors: bool = False, d0: Optional[<MagicMock name='mock.Tensor' id='139994648269432'>] = None, R0: Optional[<MagicMock name='mock.Tensor' id='139994648269432'>] = None, T0: Optional[<MagicMock name='mock.Tensor' id='139994648269432'>] = None) → Iterator[Tuple[Optional[<MagicMock name='mock.Tensor' id='139994648269432'>], ...]]¶

Compute the transfer maps of the element.

Parameters

method (str) – Determines how the transfer maps are computed (for details see implementing class).
order (int) – Transfer map order used in computations.
index (int) – Only transfer map coefficients up to the specified index are stored in the results; others are None. If None then defaults to order.
symplectify (bool) – Whether to symplectify the first order coefficients (transfer matrix) after second order feed-down terms have been included.
unfold_alignment_errors (bool) – Whether to treat alignment error transformations as separate transfer maps rather than contracting them with the wrapped lattice element.
R0, T0 (d0,) – Starting values at the beginning of the element (d0 corresponds to the closed orbit value).

Yields

transfer_map (TransferMap) – Depending on the selected method.

exact(x: <MagicMock name='mock.Tensor' id='139994648269432'>, **kwargs) → Union[<MagicMock name='mock.Tensor' id='139994648269432'>, Tuple]¶: Exact tracking through the segment.

flat() → dipas.elements.Segment¶: Convenience function wrapping Segment.flatten.

flatten() → Iterator[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, dipas.elements.AlignmentError]]¶: Retrieve a flat representation of the segment (with sub-segments flattened as well).

forward(x: <MagicMock name='mock.Tensor' id='139994648269432'>, *, method: Union[str, Callable[[<MagicMock name='mock.Tensor' id='139994648269432'>], <MagicMock name='mock.Tensor' id='139994648269432'>], Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[str, Callable[[<MagicMock name='mock.Tensor' id='139994648269432'>], <MagicMock name='mock.Tensor' id='139994648269432'>]]], List[Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[str, Callable[[<MagicMock name='mock.Tensor' id='139994648269432'>], <MagicMock name='mock.Tensor' id='139994648269432'>]]]], Dict[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[str, Callable[[<MagicMock name='mock.Tensor' id='139994648269432'>], <MagicMock name='mock.Tensor' id='139994648269432'>]]]], aperture: bool = False, exact_drift: bool = True, observe: Union[bool, int, str, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], List[Union[int, str, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]]], None] = None, recloss: Union[bool, int, str, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], List[Union[int, str, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]]], None] = None, loss_func: Optional[Callable[[<MagicMock name='mock.Tensor' id='139994648269432'>], <MagicMock name='mock.Tensor' id='139994648269432'>]] = None) → Union[<MagicMock name='mock.Tensor' id='139994648269432'>, Tuple]¶

Track the given particles through the segment.

Parameters

x (Tensor) – Shape (6, N) where N is the number of particles.
method (SelectionCriteria of str or callable) – Method name which will be used for the lattice elements to perform tracking.
aperture (bool) – Determines whether aperture checks are performed (and thus particles marked lost / excluded from tracking).
exact_drift (bool) – If true (default) then Drift`s will always be tracked through via `exact, no matter what method is.
observe (sequence of {str or re.Pattern or subclass of Element}) – Indicates relevant observation points; the (intermediary) positions at these places will be returned. Items are matched against element labels (see function match_element).
recloss (bool or “sum” or {str or re.Pattern or subclass of Element} or a sequence thereof) – If “sum” then the particle loss at each element will be recorded and summed into a single variable which will be returned. If a sequence is given it must contain element labels or regex patterns and the loss will be recorded only at the corresponding elements (similar to observe for positions). If True then the loss will be recorded at all elements; if False the loss is not recorded at all. A true value for this parameter will automatically set aperture to True.
loss_func (callable) – This parameter can be used to supply a function for transforming the returned loss at each element. This can be useful if some variation of the loss is to be accumulated into a single tensor. The function receives the loss tensor as returned by Aperture.loss as an input and should return a tensor of any shape. If not supplied this function defaults to torch.sum if recloss == “accumulate” and the identity if recloss == "history". Note that if a function is supplied it needs to cover all the steps, also the summation in case recloss == "accumulate" (the default only applies if no function is given).

Returns

x (Tensor) – Shape (6, M) where M is the number of particles that reached the end of the segment (M can be different from N in case aperture checks are performed).
history (dict) – The (intermediary) positions at the specified observation points. Keys are element labels and values are positions of shape (6, M_i) where M_i is the number of particles that reached that element. This is only returned if observe is true.
loss (Tensor or dict) – If recloss == "accumulate" the loss value accumulated for each element (i.e. the sum of all individual loss values) is returned. Otherwise, if recloss is true, a dict mapping element labels to recorded loss values is returned.

get_element_index(marker: Union[int, str, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int]]) → int¶

property l¶

linear(x: <MagicMock name='mock.Tensor' id='139994648269432'>, **kwargs) → Union[<MagicMock name='mock.Tensor' id='139994648269432'>, Tuple]¶: Linear tracking through the segment.

makethin(n: Union[int, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], int], List[Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], int]], Dict[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], int]], *, style: Union[str, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], str], List[Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], str]], Dict[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], str], None] = None) → dipas.elements.Segment¶

Retrieve a thin representation for each element of the segment except for those indicated by exclude.

Parameters

n (SelectionCriteria of int) –
Number of thin slices. If int this applies to all elements. Otherwise must key-value pairs. Keys should be element selectors (see SingleElementSelector and MultiElementSelector) or None for providing a default. Values should be the corresponding number of slices that are applied to the elements that match the key selector. Only the first matching key is considered. If a default value is desired it can be provided in various ways:
1. Using {None: default_value}.
2. Using a regex that matches any label (given that all elements have a label different from None).
3. Using the class Element.
Note that for all options these should appear at the very end of the list of criteria, otherwise they will override any subsequent definitions.
style (SelectionCriteria of str) – Slicing style per element. Works similar to the n parameter. See Element.makethin() for more information about available slicing styles.

Returns

Containing thin elements.

Return type

Segment

See also

find_matching_criterion(): For details about how keys in n can be used to fine-tune the slice number per element.
Element.makethin(): For available slicing styles.

second_order(x: <MagicMock name='mock.Tensor' id='139994648269432'>, **kwargs) → Union[<MagicMock name='mock.Tensor' id='139994648269432'>, Tuple]¶: Second order tracking through the segment.

transfer_maps(method: typing_extensions.Literal['accumulate', 'reduce', 'local'][accumulate, reduce, local], *, order: typing_extensions.Literal[1, 2][1, 2] = 2, indices: Union[typing_extensions.Literal[0, 1, 2][0, 1, 2], Tuple[typing_extensions.Literal[0, 1, 2][0, 1, 2], ...], None] = None, symplectify: bool = True, labels: bool = False, unfold_alignment_errors: bool = False, d0: Optional[<MagicMock name='mock.Tensor' id='139994648269432'>] = None, R0: Optional[<MagicMock name='mock.Tensor' id='139994648269432'>] = None, T0: Optional[<MagicMock name='mock.Tensor' id='139994648269432'>] = None) → Union[<MagicMock name='mock.Tensor' id='139994648269432'>, Tuple[Optional[<MagicMock name='mock.Tensor' id='139994648269432'>], ...], List[<MagicMock name='mock.Tensor' id='139994648269432'>], List[Tuple[Optional[<MagicMock name='mock.Tensor' id='139994648269432'>], ...]], List[Tuple[str, <MagicMock name='mock.Tensor' id='139994648269432'>]], List[Tuple[str, Tuple[Optional[<MagicMock name='mock.Tensor' id='139994648269432'>], ...]]]]¶

Process the transfer maps of the segment’s elements according to the specified method.

Note

This does not automatically compute the closed orbit first in order to use it as a starting value for d0. In that case, the closed orbit has to be provided manually in form of the parameter d0.

Parameters

method (str in {'accumulate', 'reduce', 'local'}) – If “accumulate” then the transfer maps are accumulated by contracting subsequent transfer maps. If “reduce” then the contracted transfer map for the complete segment is returned (this is identical to the last transfer map for “accumulate”). If “local” then the local transfer map of each element is computed, taking into consideration the value of the local closed orbit. The result contains the closed orbit at the exit of each element as the zeroth order coefficient.
order (int) – The order up to which transfer map coefficients (d, R, T) are taken into account for the contraction of two subsequent transfer maps.
indices (int or tuple of int) – Indicates the indices of the processed transfer maps which should be stored in the results. If a single number is given, all indices up to the specified number (inclusive) are considered. E.g. if indices = 0 and method = 'reduce' then the result will be just d where d is the orbit computed to second order but the resulting first and second order coefficients of the reduced transfer maps are discarded. Discarding coefficients of higher orders in the (intermediary) results can save memory and compute time. Note that max(indices) <= order must be fulfilled.
symplectify (bool) – Specifies whether the linear term (the transfer matrix) of lattice elements should be symplectified after the addition of second-order feed-down terms. This is only relevant for order >= 2.
labels (bool) – If True then the element’s labels are returned alongside their transfer maps as 2-tuples (for method = "reduce" this parameter is ignored). In case unfold_alignment_errors is True as well, an element’s label is repeated for each alignment error map (at entrance and exit), e.g. for an offset element “e1” it will be [..., ("e1", entrance_map), ("e1", element_map), ("e1", exit_map), ...].
unfold_alignment_errors (bool) – If True then the entrance and exit transformations of alignment errors are considered as separate transfer maps rather than being contracted with their wrapped element’s map. This increases the number of transfer maps as compared to the length of the segment.
d0 (Tensor, optional) – The value of the closed orbit at the beginning of the segment.
R0 (Tensor, optional) – Initial value for the first order terms.
T0 (Tensor, optional) – Initial value for the second order terms.

Returns

transfer_maps –

Depending on the value of method either of the following is returned:

”accumulate” – a list of the accumulated transfer maps along the lattice is returned.
”reduce” – the single transfer map, corresponding to the whole segment, is returned.
”local” – a list of the element-local transfer maps is returned.

Return type

TransferMap or list of TransferMap

update_transfer_maps(*, reset=False) → None¶: Update the transfer map of each element (see CompactElement.update_transfer_map()).