Package xal.tools.beam.calc

Class CalculationsOnRings

java.lang.Object
xal.tools.beam.calc.CalculationEngine
xal.tools.beam.calc.CalculationsOnMachines
xal.tools.beam.calc.CalculationsOnRings
All Implemented Interfaces:
ISimulationResults, ISimulationResults.ISimEnvResults<TransferMapState>, ISimulationResults.ISimLocResults<TransferMapState>
public class CalculationsOnRings extends CalculationsOnMachines

Class for computing ring parameters from simulation data. Accepts a TransferMapTrajectory as ring simulation data (from the online model) and computes the ring parameters from the transfer maps stored around the ring. Thus, the trajectory provided must be the end-to-end simulation results of the ring. The entrance of the first state in the trajectory and the exit of the last state in the trajectory will be treated as the same point, s = 0.

Do not supply partial simulations! Use the trajectory for the full ring unless it is your intent to create a sub-ring. That is, do not use the start element and stop element features of the online model unless you wish to simulate a smaller ring that excludes all elements before the stop element and all elements after the stop element. In such a case the entrance of the start element and the exit of the stop element would close the ring and be given the point s = 0.

The method names are those of interfaces ICoordinateState and IPhaseState to reflect their intent. However, they should be changed to something more descriptive once refactoring is finished. Preferably a method prefixed with calculate since the current naming scheme conflicts with Javabeans, specifically, the get prefix indicates a property of this class where in actuality it is a computation.

Do not hesitate to request new features and computations that could be provided by this class, it is by no means complete.

