Package xal.tools.beam

Class TraceXalUnitConverter

java.lang.Object
xal.tools.beam.TraceXalUnitConverter
public class TraceXalUnitConverter extends Object
Converts between Trace3D and XAL unit for envelope simulations.
Author:
Craig McChesney, Christopher Allen

  • Field Details

    • XAL_TO_TRACE_DIMENSION

      public static final double XAL_TO_TRACE_DIMENSION
      m to mm
      See Also:

    • TRACE_TO_XAL_DIMENSION

      public static final double TRACE_TO_XAL_DIMENSION
      mm to m
      See Also:

  • Method Details

    • newConverter

      public static TraceXalUnitConverter newConverter(double f, double eR, double w)
      Creates a new TraceXalUnitConverter object configured to the specified machine and beam species parameters. All conversions done by the returned object will assume the values provided in the initial configuration.
      Parameters:
      f - machine electromagnetic frequency in Hz
      eR - the rest energy of the beam particle species in eV
      w - the kinetic energy of the beam in eV
      Returns:
      new unit conversion object configured to above parameters

    • setRfFrequency

      public void setRfFrequency(double f)
      Change the RF frequency parameter used for longitudinal calculations.
      Parameters:
      f - new RF frequency in Hz

    • setKineticEnergy

      public void setKineticEnergy(double w)
      Change the current beam kinetic energy.
      Parameters:
      w - new beam energy in eV

    • setRestEnergy

      public void setRestEnergy(double eR)
      Change the current particle species rest energy.
      Parameters:
      eR - new rest energy in eV

    • traceToXalCoordinates

      public PhaseVector traceToXalCoordinates(PhaseVector vecCoords)

      Converts phase vector values in Trace3D units to values in units used by XAL (MKS). Specifically, the argument vecCoord is assumed to be in the form 

            vecPhase=(x,x',y,y',dPhi,dW,1)

      x    in mm
      x'   in mrad
      y    in mm
      y'   in mrad
      dPhi in degrees
      dW   in keV
      The output vector in in the following form along with the units: 
            returned=(x,x',y,y',z,z',1)

      x  in meters
      x' in radians
      y  in meters
      y' in radians
      z  in meters
      z' in radians

      Parameters:
      vecCoords - coordinate phase vector in Trace3D units
      Returns:
      coordinate phase vector in XAL (MKS) units

    • xalToTraceCoordinates

      public PhaseVector xalToTraceCoordinates(PhaseVector vecCoords)

      Converts phase vector values in XAL (MKS) units to values in units used by Trace3D. Specifically, the argument vecCoords is assumed to be in the form 

            vecCoords=(x,x',y,y',z,z',1)

      x  in meters
      x' in radians
      y  in meters
      y' in radians
      z  in meters
      z' in radians
      The output vector in in the following form along with the units: 
            returned=(x,x',y,y',dPhi,dW,1)

      x    in mm
      x'   in mrad
      y    in mm
      y'   in mrad
      dPhi in degrees
      dW   in keV

      Parameters:
      vecCoords - coordinate phase vector in MKS units
      Returns:
      coordinate phase vector in Trace3D units

    • traceToXalTransverse

      public Twiss traceToXalTransverse(Twiss t3dTwiss)

      Converts Twiss parameter in Trace3D units to XAL (MKS) units for the transverse phase planes. Method takes the set of Twiss parameters as a Twiss object argument and returns a new object containing the same Twiss in the different units. The method is none destructive.

      Trace3D XAL
      alpha unitless unitless (no conversion)
      beta m/rad m/rad
      emittance eff. (5xRMS) mm-mrad RMS m-rad

      Parameters:
      t3dTwiss - Twiss parameters in Trace3D units
      Returns:
      Twiss parameters in XAL units

    • traceToXalLongitudinal

      public Twiss traceToXalLongitudinal(Twiss t3dTwiss)

      Converts Twiss parameters in Trace3D units to XAL (MKS) units for the longitudinal phase planes. Method takes the set of Twiss parameters as a Twiss object argument and returns a new object containing the same Twiss in the different units. The method is non destructive.

      Trace3D XAL
      alpha unitless (-1)unitless (phase lag is positive)
      beta deg/keV m/rad
      emittance eff. (5xRMS) deg-keV RMS m-rad

      Parameters:
      t3dTwiss - Trace3D twiss parameters
      Returns:
      Twiss parameters in XAL units

    • xalToTraceTransverse

      public Twiss xalToTraceTransverse(Twiss twissXal)

      Converts Twiss parameter in XAL (MKS) units to Trace3D units for the transverse phase planes. Method takes the set of Twiss parameters as a Twiss object argument and returns a new object containing the same Twiss in the different units. The method is none destructive.

      Trace3D XAL
      alpha unitless unitless (no conversion)
      beta m/rad m/rad
      emittance eff. (5xRMS) mm-mrad RMS m-rad

      Parameters:
      twissXal - Twiss parameters in XAL (MKS) units
      Returns:
      Twiss parameters in Trace3D units

    • xalToTraceLongitudinal

      public Twiss xalToTraceLongitudinal(Twiss twissXal)

      Converts Twiss parameters in XAL (MKS) units to Trace3D units for the longitudinal phase planes. Method takes the set of Twiss parameters as a Twiss object argument and returns a new object containing the same Twiss in the different units. The method is none destructive.

      Trace3D XAL
      alpha unitless (-1)unitless (phase lag is positive)
      beta deg/keV m/rad
      emittance eff. (5xRMS) deg-keV RMS m-rad

      Parameters:
      twissXal - Trace3D twiss parameters
      Returns:
      Twiss parameters in XAL units

    • xalToTraceDispersion

      public double xalToTraceDispersion(double dXal, PhaseIndex index)
      Convert the dispersion from XAL units to Trace3D units.
      Parameters:
      dXal - dispersion as z' (radians)
      index - phase plane index
      Returns:
      dispersion as dp/p0 (radians)

    • traceToXalDispersion

      public double traceToXalDispersion(double dT3d, PhaseIndex index)
      Convert the dispersion from XAL units to Trace3D units.
      Parameters:
      dT3d - dispersion as dp/p0 (radians)
      index - phase plane index
      Returns:
      dispersion as z' (radians)

    • correlationMatrixFromT3d

      public CovarianceMatrix correlationMatrixFromT3d(Twiss t3dX, Twiss t3dY, Twiss t3dZ)

      Builds a correlation matrix from Twiss parameters in the three phase planes. The Twiss parameters are assumed to be in the units used by Trace3D. The beam is also assumed to be centered (on axis), thus the correlation matrix equals the covariance matrix (usually denoted sigma).

      NOTE: The returned matrix is in homogeneous coordinates of the block diagonal form 

            | Rxx   0   0   0 |
      |   0 Ryy   0   0 |
      |   0   0 Rzz   0 |
      |   0   0   0   1 |
      where Rii are 2x2 symmetric blocks corresponding to each phase plane. Clearly the phase planes are uncoupled.

      The covariance matrix is the second central moment of the beam distribution defined by

      sigma = <( z-<z> )2> = <zzT>-<z><z>T = <zzT>
      since since the centroid <z>=0.

      Parameters:
      t3dX - Twiss parameters describing the beam ellipse in the x plane
      t3dY - Twiss parameters describing the beam ellipse in the y plane
      t3dZ - Twiss parameters describing the beam ellipse in the z plane
      Returns:
      correlation matrix corresponding to the above Twiss parameters
      See Also:

    • correlationMatrixFromT3d

      public CovarianceMatrix correlationMatrixFromT3d(Twiss t3dX, Twiss t3dY, Twiss t3dZ, PhaseVector centroid)

      Builds a correlation matrix from Twiss parameters in the three phase planes. The Twiss parameters are assumed to be in the units used by Trace3D. The correlation matrix also has the mean values corresponding to the mean value vector <z> provided in the argument. The mean value vector centroid is also assumed to be in the units used by Trace3D. It is also assumed to have the form

      centroid = <z> = (<x>, <x'>, <y>, <y'>, <dPhi>, <dW>, 1)

      The correlation matrix is computed by first computing the covariance matrix (usually denoted sigma in the literature) from the Twiss parameters then adjusting the value according to the effects of being "off center". This is done by adding the tensor product of the mean value vector <z>.

      To see this not that the correlation matrix is the second moment of the beam distribution defined by

      <zzT>
      Thus, denoting sigma the covariance matrix we have
      sigma = <( z-<z> )2> = <zzT>-<z><z>T
      or
      <zzT> = sigma + <z><z>T

      NOTE: The returned matrix is in homogeneous coordinates of the block diagonal form 

            | Rxx   0   0    0 |
      |   0 Ryy   0    0 |   +  <z><z>T
      |   0   0 Rzz    0 |
      |   0   0   0    1 |
      where Rii are 2x2 symmetric blocks corresponding to each phase plane and <z> is the vector of mean values in the phase plane, e.g., <z>=(<x>, <x'>, <y>, <y'>, <z>, <z'>).

      Parameters:
      t3dX - Twiss parameters describing the beam ellipse in the x plane
      t3dY - Twiss parameters describing the beam ellipse in the y plane
      t3dZ - Twiss parameters describing the beam ellipse in the z plane
      centroid - phase position of the beam centroid
      Returns:
      correlation matrix corresponding to the above Twiss parameters and centroid
      See Also:

    • centroidFromXal

      public PhaseVector centroidFromXal(CovarianceMatrix matCorrel)
      Compute and return the beam centroid coordinates from the correlation matrix in homogeneous coordinates. The correlation matrix is assumed to be in MKS units used by XAL and the returned centroid coordinate vector is in phase coordinates units used by Trace3D.
      Parameters:
      matCorrel - correlation matrix <zzT> in MKS units
      Returns:
      coordinates of the centroid in Trace3D units
      See Also:

    • twissParametersFromXal

      public Twiss[] twissParametersFromXal(CovarianceMatrix mat)
      Computes and return the Twiss parameters for each plane that correspond to the given correlation matrix. The Twiss parameters are returned in the units used by Trace3D. The correlation matrix is assumed to be in MKS units used by XAL.

      NOTE: This method ignores any coupling between phase planes and any offsets of the beam centroid from the beam axis.

      TODO - Make the method consider the general case of coupling between phase planes and return the Twiss parameters as projections that one would observe in experiments.

      Parameters:
      mat - correlation matrix <zzT> in MKS units
      Returns:
      array of Twiss with length 3 where
      array[0] = Twiss parameters in x plane
      array[1] = Twiss parameters in y plane
      array[2] = Twiss parameters in z plane

    • calcSigmaXalFromTrace

      public static double calcSigmaXalFromTrace(double beta, double emit)
      calculate 1-sigma in xal unit from beta and emittance of xal unit

    • calcSigmaTraceFromTrace

      public static double calcSigmaTraceFromTrace(double beta, double emit)
      calculate 1-sigma in trace3d unit from beta and emittance of trace3d unit

    • calcSigmaXalFromXal

      public static double calcSigmaXalFromXal(double beta, double emit)
      calculate 1-sigma in xal unit from beta and emittance of xal unit

    • calcSigmaTraceFromXal

      public static double calcSigmaTraceFromXal(double beta, double emit)
      calculate 1-sigma in trace3d unit from beta and emittance of trace3d unit