dipas.compute module

Convenience functions for computing various simulation related quantities.

class dipas.compute.InitialLatticeParameters(beta_x: Union[int, float, <MagicMock name='mock.Tensor' id='139745955357904'>], beta_y: Union[int, float, <MagicMock name='mock.Tensor' id='139745955357904'>], orbit: <MagicMock name='mock.Tensor' id='139745955357904'> = <factory>, x: dataclasses.InitVar = None, px: dataclasses.InitVar = None, y: dataclasses.InitVar = None, py: dataclasses.InitVar = None, t: dataclasses.InitVar = None, pt: dataclasses.InitVar = None, alpha_x: Union[int, float, <MagicMock name='mock.Tensor' id='139745955357904'>] = 0.0, alpha_y: Union[int, float, <MagicMock name='mock.Tensor' id='139745955357904'>] = 0.0, mu_x: Union[int, float, <MagicMock name='mock.Tensor' id='139745955357904'>] = 0.0, mu_y: Union[int, float, <MagicMock name='mock.Tensor' id='139745955357904'>] = 0.0, dispersion: <MagicMock name='mock.Tensor' id='139745955357904'> = <factory>, dx: dataclasses.InitVar = None, dpx: dataclasses.InitVar = None, dy: dataclasses.InitVar = None, dpy: dataclasses.InitVar = None)

Bases: object

alpha_x: Tensor' id='139745955357904'>] = 0.0
alpha_y: Tensor' id='139745955357904'>] = 0.0
beta_x: Tensor' id='139745955357904'>]
beta_y: Tensor' id='139745955357904'>]
dispersion: <MagicMock name='mock.Tensor' id='139745955357904'>
dpx: InitVar = None
dpy: InitVar = None
dx: InitVar = None
dy: InitVar = None
mu_x: Tensor' id='139745955357904'>] = 0.0
mu_y: Tensor' id='139745955357904'>] = 0.0
orbit: <MagicMock name='mock.Tensor' id='139745955357904'>
pt: InitVar = None
px: InitVar = None
py: InitVar = None
t: InitVar = None
x: InitVar = None
y: InitVar = None
dipas.compute.closed_orbit(lattice: ~dipas.elements.Segment, *, order: typing_extensions.Literal[1, 2] = 2, max_iter: ~typing.Optional[int] = None, tolerance: float = 1e-06, initial_guess: ~typing.Optional[<MagicMock name='mock.Tensor' id='139745955357904'>] = None, return_transfer_matrix: bool = False) Tensor' id='139745955357904'>]]

Closed orbit search for a given order on the given lattice.

The given lattice may contain Element`s as well as `AlignmentError`s. Alignment errors are treated as additional elements that wrap the actual element: entrance transformations coming before the element, in order, and exit transformations being placed after, in reverse order. The closed orbit search is a first-order iterative procedure with where each update :math:`x_{Delta} is computed as the solution of the following set of linear equations:

.. math:: \left[\mathbb{1} - R\right]\, x_{\Delta} = x_1 - x_0

where \(R\) is the one-turn transfer matrix and \(x_1\) is the orbit after one turn when starting from \(x_0\). \(R\) represents the Jacobian of the orbit w.r.t. itself.

Parameters
  • lattice (Segment) –

  • order (int) – Transfer maps used for tracking the closed orbit guess are truncated at the specified order (however the linear response R does contain second feed-down terms from T, if any).

  • max_iter (int, optional) – Maximum number of iterations.

  • tolerance (float, optional) – Maximum L1 distance between initial orbit and tracked orbit after one turn for convergence.

  • initial_guess (Tensor) – Initial guess for the closed orbit search; must be of shape (6,1).

  • return_transfer_matrix (bool, default = False) – If True then the one-turn transfer matrix is returned along the computed closed orbit as a tuple: x, R. Note that during the closed orbit search, after the deviation reached below the specified threshold, one additional update to the closed orbit x is performed but not to the transfer matrix R. For that reason the matrix R might deviate slightly from the matrix obtained by elements.process_transfer_maps() when using the returned orbit x.

Returns

  • closed_orbit (Tensor) – Tensor of shape (6,) containing the closed orbit in the transverse coordinates and zeros for the longitudinal coordinates.

  • one_turn_transfer_matrix (Tensor, optional) – Tensor of shape (6, 6) representing the one-turn transfer matrix. This is only returned if the argument for return_transfer_matrix is set to True.

Raises
  • ConvergenceError – If the closed orbit search did not converge within the specified number of iterations for the given tolerance.

  • DivergingOrbitError – If a component of the closed orbit estimate exceeds the ORBIT_DIVERGENCE_THRESHOLD during the closed orbit search (the absolute value of components are considered).

dipas.compute.linear_closed_orbit(lattice: Segment) <MagicMock name='mock.Tensor' id='139745955357904'>

