Package xal.tools.beam.calc

Class SimResultsAdaptor

java.lang.Object
xal.tools.beam.calc.SimResultsAdaptor
All Implemented Interfaces:
ISimulationResults, ISimulationResults.ISimEnvResults<ProbeState<?>>, ISimulationResults.ISimLocResults<ProbeState<?>>
Direct Known Subclasses:
SimpleSimResultsAdaptor
public class SimResultsAdaptor extends Object implements ISimulationResults.ISimLocResults<ProbeState<?>>, ISimulationResults.ISimEnvResults<ProbeState<?>>

This class allows the developer to dynamically choose which calculation engine applies to which simulation results type. This is done by first registering the calculation engine (i.e., CalculationsOnBeams, CalculationsOnRings, etc.) using the method registerCalcEngine(Class, ISimulationResults) while providing the type of ProbeState derived simulation data and the previously instantiated calculation engine.

Currently, either or both of the interfacesISimulationResults.ISimLocResults and ISimulationResults.ISimEnvResults are recognized by the adaptor and the adaptor exposes both interfaces itself. When registering the adaptor checks if the calculation engine exposes each of the above interfaces then registers it as a provider of that calculation output. Any calls to registerCalcEngine(Class, ISimulationResults) supersedes any previous registrations.

When an exposed method of either of the supported interfaces is called upon this adaptor, it first looks at the type of ProbeState it was given then retrieves the calculation engine registered to that type. It then delegates the method call to that simulation engine and returns the result.

