Package xal.tools.beam.calc

Class CalculationEngine

java.lang.Object

xal.tools.beam.calc.CalculationEngine

Direct Known Subclasses:

CalculationsOnBeams, CalculationsOnMachines, CalculationsOnParticles

public abstract class CalculationEngine
extends Object

Class CalculationEngine performs all the common numerical calculation when computing machine parameters from simulation data. There are common data produced by ring simulations and linac simulation, however, the interpretation is different. It is up to the child classes to interpret the results of these calculations.

Since:

Aug 14, 2013

Author:

Christopher K. Allen, Patrick Scruggs

Constructor Summary

Constructors

Constructor	Description
CalculationEngine()

Method Summary

Modifier and Type	Method	Description
protected R6	calculateAberration(PhaseMatrix matPhi, double dblGamma)	Convenience function for returning the chromatic aberration coefficients.
protected R4	calculateDispersion(PhaseMatrix matPhi, double dblGamma)	Taken from TransferMapState.
protected PhaseVector	calculateFixedPoint(PhaseMatrix matPhi)	Taken from TransferMapState.
protected Twiss[]	calculateMatchedTwiss(PhaseMatrix matPhiCell)	Taken from TransferMapState.
protected R3	calculatePhaseAdvance(PhaseMatrix matPhi, Twiss[] twsInit, Twiss[] twsFinal)	Taken from TransferMapState.
protected R3	calculatePhaseAdvPerCell(PhaseMatrix matPhiCell)	Taken from TransferMapTrajectory.
protected R3	calculateTunePerCell(PhaseMatrix matPhiCell)	Taken from TransferMapTrajectory.
protected Twiss3D	computeTwiss(TwissProbe probe, PhaseMatrix matPhi, double dW)	Deprecated. This is the algorithm component for a TwissProbe and should not be used as the dynamics elsewhere.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CalculationEngine

public CalculationEngine()

Method Details

calculateFixedPoint

protected PhaseVector calculateFixedPoint(PhaseMatrix matPhi)

Taken from TransferMapState.

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 ∈ R⁶×{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 ∈ R^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 R⁶ (without homogeneous the homogeneous coordinate). coordinates).

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 ∈ R⁶ × {1}.

When the eigenvectors do contain 1, we attempt to find the solution for the transverse phase space. That is, we take vector p ∈ R⁴ and T ∈ R^4×4 where T = proj_4×4 Φ. The returned value is then z = (p 0 0 1)^T.

Parameters:

matPhi - the one-turn transfer matrix (full-turn matrix)

Returns:

fixed point solution for the given phase matrix

Since:

Aug 14, 2013

calculatePhaseAdvPerCell

protected R3 calculatePhaseAdvPerCell(PhaseMatrix matPhiCell)

Taken from TransferMapTrajectory.

Calculates the phase advance for the given transfer map assuming periodicity, that is, the given matrix represents the transfer matrix Φ of at least one cell in a periodic structure. The Courant-Snyder parameters of the machine (beam) must be invariant under the action of the transfer matrix (this indicates a periodic focusing structure where the beam envelope is modulated by that structure). One phase advance is provided for each phase plane, i.e., (σ_x, σ_z, σ_z). In the case the given map is the transfer map for one cell in a periodic lattice, in that case the returned value is the phase advance per cell, σ_cell of the periodic system.

When the given map is the full turn map of a ring then the phase advances are the betatron phases for the ring. Specifically, the sinusoidal phase that the particles advance after each completion of a ring traversal, modulo 2π (that is, we only take the fractional part).

The basic computation is

σ = 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 Φ_αα.

Parameters:

matPhiCell - transfer matrix for a cell in a periodic structure

Returns:

vector of phase advances (σ_x, σ_y, σ_z)

Since:

Aug 14, 2013

calculateTunePerCell

protected R3 calculateTunePerCell(PhaseMatrix matPhiCell)

Taken from TransferMapTrajectory.

Calculates the fractional tunes for the given transfer map assuming periodicity. That is, the Courant-Snyder parameters of the machine (beam) must be invariant under the action of the transfer matrix (this indicates a periodic focusing structure where the beam envelope is modulated by that structure). One tune is provided for each phase plane, i.e., (ν_x, ν_z, ν_z). The given map must in the least be the transfer map for one cell in a periodic lattice. In that case the returned value is the fractional phase advance per cell, σ_cell/2π of the periodic system.

When the given map is the full turn map of a ring then the tunes are the betatron tunes for the ring. Specifically, the fraction of a cycle that the particles advance after each completion of a ring traversal, modulo 1 (that is, we only take the fractional part).

The basic computation is

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

where Φ is the 2×2 diagonal block of the transfer matrix corresponding to the phase plane of interest.

The calculations are actually done by the method calculatePhaseAdvPerCell(PhaseMatrix) then normalized by 2π.

Parameters:

matPhiCell - transfer matrix for a cell in a periodic structure

Returns:

the array of betatron tunes (ν_x, ν_y, ν_z)

Since:

Aug 14, 2013

calculatePhaseAdvance

protected R3 calculatePhaseAdvance(PhaseMatrix matPhi,
 Twiss[] twsInit,
 Twiss[] twsFinal)

Taken from TransferMapState.

Compute and return the particle phase advance for under the action of the given phase matrix when used as a transfer matrix.

Calculates the phase advances given the initial and final Courant-Snyder α and β values provided. This is the general phase advance of the particle through the transfer matrix Φ, and no special requirements are placed upon Φ. 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 φ₁₂/(β₁β₂)^½ ,