Compute the linear closed orbit for the given lattice.

The given lattice may contain Element`s as well as `AlignmentError`s. Alignment errors are treated as additional elements that wrap the actual element: entrance transformations coming before the element, in order, and exit transformations being placed after, in reverse order. Hence all parts of the lattice can be described as a chain of linear transformations and the linear closed orbit is given as the solution to the following system of equations (in the transverse coordinates, for a total of :math:`n elements (actual elements and error transformations)):

\[\left[\mathbb{1} - \bar{R}_0\right]\, x_{co} = \sum_{i=1}^{n}\bar{R}_i\,d_i\]

where \(\bar{R}_i\) is given by:

\[\begin{split}\bar{R}_i \equiv \prod_{j=n\\j\rightarrow j-1}^{i+1}R_j\end{split}\]

and \(R_k, d_k\) are, respectively, the first and zero order term of the k-th element.

Parameters

lattice (Segment) –

Returns

linear_closed_orbit – Tensor of shape (6,) containing the closed orbit in the transverse coordinates and zeros for the longitudinal coordinates.

Return type

Tensor

dipas.compute.orm(lattice: Segment, *, kickers: Union[str, Pattern, Type[Union[CompactElement, PartitionedElement, Element, AlignmentError]], Sequence[Union[int, str, CompactElement, PartitionedElement, Element, AlignmentError, Tuple[Union[str, Pattern, Type[Union[CompactElement, PartitionedElement, Element, AlignmentError]]], int], Kicker]]], monitors: Union[str, Pattern, Type[Union[CompactElement, PartitionedElement, Element, AlignmentError]], Sequence[Union[int, str, CompactElement, PartitionedElement, Element, AlignmentError, Tuple[Union[str, Pattern, Type[Union[CompactElement, PartitionedElement, Element, AlignmentError]]], int], Monitor, BPMError]]], kicks: Tuple[float, float] = (-0.001, 0.001), order: typing_extensions.Literal[1, 2] = 2, co_args: Optional[dict] = None) ORMData

Compute the orbit response matrix (ORM) for the given lattice, kickers and monitors.

Parameters
  • lattice (Segment) –

  • kickers (MultiElementSelector or list of SingleElementSelector) – Can be an identifier for selecting multiple kickers, or a list of identifiers each selecting a single kicker or a list of Kicker elements directly.

  • monitors (MultiElementSelector or list of SingleElementSelector) – Can be an identifier for selecting multiple monitors, or a list of identifiers each selecting a single monitor or a list of Monitor elements directly.

  • kicks (2-tuple of float) – The kick strengths to be used for measuring the orbit response.

  • order (int) – See closed_orbit().

  • co_args (dict) – Additional arguments for the closed orbit search.

Returns

orm_x, orm_y – Shape len(monitors), len(kickers).

Return type

Tensor

dipas.compute.transfer_maps(lattice: Segment, *, method: typing_extensions.Literal[accumulate, reduce, local], order: typing_extensions.Literal[1, 2] = 2, indices: Optional[Union[typing_extensions.Literal[0, 1, 2], Tuple[typing_extensions.Literal[0, 1, 2], ...]]] = None, symplectify: bool = True, labels: bool = False, unfold_alignment_errors: bool = False) ]]]]

Compute the transfer maps of the lattice, performing a closed orbit search beforehand and using it as the starting value. For details see Segment.transfer_maps().

dipas.compute.twiss(lattice: Segment, *, order: typing_extensions.Literal[1, 2] = 2, co_args: Optional[Dict] = None, initial: Optional[InitialLatticeParameters] = None) Dict

Compute various lattice functions and parameters.

Note

Kicker`s must be sliced via :meth:`~Kicker.makethin beforehand in order for twiss to work.

Parameters
  • lattice (Segment) –

  • order (int) – Order of truncation for the transfer maps of lattice elements.

  • co_args (dict) – Keyword arguments for closed_orbit().

  • initial (InitialLatticeParameters) – Initial lattice parameters to be used instead of the values from the periodic solution. If this argument is provided the periodic solution won’t be computed; all values are taken from the initial specification.

Returns

twiss

Contains the following key-value pairs:
  • ”Q1” – first mode tune

  • ”Q2” – second mode tune

  • ”coupling_matrix” – the 2x2 coupling matrix

  • ”lattice” – a data frame with element labels as indices and the following columns:
    • ”x”, “y”, “px”, “py” – the values of the closed orbit.

    • ”bx”, “ax”, “mx”, “by”, “ay”, “my”, “dx”, “dpx”, “dy”, “dpy” – linear lattice functions beta and alpha as well as phase advance and dispersion for the two modes; the phase advance is given in units of [2*pi].

Return type

dict

Raises

UnstableLatticeError