at.physics.orbit#

Closed orbit related functions

Functions

find_orbit4(ring[, dp, refpts, dct, df, ...])

Gets the 4D closed orbit for a given dp

find_sync_orbit(ring[, dct, refpts, dp, df, ...])

Gets the 4D closed orbit for a given dct

find_orbit6(ring[, refpts, orbit, keep_lattice])

Gets the closed orbit in the full 6-D phase space

find_orbit(ring[, refpts])

Gets the closed orbit in the general case
find_orbit(ring, refpts=None, **kwargs)[source]#

Gets the closed orbit in the general case

Depending on the lattice, find_orbit() will:

Parameters:
Keyword Arguments:

  • orbit (Orbit) – Avoids looking for initial the closed orbit if it is already known. find_orbit() propagates it to the specified refpts.

  • dp (float) – Momentum deviation. Defaults to None

  • dct (float) – Path lengthening. Defaults to None

  • df (float) – Deviation from the nominal RF frequency. Defaults to None

  • guess (Orbit) – (6,) initial value for the closed orbit. It may help convergence. Default: (0, 0, 0, 0, 0, 0)

  • convergence (float) – Convergence criterion. Default: DConstant.OrbConvergence

  • max_iterations (int) – Maximum number of iterations. Default: DConstant.OrbMaxIter

  • XYStep (float) – Step size. Default: DConstant.XYStep

  • DPStep (float) – Momentum step size. Default: DConstant.DPStep

For other keywords, refer to the underlying methods

Returns:

  • orbit0 – (6,) closed orbit vector at the entrance of the 1-st element (x,px,y,py,dp,0)

  • orbit – (Nrefs, 6) closed orbit vector at each location specified in refpts

See also

find_orbit4(), find_sync_orbit(), find_orbit6()

find_orbit4(ring, dp=None, refpts=None, *, dct=None, df=None, orbit=None, keep_lattice=False, **kwargs)[source]#

Gets the 4D closed orbit for a given dp

Finds the closed orbit in the 4-d transverse phase space by numerically solving for a fixed point of the one turn map M calculated with internal_lpass().

\[\begin{split}\begin{pmatrix}x \\ p_x \\ y \\ p_y \\ dp \\ c\tau_2\end{pmatrix} =\mathbf{M} \cdot \begin{pmatrix}x \\ p_x \\ y \\ p_y \\ dp \\ c\tau_1\end{pmatrix}\end{split}\]

under the CONSTANT MOMENTUM constraint dp and with NO constraint on the 6-th coordinate \(c\tau\)

Important

find_orbit4() imposes a constraint on dp and relaxes the constraint on the revolution frequency. A physical storage ring does exactly the opposite: the momentum deviation of a particle on the closed orbit settles at the value such that the revolution is synchronous with the RF cavity: \(f_{RF} = h*f_{rev}\)

To impose this artificial constraint in find_orbit4(), the PassMethod used for any element SHOULD NOT:

  1. Change the longitudinal momentum dp (cavities , magnets with radiation)

  2. Have any time dependence (localized impedance, fast kickers etc)

Parameters:

  • ring (Lattice) – Lattice description (is_6d must be False)

  • dp (float | None) – Momentum deviation. Defaults to 0

  • refpts (Type[Element] | Element | Callable[[Element], bool] | str | None | int | Sequence[int] | bool | Sequence[bool] | RefptsCode) – Observation points. See “Selecting elements in a lattice”

  • dct (float | None) – Path lengthening. If specified, dp is ignored and the off-momentum is deduced from the path lengthening.

  • df (float | None) – Deviation from the nominal RF frequency. If specified, dp is ignored and the off-momentum is deduced from the frequency deviation.

  • orbit (ndarray | None) – Avoids looking for initial the closed orbit if it is already known ((6,) array). find_orbit4() propagates it to the specified refpts.

  • keep_lattice (bool) – Assume no lattice change since the previous tracking. Default: False

Keyword Arguments:
Returns:

  • orbit0 – (6,) closed orbit vector at the entrance of the 1-st element (x,px,y,py,dp,0)

  • orbit – (Nrefs, 6) closed orbit vector at each location specified in refpts