where φ₁₂ is the element of Φ in the upper right corner of each 2×2 diagonal block, β₁ is the initial beta function value (provided) and β₂ is the final beta function value (provided).

Parameters:

matPhi - the transfer matrix that propagated the Twiss parameters

twsInit - initial Twiss parameter before application of matrix

twsFinal - final Twiss parameter after application of matrix

Returns:

the array of betatron tunes (σ_x, σ_z, σ_z)

Since:

Jun, 2004

calculateMatchedTwiss

protected Twiss[] calculateMatchedTwiss(PhaseMatrix matPhiCell)

Taken from TransferMapState.

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.

The given matrix Φ 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 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 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' = (φ₁₁ - φ₂₂)/(2 sin σ) ,

β ≡ w² = φ₁₂/sin σ

where φ_ij are the elements of the 2×2 diagonal blocks of Φ corresponding the the particular phase plane, the function w is taken from Reiser, and σ is the phase advance through the cell for the particular phase plance.

Parameters:

matPhiCell - transfer matrix Φ for a periodic cell (or full turn)

Returns:

array of matched Courant-Snyder parameters (α_cell, β_cell, NaN) for each phase plane

Since:

Jun 2004

calculateAberration

protected R6 calculateAberration(PhaseMatrix matPhi,
 double dblGamma)

Convenience function for returning the chromatic aberration coefficients.

For example, in the horizontal phase plane (x,x') these coefficients specify the change in position Δx and the change in divergence angle Δx' due to chromatic dispersion δ within the beam, or

Δx = (dx/dδ) ⋅ δ ,

Δx' = (dx'/dδ) ⋅ δ .

That is, (dx/dδ) and (dx'/dδ) are the dispersion coefficients for the horizontal plane position and horizontal plane divergence angle, respectively. The vector returned by this method contains all the analogous coefficients for all the phase planes.

The chromatic dispersion coefficient vector Δ can be built from the 6^th column of the state response matrix Φ. However we must pay close attention to the transverse plane quantities. Specifically, consider again the horizontal phase plane (x,x'). Denoting the elements of Φ in the 6^th column (i.e., the z' column) corresponding to this positions as φ_1,6 and φ_2,6, we can write them as

φ_1,6 = ∂x/∂z' ,

φ_2,6 = ∂x'/∂z' .

Now consider the relationship

δ ≡ (p - p₀)/p₀ = γ²z'= γ²dz/ds

or

∂z'/∂δ = 1/γ² .

Thus, it is necessary to multiply the transfer plane elements of Row₆Φ by 1/γ² to covert to the conventional dispersion coefficients. Specifically, for the horizontal plane

Δ_x = (dx/dδ) = φ_6,1/γ² ,

Δ_x' = (dx'/dδ) = φ_6,2/γ² ,

For the longitudinal plane no such normalization is necessary.

NOTE:

- Reference text D.C. Carey, "The Optics of Charged Particle Beams"

Parameters:

matPhi - transfer matrix for which we are computing aberrations

dblGamma - relativistic factor for the beam particles at the location of aberration

Returns:

vector of chromatic dispersion coefficients in meters/radian

Since:

Nov 15, 2013

calculateDispersion

protected R4 calculateDispersion(PhaseMatrix matPhi,
 double dblGamma)

Taken from TransferMapState.

Calculates the differential coefficients describing change in the fixed point of the closed orbit versus chromatic dispersion. The given transfer matrix Φ is assumed to be the one-turn map of the ring with which the fixed point is caculated. The fixed point is with regard to the transverse phase plane coordinates.

The transverse plane dispersion vector Δ is defined

Δ_t ≡ -(1/γ²)[dx/dz', dx'/dz', dy/dz', dy'/dz']^T .

It can be identified as the first 4 entries of the 6^th 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/γ²) 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 = γ²z'

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 π : R^6×6 → R^4×4 is the projection operator.

This method finds that point z_t ≡ (x_t, x'_t, y_t, 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

Tz_t + δpΔ_t = z_t ,

which can be written

z_t = δp(I - T)^-1Δ_t ,

where I is the identity matrix. Dividing both sides by δp yields the final result

z₀ ≡ z_t/δp = (I - T)^-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.

The eigenvalues of T determine conditioning of the the resolvent (I - T)^-1. Whenever 1 ∈ λ(T) we have problems. Currently a value of 0 is returned whenever the resolvent does not exist.

Parameters:

matPhi - we are calculating the dispersion of a ring with this one-turn map

dblGamma - relativistic factor

Returns:

The closed orbit fixed point z₀ for finite dispersion, normalized by momentum spread. Returned as an array [x₀,x'₀,y₀,y'₀]/δp

Since:

Aug 14, 2013

computeTwiss

@Deprecated
protected Twiss3D computeTwiss(TwissProbe probe,
 PhaseMatrix matPhi,
 double dW)

Deprecated.

This is the algorithm component for a TwissProbe and should not be used as the dynamics elsewhere. It has been moved to the TwissTracker class.

Advance the twiss parameters using the given transfer matrix based upon formula 2.54 from S.Y. Lee's book.

CKA NOTES:

- This method will only work correctly for a beam that is unccorrelated in the phase planes.

Parameters:

probe - probe with target twiss parameters

matPhi - the transfer matrix of the element

dW - the energy gain of this element (eV)

Returns:

set of new twiss parameter values