Since:
Oct 22, 2013
Author:
Christopher K. Allen

  • Constructor Details

    • CalculationsOnRings

      public CalculationsOnRings(Trajectory<TransferMapState> datSim)

      Constructor for CalculationsOnRings. The the ring is closed by identifying the first and last states in the provided trajectory.

      Parameters that are required for subsequent ring parameter calculations are computed, such as "entrance" position phase advance, "entrance" position fixed orbit, and "entrance" position matched envelope. By entrance position we imply the location s = 0, the location of ring closure. Once these quantities are computed we can propagate them to other ring locations as needed.

      For example, the transfer map of the last state in the trajectory is the full turn map of the ring at the entrance position. By conjugation with transfer map of any other state we can form the transfer map at that state location.

      Parameters:
      datSim - the simulation data for entire ring, a "transfer map trajectory" object
      Throws:
      IllegalArgumentException - the trajectory does not contain TransferMapState objects
      Since:
      Oct 22, 2013

  • Method Details

    • ringBetatronPhaseAdvance

      public R3 ringBetatronPhaseAdvance()

      Returns the betatron phase advances for the ring entrance (which are computed at instantiation). The returned value is the calculation CalculationEngine.calculatePhaseAdvPerCell(PhaseMatrix) given the full turn matrix at the ring entrance.

      NOTES:

      · The ring tunes and betatron phase advances differ by a factor 2π.
      · The entrance of the ring is assumed to be the location of the first and last states of the solution trajectory.

      Returns:
      vector particle betatron phase advances (in radians)
      Since:
      Oct 30, 2013

    • ringFixedOrbitPt

      public PhaseVector ringFixedOrbitPt()

      Returns the phase space location of the fixed orbit at the ring entrance (which is computed at instantiation). The returned value z is the result of the calculation CalculationEngine.calculateFixedPoint(PhaseMatrix) given the full turn matrix Φ at the ring entrance. It is invariant under the action of Φ, that is, Φz = z.

      NOTES:

      · The entrance of the ring is assumed to be the location of the first and last states of the solution trajectory.

      Returns:
      Since:
      Oct 30, 2013

    • ringMatchedTwiss

      public Twiss[] ringMatchedTwiss()

      Returns the matched Courant-Snyder parameters at the "entrance" of the ring. These are the envelopes taken from the "closed envelope" solution at the beginning of the ring, s = 0.

      Note that emittance ε is the parameter used to describe the extend of the actual beam (rather than the normalized size β), or "acceptance". Thus it cannot be computed here and NaN is returned instead.

      NOTES:

      · The entrance of the ring is assumed to be the location of the first and last states of the solution trajectory.

      Returns:
      array of Twiss parameter sets (α, β, NaN)
      Since:
      Oct 30, 2013

    • getOneTurnMap

      public PhaseMap getOneTurnMap()
      Returns the one-turn map Φ0 for the ring at the location s = 0.
      Returns:
      ring one-turn map at join location
      Since:
      Nov 4, 2014

    • computePhaseAdvanceBetween

      public R3 computePhaseAdvanceBetween(TransferMapState state1, TransferMapState state2)
      Computes the phase advances between the given state locations for each phase plane. This is done by computing the matched Twiss parameters at the two locations, along with the transfer matrix, then computing the phase advances σ using is its entries in the transfer matrix.
      Parameters:
      state1 - state defining the start location in the ring
      state2 - state defining the stop location in the ring
      Returns:
      phases advances (σx, σy, σz)
      Since:
      Nov 7, 2014

    • computeFractionalTunes

      public R3 computeFractionalTunes()

      Calculates the fractional phase tune for the ring from its one-turn matrix. The Courant-Snyder parameters of the machine (beam) must be invariant under the action of the one-turn matrix (this indicates a periodic focusing structure where the beam envelope is modulated by that structure) for the returned values to be accurate. One tune parameter is provided for each phase plane, i.e., (νx, νy, νz). The betatron phase advances for the ring are then given by (2πνx, 2πνy, 2πνz). Specifically, the above values are the sinusoidal phase that a particle advances after each completion of a ring traversal, modulo 2π (that is, we only take the fractional part).

      The basic computation is

          ν = (1/2π) cos-1[½ Tr Φαα] ,

      where Φαα is the 2×2 block diagonal of the the provided transfer matrix for the α phase plane, and Tr Φαα indicates the trace of matrix Φαα.

      Returns:
      vector of fractional tunes (νx, νy, νz)
      Since:
      Nov 4, 2014

    • computeFullTunes

      public R3 computeFullTunes()

      Calculates and returns the full tune around the ring including the integer portion. The tunes are computed for the start of the ring. The tune for each phase plane is returned in the 3-dimensional vector.

      The full tunes are computed by summing all the partial phase advances through each of the trajectory states (see CalculationEngine.calculatePhaseAdvance(PhaseMatrix, Twiss[], Twiss[])). Thus, the partial phase advance through each state must also be computed so this can be an expensive operation.

      Returns:
      the number n.ν for each phase plane where n is the integer portion and ν is the fractional phase advance.
      Since:
      Oct 24, 2013

    • computeRingFullTurnMatrixAt

      public PhaseMatrix computeRingFullTurnMatrixAt(TransferMapState state)
      Computes the one-turn matrix of the ring at the given state location. Let Sn be the given state object at location sn, and let Tn be the transfer matrix between locations s0 and sn , where s0 is the location of the full one-turn matrix Φ0 for this machine at position s = 0 (which is the beginning and the end of the trajectory object used to construct this class instance). Then the full turn matrix Φn for the machine at location sn is given by

          Φn = Tn ⋅ Φ0 ⋅ Tn-1 .

      That is, we conjugate the full transfer map for this machine by the transfer map for the given state.

      Parameters:
      state - state Sn identifying the position sn
      Returns:
      The one-turn matrix Φn of the ring at sn
      Since:
      Nov 4, 2014

    • computeRingTransferMatrix

      public PhaseMatrix computeRingTransferMatrix(TransferMapState state1, TransferMapState state2)

      Returns the transfer matrix Φ2,1 taking phase coordinates from state position S1 to state position S2 within the ring. This is the first-order portion of the ring's transfer map T2,1 between states S1 and S2 (see method CalculationsOnMachines.computeTransferMap(TransferMapState, TransferMapState)).

      Because of the ring topology, position s1 of state S1 and position s2 of state S2 are really equivalence classes of real numbers [s1] ⊂ R and [s2] ⊂ R, respectively. Each equivalence class can be represented

          [si ] = { si + nL | n ∈ Z+ }

      where L is the circumference of the ring. Because of the way the ring is represented as a data structure, we have s ∈ [0,L]. However, we must enforce the condition that s2 is always "down stream" of s1. Specifically, we do not reverse directions when computing the transfer matrix. Here we describe the calculations in practical detail.

      If while traveling downstream from position s1 we need to determine whether or not we pass the position s = 0 before we encounter the position s2. If so we to represent the position of state S2 as s2 + L ∈ [s2], since s2 < s1 indicating s2 is upstream of s1 (according to our model). This condition requires that we must include the ring full turn matrix Φ0 when computing the transfer matrix. Recall that Φ0 takes phase coordinates from position s = 0 to position s</i = 0 going all the way around the ring.

      Collecting all of the above, if < e m>s2 < s1 then we have a propagation through point s = 0 and we must include the full turn matrix according to

          Φ2,1 = Φ2Φ0Φ1-1 .

      If s2 > s1 then we can compute the transfer matrix Φ2,1 in the usual fashion

          Φ2,1 = Φ2Φ1-1 .

      Parameters:
      state1 - phase state S1 defining ring position s1
      state2 - phase state S2 defining ring position s2
      Returns:
      the transfer matrix Φ2,1 taking phase coordinates z from position s1 on the ring to position s2
      Since:
      Nov 3, 2014

    • computeRingTransferMap

      public PhaseMap computeRingTransferMap(TransferMapState state1, TransferMapState state2)

      Returns the transfer map T2,1 taking phase coordinates from state position S1 to state position S2 within the ring.

      Because of the ring topology, position s1 of state S1 and position s2 of state S2 are really equivalence classes of real numbers [s1] ⊂ R and [s2] ⊂ R, respectively. Each equivalence class can be represented

          [si ] = { si + nL | n ∈ Z+ }

      where L is the circumference of the ring. Because of the way the ring is represented as a data structure, we have s ∈ [0,L]. However, we must enforce the condition that s2 is always "down stream" of s1. Specifically, we do not reverse directions when computing the transfer map. Here we describe the calculations in practical detail.

      If while traveling downstream from position s1 we need to determine whether or not we pass the position s = 0 before we encounter the position s2. If so we to represent the position of state S2 as s2 + L ∈ [s2], since s2 < s1 indicating s2 is upstream of s1 (according to our model). This condition requires that we must include the ring full turn map T0 when computing the transfer map. Recall that T0 takes phase coordinates from position s = 0 to position s</i = 0 going all the way around the ring.

      Collecting all of the above, if s < s ub>2< /sub> < s1 then we have a propagation through point s = 0 and we must include the full turn map according to

          T2,1 = T2T0T1-1 .

      If s2 > s1 then we can compute the transfer map T2,1 in the usual fashion

          T2,1 = T2T1-1 .

      Parameters:
      state1 - phase state S1 defining ring position s1
      state2 - phase state S2 defining ring position s2
      Returns:
      the transfer map T2,1 taking phase coordinates z from position s1 on the ring to position s2
      Since:
      Nov 3, 2014

    • computeTurnByTurnResponse

      public PhaseVector[] computeTurnByTurnResponse(TransferMapState stateInj, TransferMapState stateObs, int cntTurns, PhaseVector vecInj)

      Computes and returns the turn-by-turn phase positions {zn ∈ R6 × {1} | n=0,...,N-1 } at the given location sobs of state Sobs resulting from a particle injected at location sinj ∈ Sinj with initial phase coordinates zinj.

      The coordinates zn are taken with respect to the ring's fixed point orbit p at location sobj. That is, each zn is a displacement from p in the global coordinate system.

      Currently the computation is entirely matrix based. Only transfer matrices are used and not transfer maps. Specifically, let Φ2,1 be the transfer matrix from s1 ≜ sinj to s2 ≜ sobs and let Φ2,2 be the one-turn map at position s2 in the ring. Then the returned array of phase vectors {zn } is given by

          zn = [Φ2,2]n Φ2,1 zinj .

      Note that z0 is Φ2,1 zinj , the phase coordinates of the particle after propagating from the injection location to the observation location.

      Parameters:
      stateInj - trajectory state at the injection location
      stateObs - trajectory state at the observation location
      cntTurns - number of turns N to observe particle
      vecInj - the initial phase coordinates in the ring global coordinate system
      Returns:
      an array of phase coordinates representing displacements from the fixed orbit
      Since:
      Nov 4, 2014

    • computeTurnByTurnRespWrtFixedOrbit

      public PhaseVector[] computeTurnByTurnRespWrtFixedOrbit(TransferMapState stateInj, TransferMapState stateObs, int cntTurns, PhaseVector vecInj)

      Computes and returns the turn-by-turn phase positions {zn ∈ R6 × {1} | n=0,...,N-1 } at the given location sobs of state Sobs resulting from a particle injected at location sinj ∈ Sinj with initial phase coordinates zinj.

      Currently the computation is entirely matrix based. Only transfer matrices are used and not transfer maps. Specifically, let Φ2,1 be the transfer matrix from s1 ≜ sinj to s2 ≜ sobs and let Φ2,2 be the one-turn map at position s2 in the ring. Then the returned array of phase vectors {zn } is given by

          zn = [Φ2,2]n Φ2,1 zinj .

      Note that z0 is Φ2,1 zinj , the phase coordinates of the particle after propagating from the injection location to the observation location.

      Parameters:
      stateInj - trajectory state at the injection location
      stateObs - trajectory state at the observation location
      cntTurns - number of turns N to observe particle
      vecInj - the initial phase coordinates w.r.t. to the fixed orbit location
      Returns:
      an array of phase coordinates representing displacements from the fixed orbit
      Since:
      Nov 4, 2014

    • computeMatchedTwissAt

      public Twiss[] computeMatchedTwissAt(TransferMapState state)

      Calculates the matched Courant-Snyder parameters for the given state location. The computed Twiss parameters are the matched envelopes for the ring at that point.

      Internally, the array of phase advances {σx, σy, σx} are assumed to be the particle phase advances through the ring for the matched solution. These are computed with the base class method CalculationEngine.calculatePhaseAdvPerCell(PhaseMatrix).

      The returned Courant-Snyder parameters (α, β, ε) are invariant under the action of the one-turn matrix at the state location, that is, they are matched. All that is required are α and β since ε specifies the size of the beam envelope. Consequently the returned ε is NaN.

      The following are the calculations used for the Courant-Snyder parameters of a single phase plane:

          α ≡ -ww' = (φ11 - φ22)/(2 sin σ) ,

          β ≡ w2 = φ12/sin σ

      where φij are the elements of the 2×2 diagonal blocks of the one-turn matrix Φ for the the particular phase plane. The particle amplitude function w is taken from Reiser, and σ is the phase advance through the cell for the particular phase plane.

      Parameters:
      state - state defining the location for computing the matched Twiss parameters
      Returns:
      matched Twiss parameters at the given state location
      Since:
      Nov 5, 2014