public class CalculationsOnMachines extends CalculationEngine implements ISimulationResults.ISimLocResults<TransferMapState>, ISimulationResults.ISimEnvResults<TransferMapState>
ISimEnvResults interface in the context of
a particle beam system without regard to the particle.
That is, only properties of the machine are computed, no
attributes or properties of the beam are required for the
computations.ISimulationResults.ISimEnvResults<S>, ISimulationResults.ISimLocResults<S>| Constructor and Description |
|---|
CalculationsOnMachines(Trajectory<TransferMapState> datSim)
Constructor for
CalculationsOnMachines. |
| Modifier and Type | Method and Description |
|---|---|
protected PhaseMatrix |
calculateFullLatticeMatrixAt(TransferMapState state)
Calculates and returns the full lattice matrix for the machine at the
given state location.
|
R3 |
computeBetatronPhase(TransferMapState state)
This is the phase advance for the given state location.
|
PhaseVector |
computeChromAberration(TransferMapState state)
Computes the chromatic aberration for one pass around the ring starting at the given
state location, or from the entrance to state position for a linear
machine.
|
PhaseVector |
computeChromDispersion(TransferMapState state)
Calculates the fixed point (closed orbit) in transverse phase space
at the given state location in the presence of dispersion.
|
PhaseVector |
computeCoordinatePosition(TransferMapState state)
We return the projective portion of the full-turn transfer
map φn : P6 → P6
where n is the index of the given state Sn.
|
PhaseVector |
computeFixedOrbit(TransferMapState state)
Get the fixed point at this state location about which betatron oscillations occur.
|
static PhaseMap |
computeTransferMap(TransferMapState state1,
TransferMapState state2)
Convenience method for computing the transfer map between two state locations, say S1
and S2.
|
PhaseMatrix |
computeTransferMatrix(java.lang.String strIdElemFrom,
java.lang.String strIdElemTo)
Returns the state response matrix calculated from the front face of
elemFrom to the back face of elemTo.
|
static PhaseMatrix |
computeTransferMatrix(TransferMapState state1,
TransferMapState state2)
Convenience method for computing the transfer matrix between two state locations, say S1
and S2.
|
Twiss[] |
computeTwissParameters(TransferMapState state)
Computes the closed orbit Twiss parameters at this state location representing
the matched beam envelope when treating the trajectory as a lattice of
periodic cells.
|
PhaseMap |
getFullTransferMap()
Returns the transfer map of the full machine lattice represented by the
associated simulation trajectory.
|
Twiss[] |
getMatchedTwiss()
Returns the collection of matched Courant-Snyder parameters for each phase
plane.
|
Trajectory<TransferMapState> |
getTrajectory()
Returns the simulation trajectory from which all the machine properties are
computed.
|
calculateAberration, calculateDispersion, calculateFixedPoint, calculateMatchedTwiss, calculatePhaseAdvance_old, calculatePhaseAdvance, calculatePhaseAdvPerCell, calculateTunePerCell, computeTwisspublic CalculationsOnMachines(Trajectory<TransferMapState> datSim) throws java.lang.IllegalArgumentException
Constructor for CalculationsOnMachines. Accepts the
TransferMapTrajectory
object and extracts the final state and full trajectory transfer map.
Quantities that are
required for subsequent machine property calculations are also computed, such as
phase advance through the trajectory (modulo 2π), entrance position
"fixed orbit" (that is, the orbit that is invariant for repeated applications of the
linear part of the transfer map (separating the projective part),
and the matched envelope when treating the full transfer map as the map
for a periodic cell.
datSim - the simulation data for the ring, a "transfer map trajectory" objectjava.lang.IllegalArgumentException - the trajectory does not contain TransferMapState objectspublic static PhaseMatrix computeTransferMatrix(TransferMapState state1, TransferMapState state2)
state1 - trajectory state S1 of starting location s1state2 - trajectory state S2 of final location s2public static PhaseMap computeTransferMap(TransferMapState state1, TransferMapState state2)
state1 - trajectory state S1 of starting location s1state2 - trajectory state S2 of final location s2public Trajectory<TransferMapState> getTrajectory()
public PhaseMap getFullTransferMap()
public Twiss[] getMatchedTwiss()
Returns the collection of matched Courant-Snyder parameters for each phase plane. The Courant-Snyder parameters describe the matched beam envelopes when treating the trajectory of transfer maps as that for a periodic lattice. There the beam envelopes would have the same characteristics at the beginning and end of the lattice.
These are computed parameters calculated once at construction time.
public PhaseMatrix computeTransferMatrix(java.lang.String strIdElemFrom, java.lang.String strIdElemTo)
Returns the state response matrix calculated from the front face of elemFrom to the back face of elemTo. This is a convenience wrapper to the real method in the trajectory class
This method was moved here from EnvelopeTrajectory/EnvelopeProbe where
it was eliminated since Trajectory was genericized.
strIdElemFrom - String identifying starting lattice elementstrIdElemTo - String identifying ending lattice elementEnvelopeTrajectory#computeTransferMatrix(String, String)public PhaseVector computeCoordinatePosition(TransferMapState state)
We return the projective portion of the full-turn transfer map φn : P6 → P6 where n is the index of the given state Sn. This is the image Δz of the value 0 ∈ P6 ≅ R6 × {1}. That is the value Δz = φn(0).
Recall that the transfer
map φ is a PhaseMap object containing a first-order component which is
a linear operator on projective space P6. As such, this
PhaseMatrix object Φ is embedded in R7×7.
The 7th column Δz of Φ is the column of
translation operations on a phase vector
z ∈ P6 ⊂ R6 × {1} since
z ∈ P6 is represented
z = (x, x', y, y', z, z', 1)T .
Thus, the action of Φ can be (loosely) decomposed as
Φ ⋅ z = Mz + Δz ,
where M ∈ Sp(6), the symplectic group. This method returns the
component Δz of the transfer map.
computeCoordinatePosition in interface ISimulationResults.ISimLocResults<TransferMapState>state - state containing location of returned translation vectorpublic PhaseVector computeFixedOrbit(TransferMapState state)
Get the fixed point at this state location about which betatron oscillations occur.
Calculate the fixed point solution vector representing the closed orbit at the
location of this element.
We first attempt to find the fixed point for the full six phase space coordinates.
Let Φ denote the one-turn map for a ring. The fixed point
z ∈ R6×{1} in homogeneous phase space coordinates
is that which is invariant under Φ, that is,
Φz = z .
This method returns that vector z.
Recall that the homogeneous transfer matrix Φ for the ring
has final row that represents the translation Δ of the particle
for the circuit around the ring. The 6×6 sub-matrix of Φ represents
the (linear) action of the bending magnetics and quadrupoles and corresponds to the
matrix T ∈ R6×6 (here T is linear).
Thus, we can write the linear operator Φ
as the augmented system
Φ = |T Δ |, z ≡ |p| ,
|0 1 | |1|
where p is the projection of z onto the ambient phase space
R6 (without homogeneous the homogeneous coordinate).
Putting this together we get
Φz = Tp + Δ = p ,
to which the solution is
p = -(T - I)-1Δ
assuming it exists. The question of solution existence falls upon the
resolvent R ≡ (T - I)-1 of T.
By inspection we can see that p is defined so long as the eigenvalues
of T are located away from 1.
In this case the returned value is the augmented vector
(p 1)T ∈ R6 × {1}.
When the set of eigenvectors does contain 1, we attempt to find the solution for the transverse phase space. That is, we take vector p ∈ R4 and T ∈ R4×4 where T = proj4×4 Φ. The returned value is then z = (p 0 0 1)T.
computeFixedOrbit in interface ISimulationResults.ISimLocResults<TransferMapState>state - state containing transfer map and location used in these calculationspublic PhaseVector computeChromAberration(TransferMapState state)
ISimLocResults#computeChromAberration(ProbeState) for a more detailed
exposition.computeChromAberration in interface ISimulationResults.ISimLocResults<TransferMapState>state - simulation state where parameters are computedxal.tools.beam.calc.ISimLocResults#computeChromAberration(xal.model.probe.traj.ProbeState)public Twiss[] computeTwissParameters(TransferMapState state)
Computes the closed orbit Twiss parameters at this state location representing the matched beam envelope when treating the trajectory as a lattice of periodic cells.
Returns the array of twiss objects for this state for all three planes.
Calculates the matched Courant-Snyder parameters for the given period cell transfer matrix and phase advances. When the given transfer matrix is the full-turn matrix for a ring the computed Twiss parameters are the matched envelopes for the ring at that point.
Let Φ denote the transfer matrix from the machine beginning to the given
state location (it is contained in the given state).
It is assumed to be the transfer matrix through
at least one cell in a periodic lattice. Internally, the array of phase advances
{σx, σy, σx}
are assumed to be the particle phase advances through the cell for the matched
solution. These are computed with the method
CalculationEngine.calculatePhaseAdvPerCell(PhaseMatrix)
The returned Courant-Snyder parameters (α, β, ε) are invariant
under the action of the given phase matrix, that is, they are matched. All that
is require are α and β since ε specifies the size of the beam
envelope. Consequently the returned ε is NaN.
computeTwissParameters in interface ISimulationResults.ISimEnvResults<TransferMapState>state - state containing transfer map and location used in these calculationspublic R3 computeBetatronPhase(TransferMapState state)
This is the phase advance for the given state location.
Compute and return the particle phase advance from the trajectory beginning to the given state location.
Internally the method calculates the phase advances using the initial and final Courant-Snyder α and β values for the matched beam at the trajectory beginning and the location of the given state, respectively. These Courant-Snyder parameters are computed as the matched beam envelope at the trajectory beginning and the given state location.
Let Φ represent the transfer matrix from the initial ring location to the given state location. The computed quantity is the general phase advance of the particle through the transfer matrix Φ, and no special requirements are placed upon Φ (e.g., periodicity). One phase advance is provided for each phase plane, i.e., (σx, σz, σz).
The definition of phase advance σ is given by
σ(s) ≡ ∫s [1/β(t)]dt ,
where β(s) is the Courant-Snyder, envelope function, and the integral
is taken along the interval between the initial and final Courant-Snyder
parameters.
The basic relation used to compute σ is the following:
σ = sin-1 φ12/(β1β2)½ ,
where φ12 is the element of Φ in the upper right corner of each
2×2 diagonal block, β1 is the initial beta function value (provided)
and β2 is the final beta function value (provided).
computeBetatronPhase in interface ISimulationResults.ISimEnvResults<TransferMapState>state - state containing transfer map and location used in these calculationsCalculationEngine.calculatePhaseAdvance(PhaseMatrix, Twiss[], Twiss[])public PhaseVector computeChromDispersion(TransferMapState state)
Calculates the fixed point (closed orbit) in transverse phase space at the given state location in the presence of dispersion.
Let the full-turn map a the state location be denoted Φ.
The transverse plane dispersion vector Δ is defined
Δt ≡ -(1/γ2)[dx/dz', dx'/dz', dy/dz', dy'/dz']T .
It can be identified as the first 4 entries of the 6th
column in the transfer matrix Φ. The above vector
quantifies the change in the transverse particle phase
coordinate position versus the change in particle momentum.
The factor -(1/γ2) is needed to convert from longitudinal divergence
angle z' used by XAL to momentum δp ≡ Δp/p used in
the dispersion definition. Specifically,
δp ≡ Δp/p = γ2z'
As such, the above vector can be better described
Δt ≡ [Δx/δp, Δx'/δp, Δy/δp, Δy'/δp]T
explicitly describing the change in transverse phase coordinate for fractional
change in momentum δp.
Since we are only concerned with transverse phase space coordinates, we restrict ourselves to the 4×4 upper diagonal block of Φ, which we denote take T. That is, T = π ⋅ Φ where π : R6×6 → R4×4 is the projection operator.
This method finds that point zt ≡
(xt, x't, yt, y't)
in transvse phase space that is invariant under the action of the ring for a given momentum spread
δp. That is, the particle ends up
in the same location each revolution. With a finite momentum spread of δp > 0
we require this require that
Tzt + δpΔt = zt ,
which can be written
zt = δp(T - I)-1Δt ,
where I is the identity matrix. Dividing both sides by δp yields the final
result
z0 ≡ zt/δp = (T - I)-1Δt ,
which is the returned value of this method. It is normalized by
δp so that we can compute the closed orbit for any given momentum spread.
computeChromDispersion in interface ISimulationResults.ISimEnvResults<TransferMapState>state - we are calculating the dispersion at this state locationxal.tools.beam.calc.ISimEnvResults#computeChromDispersion(xal.model.probe.traj.ProbeState)protected PhaseMatrix calculateFullLatticeMatrixAt(TransferMapState state)
Calculates and returns the full lattice matrix for the machine 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 transfer matrix
Φ0 for this machine (end to end). 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.
state - state object Sn for location sn
containing transfer matrix Tn