dipas.compute module

Convenience functions for computing various simulation related quantities.

dipas.compute.orm(lattice: dipas.elements.Segment, *, kickers: Union[str, Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], Sequence[Union[int, str, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int]]]], monitors: Union[str, Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], Sequence[Union[int, str, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern, Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int]]]], kicks: Tuple[float, float] = (-0.001, 0.001), order: typing_extensions.Literal[1, 2][1, 2] = 2, co_args: Optional[dict] = None) → Tuple[<MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.Tensor' id='139994648269432'>]

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.

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

  • 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(kickers), len(monitors).

Return type

Tensor

dipas.compute.closed_orbit(lattice: dipas.elements.Segment, *, order: typing_extensions.Literal[1, 2][1, 2] = 2, max_iter: Optional[int] = None, tolerance: float = 1e-06, initial_guess: Optional[<MagicMock name='mock.Tensor' id='139994648269432'>] = None, return_transfer_matrix: bool = False) → Union[<MagicMock name='mock.Tensor' id='139994648269432'>, Tuple[<MagicMock name='mock.Tensor' id='139994648269432'>, <MagicMock name='mock.Tensor' id='139994648269432'>]]

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.

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

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.twiss(lattice: dipas.elements.Segment, *, order: typing_extensions.Literal[1, 2][1, 2] = 2, co_args: Optional[Dict] = None, initial: Optional[dipas.compute.InitialLatticeParameters] = None) → Dict

Compute various lattice functions and parameters.

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 –