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.
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.
ISimulationResults.ISimEnvResults<S>, ISimulationResults.ISimLocResults<S>| Constructor and Description |
|---|
CalculationsOnRings(Trajectory<TransferMapState> datSim)
Constructor for CalculationsOnRings.
|
| Modifier and Type | Method and Description |
|---|---|
R3 |
computeFractionalTunes()
Calculates the fractional phase tune for the ring from its one-turn matrix.
|
R3 |
computeFullTunes()
Calculates and returns the full tune around the ring including the integer portion.
|
Twiss[] |
computeMatchedTwissAt(TransferMapState state)
Calculates the matched Courant-Snyder parameters for the given
state location.
|
R3 |
computePhaseAdvanceBetween(TransferMapState state1,
TransferMapState state2)
Computes the phase advances between the given state locations for each phase plane.
|
PhaseMatrix |
computeRingFullTurnMatrixAt(TransferMapState state)
Computes the one-turn matrix of the ring at the given state location.
|
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.
|
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.
|
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.
|
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.
|
PhaseMap |
getOneTurnMap()
Returns the one-turn map Φ0 for the ring at the location
s = 0.
|
R3 |
ringBetatronPhaseAdvance()
Returns the betatron phase advances for the ring entrance (which are computed
at instantiation).
|
PhaseVector |
ringFixedOrbitPt()
Returns the phase space location of the fixed orbit at the ring entrance
(which is computed at instantiation).
|
Twiss[] |
ringMatchedTwiss()
Returns the matched Courant-Snyder parameters at the "entrance" of the ring.
|
calculateFullLatticeMatrixAt, computeBetatronPhase, computeChromAberration, computeChromDispersion, computeCoordinatePosition, computeFixedOrbit, computeTransferMap, computeTransferMatrix, computeTransferMatrix, computeTwissParameters, getFullTransferMap, getMatchedTwiss, getTrajectorycalculateAberration, calculateDispersion, calculateFixedPoint, calculateMatchedTwiss, calculatePhaseAdvance_old, calculatePhaseAdvance, calculatePhaseAdvPerCell, calculateTunePerCell, computeTwisspublic 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.
trjSimFull - the simulation data for entire ring, a "transfer map trajectory" objectjava.lang.IllegalArgumentException - the trajectory does not contain TransferMapState objectspublic 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)
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)
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.
public PhaseMap getOneTurnMap()
public R3 computePhaseAdvanceBetween(TransferMapState state1, TransferMapState state2)
state1 - state defining the start location in the ringstate2 - state defining the stop location in the ringpublic 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
Φαα.
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[])
public PhaseMatrix computeRingFullTurnMatrixAt(TransferMapState state)
state - state Sn identifying the position snpublic 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
Collecting all of the above, if 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 .
state1 - phase state S1 defining ring position s1state2 - phase state S2 defining ring position s2public 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
Collecting all of the above, if s2 < 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 .
state1 - phase state S1 defining ring position s1state2 - phase state S2 defining ring position s2public 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.
stateInj - trajectory state at the injection locationstateObs - trajectory state at the observation locationcntTurns - number of turns N to observe particlevecInj - the initial phase coordinates in the ring global coordinate systempublic 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.
stateInj - trajectory state at the injection locationstateObs - trajectory state at the observation locationcntTurns - number of turns N to observe particlevecInj - the initial phase coordinates w.r.t. to the fixed orbit locationpublic 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.
state - state defining the location for computing the matched Twiss parameters