Since:
Nov 15, 2013
Author:
Christopher K. Allen

  • Constructor Details

    • SimResultsAdaptor

      public SimResultsAdaptor()
      Constructor for SimResultsAdaptor.
      Since:
      Nov 15, 2013

  • Method Details

    • registerCalcEngine

      public <I extends ISimulationResults> void registerCalcEngine(Class<? extends ProbeState<?>> clsType, I iCalcEngine) throws IllegalArgumentException
      Register the location calculation engine for the given probe data type.
      Parameters:
      clsType - class type of the simulation trajectory states
      iCalcEngine - interface of computation engine for processing the data
      Throws:
      IllegalArgumentException - unknown calculation engine type
      Since:
      Nov 15, 2013

    • computeCoordinatePosition

      public PhaseVector computeCoordinatePosition(ProbeState<?> state) throws IllegalArgumentException
      Description copied from interface: ISimulationResults.ISimLocResults

      Returns homogeneous phase space coordinates of something involving the simulation data. The interpretation is highly dependent upon the context of the data. That is, this quantity is open for interpretation; we can be referring to the position of the design trajectory, an offset, or the location of the beam centroid, whatever "beam" means in the context. The units are meters and radians.

      NOTE:

      This quantity is obtuse and not well defined - PhaseCoordinates of what?
          · Is this a centroid location?
          · From which starting orbit?
          · Not all simulation results have quantities naturally associated with phase coordinates

      Specified by:
      computeCoordinatePosition in interface ISimulationResults.ISimLocResults<ProbeState<?>>
      Parameters:
      state - simulation state where parameters are computed
      Returns:
      vector (x,x',y,y',z,z',1) of phase space coordinates
      Throws:
      IllegalArgumentException
      Since:
      Nov 19, 2013
      See Also:
      • xal.tools.beam.calc.ISimulationResults.ISimLocResults#computeCoordinatePosition(xal.model.probe.traj.ProbeState)

    • computeFixedOrbit

      public PhaseVector computeFixedOrbit(ProbeState<?> state)
      Description copied from interface: ISimulationResults.ISimLocResults

      Computes the fixed orbit about which betatron oscillations occur. This value is well-defined for rings but could be ambiguous for beam envelope simulation, especially with regard to method #computeCoordinatePosition(ProbeState). The returned value for some given simulation types are provided below.

      In general the idea is that the returned coordinate z in phase space P6 ≅ R6 × {1} is invariant under some map φ : P6 → P6 representing the dynamics of the system.

      IMPORTANT NOTE

      This method is provided to maintain compatibility with the previous use of computeFixedOrbit() presented by the trajectory classes for particles, beam envelopes, etc. (This method has been deprecated and discontinued.) The methods responded differently depending upon whether the structure producing the simulation data was from a ring or a linear transport/accelerator structure. This behavior has now changed, the method produces different results for different simulation types (e.g., particle, transfer map, envelope, etc.) rather than different simulation structures.

      When the underlying data is produced by a transfer map this method should return the fixed orbit position at the given state. When the underlying data is produced by a particle then the returned value should be the position of the particle at the given state location (for its given initial position). When the underlying data is from a beam envelope then this method should return the centroid location of the beam bunch (for its given initial condition).

      You must specify the simulation processing engine for each data type to use a SimResultsAdaptor. To reproduce the behavior of the past Trajectory#computeFixedOrbit(ProbeState) specify a CalculationsOnMachines simulation data processor for ring lattices and a CalculationsOnBeams simulation processor for linear lattices. This configuration is accommodated in the class SimpleSimResultsAdaptor exposing this interface.

      Specified by:
      computeFixedOrbit in interface ISimulationResults.ISimLocResults<ProbeState<?>>
      Parameters:
      state - simulation state where parameters are computed
      Returns:
      the reference orbit vector (x,x',y,y',z,z',1) (see comments)
      Since:
      Nov 19, 2013
      See Also:
      • xal.tools.beam.calc.ISimulationResults.ISimLocResults#computeFixedOrbit(xal.model.probe.traj.ProbeState)

    • computeChromAberration

      public PhaseVector computeChromAberration(ProbeState<?> state)
      Description copied from interface: ISimulationResults.ISimLocResults
      Compute and return the aberration at the given state location due to energy spread. The returned value Δ is the vector

          Δ ≡ (Δx, Δx', Δy, Δy', 0, 0, 1)

      where, when multiplied by momentum spread δ ≡ Δp/p yields the change in fixed orbit position. That is z = z0 + δΔ.
      Specified by:
      computeChromAberration in interface ISimulationResults.ISimLocResults<ProbeState<?>>
      Parameters:
      state - simulation state where parameters are computed
      Returns:
      the vector Δ of dispersion coefficients
      Since:
      Nov 19, 2013
      See Also:
      • xal.tools.beam.calc.ISimulationResults.ISimLocResults#computeChromAberration(xal.model.probe.traj.ProbeState)

    • computeTwissParameters

      public Twiss[] computeTwissParameters(ProbeState<?> state)
      Description copied from interface: ISimulationResults.ISimEnvResults
      Returns the array of twiss objects for this state for all three planes at the location of the given simulation state. These could be the matched beam Twiss parameters for a periodic structure or the dynamics Twiss parameters of a mismatched or otherwise evolving beam.
      Specified by:
      computeTwissParameters in interface ISimulationResults.ISimEnvResults<ProbeState<?>>
      Parameters:
      state - simulation state where Twiss parameters are computed
      Returns:
      array (twiss-H, twiss-V, twiss-L)
      Since:
      Nov 19, 2013
      See Also:
      • xal.tools.beam.calc.ISimulationResults.ISimEnvResults#computeTwissParameters(xal.model.probe.traj.ProbeState)

    • computeBetatronPhase

      public R3 computeBetatronPhase(ProbeState<?> state)
      Description copied from interface: ISimulationResults.ISimEnvResults
      Get the betatron phase values at the given state location for all three phase planes.
      Specified by:
      computeBetatronPhase in interface ISimulationResults.ISimEnvResults<ProbeState<?>>
      Parameters:
      state - simulation state where parameters are computed
      Returns:
      vector (ψx, ψy, ψx) of phases in radians
      Since:
      Nov 19, 2013
      See Also:
      • xal.tools.beam.calc.ISimulationResults.ISimEnvResults#computeBetatronPhase(xal.model.probe.traj.ProbeState)

    • computeChromDispersion

      public PhaseVector computeChromDispersion(ProbeState<?> state)
      Description copied from interface: ISimulationResults.ISimEnvResults

      Calculates the fixed point (closed orbit) in transverse phase space at the given state Sn location sn in the presence of dispersion.

      Let the full-turn map a the state location be denoted Φn (or the transfer matrix from entrance to location sn for a linac). 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 Φn. 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 Φn, which we denote take Tn. That is, Tn = π ⋅ Φn 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

          Tnzt + δpΔt = zt ,

      which can be written

        zt = δp(Tn - I)-1Δt ,

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

        z0 ≡ zt/δp = (Tn - 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.

      Specified by:
      computeChromDispersion in interface ISimulationResults.ISimEnvResults<ProbeState<?>>
      Parameters:
      state - we are calculating the dispersion at this state location
      Returns:
      The closed orbit fixed point z0 for finite dispersion, normalized by momentum spread. Returned as an array [x0,x'0,y0,y'0]/δp
      Since:
      Nov 19, 2013
      See Also:
      • xal.tools.beam.calc.ISimulationResults.ISimEnvResults#computeChromDispersion(xal.model.probe.traj.ProbeState)