Package xal.tools.beam.calc

Class CalculationsOnBeams

java.lang.Object
xal.tools.beam.calc.CalculationEngine
xal.tools.beam.calc.CalculationsOnBeams
All Implemented Interfaces:
ISimulationResults, ISimulationResults.ISimEnvResults<EnvelopeProbeState>, ISimulationResults.ISimLocResults<EnvelopeProbeState>
public class CalculationsOnBeams extends CalculationEngine implements ISimulationResults.ISimLocResults<EnvelopeProbeState>, ISimulationResults.ISimEnvResults<EnvelopeProbeState>
Class for performing calculations on data obtained from simulating linacs and beam transport systems. The class performs the calculation exposed in the ISimEnvResults interface. They are performed in the context of a linear accelerator or transport system acting upon a beam bunch, the simulation data being a trajectory of EnvelopeProbeStates.
Since:
Oct 22, 2013
Author:
Christopher K. Allen

  • Constructor Details

    • CalculationsOnBeams

      public CalculationsOnBeams(Trajectory<EnvelopeProbeState> datSim)
      Constructor for CalculationsOnBeams. Creates object and computes all the static simulation results.
      Parameters:
      datSim - results for an EnvelopeProbe simulation
      Since:
      Oct 22, 2013

  • Method Details

    • getTrajectory

      public Trajectory<EnvelopeProbeState> getTrajectory()
      Returns the simulation trajectory from which all the machine properties are computed.
      Returns:
      simulation trajectory from which this object was initialized
      Since:
      Nov 7, 2013

    • getFullResponseMatrix

      public PhaseMatrix getFullResponseMatrix()
      Returns the transfer map of the full machine lattice represented by the associated simulation trajectory.
      Returns:
      the transfer map of the last state of the associated trajectory
      Since:
      Nov 7, 2013

    • periodBetatronPhaseAdvance

      public R3 periodBetatronPhaseAdvance()

      Returns the betatron phase advances from the simulation beginning to end (which are computed at instantiation). The returned value is the calculation CalculationEngine.calculatePhaseAdvPerCell(PhaseMatrix) of the super class, and thus assumes simulation trajectory is that for at least one period of a periodic structure.

      NOTES:

      · The betatron phase advances are given in the range [0,2&pi];.

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

    • periodFixedOrbitPt

      public PhaseVector periodFixedOrbitPt()

      Returns the phase space location of the fixed orbit at the simulation start (which is computed at instantiation) assuming the simulation is that for at least one period of a periodic accelerating or transport section. The returned value z is the result of the calculation CalculationEngine.calculateFixedPoint(PhaseMatrix) given the full turn matrix Φ at the simulation exit (see getFullResponseMatrix()). 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

    • periodMatchedTwiss

      public Twiss[] periodMatchedTwiss()

      Returns the matched Courant-Snyder parameters at the entrance of the simulation assuming the simulation is for at least one period of a periodic structure. These are the "envelopes" taken from the "closed envelope" solution under the assume the linac is a periodic transport.

      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 simulation 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

    • computeTransferMatrix

      public PhaseMatrix computeTransferMatrix(String elemFrom, String elemTo)
      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
      Parameters:
      elemFrom - String identifying starting lattice element
      elemTo - String identifying ending lattice element
      Returns:
      response matrix from elemFrom to elemTo
      See Also:
      • EnvelopeTrajectory#computeTransferMatrix(String, String)

    • computeCoordinatePosition

      public PhaseVector computeCoordinatePosition(EnvelopeProbeState state)
      Returns the centroid location of the beam envelope. This quantity is taken from the CovarianceMatrix state object. Since the state quantities are expressed in homogeneous coordinates the final row and column of the covariance matrix are interpreted as the centroid vector of the beam bunch.
      Specified by:
      computeCoordinatePosition in interface ISimulationResults.ISimLocResults<EnvelopeProbeState>
      Parameters:
      state - simulation state where parameters are computed
      Returns:
      vector (x,x',y,y',z,z',1) of phase space coordinates
      Since:
      Nov 7, 2013
      See Also:
      • xal.tools.beam.calc.ISimEnvResults#computeCoordinatePosition(xal.model.probe.traj.ProbeState)

    • computeFixedOrbit

      public PhaseVector computeFixedOrbit(EnvelopeProbeState state)

      IMPORTANT NOTE

      This method has been modified so it returns exactly the same value as #computeCoordinatePosition(ParticleProbeState). This modification is maintain compatibility with the previous use of computeFixedOrbit() presented by the trajectory classes for particles, beam envelopes, etc. They responded differently depending upon whether the structure producing the simulation data was from a ring or a linear transport/accelerator structure.

      Thus, ignore all commenting below!

      Consider first the point in phase space that is invariant under repeated application of the response matrix Φ for the entire beamline or ring. This is under the condition that we decompose Φ into its homogeneous and non-homogeneous components. A particle entering the linac at that location exits at the same location.

      To compute this linac fixed point, recall that the homogeneous response matrix Φ for the beamline (or full-turn matrix for a ring) has final row that represents the translation Δ of the particle under the action of Φ. 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 into the embedded phase space R6 (without 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 ∈ 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 solution value is then z = (p 0 0 1)T.

      Once we have the fixed point z0 for the linac we compute the trajectory of the fixed point at the location of the given probe state. To do so, we multiply z0 by the response matrix Φn for the given probe state. That is, we propagate the fixed point of the linac from the linac entrance to the location of the given phase state.

      Specified by:
      computeFixedOrbit in interface ISimulationResults.ISimLocResults<EnvelopeProbeState>
      Parameters:
      state - simulation state where parameters are computed
      Returns:
      The quantity Φn⋅z0, the linac fixed point z0 propagated to the state location sn
      Since:
      Nov 7, 2013
      See Also:
      • xal.tools.beam.calc.ISimEnvResults#computeFixedOrbit(xal.model.probe.traj.ProbeState)

    • computeChromAberration

      public PhaseVector computeChromAberration(EnvelopeProbeState 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. The returned vector is the displacement from the closed orbit caused by a unit momentum offset (δp = 1). See the documentation in ISimLocResults#computeChromAberration(ProbeState) for a more detailed exposition.
      Specified by:
      computeChromAberration in interface ISimulationResults.ISimLocResults<EnvelopeProbeState>
      Parameters:
      state - simulation state where parameters are computed
      Returns:
      the vector Δ of dispersion coefficients
      Since:
      Nov 15, 2013
      See Also:
      • xal.tools.beam.calc.ISimLocResults#computeChromAberration(xal.model.probe.traj.ProbeState)

    • computeTwissParameters

      public Twiss[] computeTwissParameters(EnvelopeProbeState state)
      Returns the Courant-Snyder parameters of the beam envelope at the location of the given probe state. These values are computed from the primary state object of an EnvelopeProbe the covariance matrix σ. Only the 2×2 diagonal blocks of σ are used for Courant-Snyder parameter calculations (for each phase plane), thus, any phase plane coupling is lost.
      Specified by:
      computeTwissParameters in interface ISimulationResults.ISimEnvResults<EnvelopeProbeState>
      Parameters:
      state - simulation state where Twiss parameters are computed
      Returns:
      array (twiss-H, twiss-V, twiss-L)
      Since:
      Nov 7, 2013
      See Also:
      • xal.tools.beam.calc.ISimEnvResults#computeTwissParameters(xal.model.probe.traj.ProbeState)

    • computeBetatronPhase

      public R3 computeBetatronPhase(EnvelopeProbeState state)

      Computes and returns the "betatron phase" of a beam particle within the simulated envelope at the given state location. This quantity is the phase advance between the beginning of the simulation and the given state location. The calculation proceeds by computing the Courant-Snyder parameters α and β of the envelope at the entrance to the linac and at the given state location using the covariance matrix σ(s) of the simulation. The given state also contains the response matrix Φ(s) between the entrance to the linac and the current state location s. This matrix is used as the transfer matrix mapping particle phase coordinates between the linac entrance and the current state location.

      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).

      Specified by:
      computeBetatronPhase in interface ISimulationResults.ISimEnvResults<EnvelopeProbeState>
      Parameters:
      state - simulation state where parameters are computed
      Returns:
      vector (ψx, ψy, ψx) of phases in radians
      Since:
      Nov 7, 2013
      See Also:
      • xal.tools.beam.calc.ISimEnvResults#computeBetatronPhase(xal.model.probe.traj.ProbeState)

    • computeChromDispersion

      public PhaseVector computeChromDispersion(EnvelopeProbeState state)

      Convenience function for returning the chromatic dispersion coefficients as defined by D.C. Carey in "The Optics of Charged Particle Beams".

      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. The returned vector is the displacement from the closed orbit caused by a unit momentum offset (δp = 1). See the documentation in ISimLocResults#computeChromAberration(ProbeState) for a more detailed exposition.

      NOTE:

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

      Specified by:
      computeChromDispersion in interface ISimulationResults.ISimEnvResults<EnvelopeProbeState>
      Parameters:
      state - we are calculating the dispersion at this state location
      Returns:
      vector of chromatic dispersion coefficients in meters/radian
      Since:
      Nov 8, 2013
      See Also:
      • xal.tools.beam.calc.ISimEnvResults#computeChromDispersion(xal.model.probe.traj.ProbeState)