See also

find_sync_orbit(), find_orbit6()

find_orbit6(ring, refpts=None, *, orbit=None, keep_lattice=False, **kwargs)[source]#

Gets the closed orbit in the full 6-D phase space

Finds the closed orbit in the full 6-D phase space by numerically solving for a fixed point of the one turn map M calculated with internal_lpass()

\[\begin{split}\begin{pmatrix}x \\ p_x \\ y \\ p_y \\ dp \\ c\tau_2\end{pmatrix} =\mathbf{M} \cdot \begin{pmatrix}x \\ p_x \\ y \\ p_y \\ dp \\ c\tau_1\end{pmatrix}\end{split}\]

with constraint \(c\tau_2 - c\tau_1 = c.h (1/f_{RF} - 1/f_{RF_0})\)

Important

find_orbit6() is a realistic simulation:

  1. The requency in the RF cavities \(f_{RF}\) (may be different from \(f_{RF_0}\)) imposes the synchronous condition \(c\tau_2 - c\tau_1 = c.h (1/f_{RF} - 1/f_{RF_0})\),

  2. The algorithm numerically calculates the 6-by-6 Jacobian matrix J6. In order for (J-E) matrix to be non-singular it is NECESSARY to use a realistic PassMethod for cavities with non-zero momentum kick (such as RFCavityPass).

  3. find_orbit6() can find orbits with radiation. In order for the solution to exist the cavity must supply an adequate energy compensation. In the simplest case of a single cavity, it must have Voltage set so that \(V > E_{loss}\), the energy loss per turn

  4. There is a family of solutions that correspond to different RF buckets They differ in the 6-th coordinate by \(c*Nb/f_{RF}\), Nb = 0:h-1

  5. The value of the 6-th coordinate found at the cavity gives the equilibrium RF phase. If there is no radiation it is 0.

  6. dp, dct and df arguments are applied with respect to the NOMINAL on-momentum frequency. They overwrite exisiting frequency offsets

Parameters:
Keyword Arguments:
Returns:

  • orbit0 – (6,) closed orbit vector at the entrance of the 1-st element (x,px,y,py,dp,0)

  • orbit – (Nrefs, 6) closed orbit vector at each location specified in refpts

See also

find_orbit4(), find_sync_orbit()

find_sync_orbit(ring, dct=None, refpts=None, *, dp=None, df=None, orbit=None, keep_lattice=False, **kwargs)[source]#

Gets the 4D closed orbit for a given dct

Finds the closed orbit, synchronous with the RF cavity (first 5 components of the phase space vector) by numerically solving for a fixed point of the one turn map M calculated with internal_lpass()

\[\begin{split}\begin{pmatrix}x \\ p_x \\ y \\ p_y \\ dp \\ c\tau_1+ dc\tau\end{pmatrix} =\mathbf{M} \cdot \begin{pmatrix}x \\ p_x \\ y \\ p_y \\ dp \\ c\tau_1\end{pmatrix}\end{split}\]

under the constraint \(dc\tau = c\tau_2 - c\tau_1 = c/f_{rev} - c/f_{rev_0}\), where \(f_{rev_0} = f_{RF_0}/h\) is the design revolution frequency and \(f_{rev} = (f_{RF_0} + df_{RF})/h\) is the imposed revolution frequency.

Important

find_sync_orbit() imposes a constraint \(c\tau_2 - c\tau_1\) and \(dp_2 = dp_1\) but no constraint on the value of \(dp_2\) or \(dp_1\). The algorithm assumes time-independent fixed-momentum ring to reduce the dimensionality of the problem.

To impose this artificial constraint in find_sync_orbit(), the PassMethod used for any element SHOULD NOT:

  1. Change the longitudinal momentum dp (cavities , magnets with radiation)

  2. Have any time dependence (localized impedance, fast kickers etc)

Parameters:
Keyword Arguments:
Returns:

  • orbit0 – (6,) closed orbit vector at the entrance of the 1-st element (x,px,y,py,dp,0)

  • orbit – (Nrefs, 6) closed orbit vector at each location specified in refpts

See also

find_orbit4(), find_orbit6()