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 byelements.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 fortwiss
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 –