Package xal.tools.beam

Class CovarianceMatrix

java.lang.Object
xal.tools.math.BaseMatrix<M>
xal.tools.math.SquareMatrix<PhaseMatrix>
xal.tools.beam.PhaseMatrix
xal.tools.beam.CovarianceMatrix
All Implemented Interfaces:
Serializable, IArchive
public class CovarianceMatrix extends PhaseMatrix

A CovarianceMatrix in homogeneous coordinates represents all moments of a phase space distribution up to and including second order. This is seen by taken the moment of the outer product of two phase vectors. We find 

 <zzˆT>  = | <xx>   <xx'   <xy>   <xy'>  <xz>   <xz'>  <x>  |
           | <x'x>  <x'x'> <x'y>  <x'y'> <x'z>  <x'z'> <x'> |
           | <yx>   <yx'>  <yy>   <yy'>  <yz>   <yz'>  <y>  |
           | <y'x>  <y'x'> <y'y>  <y'y'> <y'z>  <y'z'> <y'> |
           | <zx>   <zx'>  <zy>   <zy'>  <zz>   <zz'>  <z>  |
           | <z'x>  <z'x'> <z'y>  <z'y>  <z'z>  <z'z'> <z'> |
           | <x>     <x>    <y>     <y>   <z>    <z>   <1>  |
where x', y', z' represent the momentum coordinate in the x, y, and z directions, respectively.

Note that the covariance matrix is not necessarily centralized. Specifically, if the beam is off axis, then at least one of the moments <x>, <y>, <z> is non-zero and the corresponding second-order moments will be skewed. Likewise, if the beam has a coherent drift in some direction, then the moments <x'>, <y'>, <z'> will have at least one nonlinear value. There are methods in this class for returning centralized moments when such quantities are needed.

Note that the covariance matrix is not necessarily centralized. Specifically, if the beam is off axis, then at least one of the moments <x>, <y>, <z> is non-zero and the corresponding second-order moments will be skewed. Likewise, if the beam has a coherent drift in some direction, then the moments <xp>, <yp>, <zp> will have at least one nonlinear value. There are methods in this class for returning centralized moments when such quantities are needed.

Author:
Christopher K. Allen, Craig McChesney
See Also:

  • Constructor Details

    • CovarianceMatrix

      public CovarianceMatrix()
      Constructor for CovarianceMatrix. Creates a zero values correlation matrix.

    • CovarianceMatrix

      public CovarianceMatrix(PhaseMatrix matInit) throws IllegalArgumentException

      Constructor for CovarianceMatrix. Creates an initialized correlation matrix from a symmetric PhaseMatrix argument.

      We are not checking symmetry of the given phase matrix in order to expedite the process. So the caller must ensure symmetry.

      Parameters:
      matInit - symmetric PhaseMatrix object to initial this
      Throws:
      IllegalArgumentException - initializing matrix is not symmetric

    • CovarianceMatrix

      public CovarianceMatrix(String strTokens) throws IllegalArgumentException, NumberFormatException
      Constructor for CovarianceMatrix. Takes a formatted text string containing the initial values of the matrix.
      Parameters:
      strTokens - initial values of matrix in Mathematica format
      Throws:
      IllegalArgumentException - wrong number of token string in argument
      NumberFormatException - malformatted number in argument string
      See Also:

  • Method Details

    • newZero

      public static CovarianceMatrix newZero()
      Create a new instance of a zero phase matrix.
      Returns:
      zero vector

    • newIdentity

      public static CovarianceMatrix newIdentity()
      Create an identity correlation matrix
      Returns:
      7x7 real identity matrix

    • newCenter

      public static CovarianceMatrix newCenter(PhaseVector vecCen)

      Create a "center matrix" corresponding the given mean values (centroid location). The returned matrix can be subtracted from a covariance matrix to produce a central covariance matrix.

      NOTE:

      The returned matrix is the outer product of the given argument. Specifically σ = v*v'.
      Parameters:
      vecCen - mean value vector of the phase space coordinates, i.e., <z>
      Returns:
      center matrix corresponding to mean value vector

    • buildCovariance

      public static CovarianceMatrix buildCovariance(Twiss3D envTwiss)
      Create and return a CovarianceMatrix built according to the given set of Twiss parameters.
      Parameters:
      envTwiss - twiss parameter set describing RMS envelope
      Returns:
      correlation matrix with statistical properties of argument
      See Also:

    • buildCovariance

      public static CovarianceMatrix buildCovariance(Twiss twissX, Twiss twissY, Twiss twissZ)

      Create a PhaseMatrix that is the correlation matrix corresponding to the given Twiss parameters. Note that the correlation matrix is for a centered beam (on axis). Thus, the correlation matrix is actually the covariance matrix.

      NOTE:

      No unit conversion is done, the correlation matrix has the same unit system as the Twiss parameters.

      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.

      Parameters:
      twissX - twiss parameters of the x phase plane
      twissY - twiss parameters of the y phase plane
      twissZ - twiss parameters of the z phase plane
      Returns:
      correlation matrix corresponding to the above twiss parameters

    • buildCovariance

      public static CovarianceMatrix buildCovariance(Twiss twissX, Twiss twissY, Twiss twissZ, PhaseVector vecCen)

      Create a CovarianceMatrix corresponding to the given Twiss parameters and having the given mean values (centroid location).

      NOTE:

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

      | Rxx 0 0 <x> |
      | 0 Ryy 0 <y> |
      | 0 0 Rzz <z> |
      | <x> <y> <z> 1 |

      where Rii are 2x2 symmetric blocks corresponding to each phase plane, and <i> is shorthand for the vector of phase averages for the i plane, eg. <x> = (<x>, <x'>).

      Parameters:
      twissX - twiss parameters of the x phase plane
      twissY - twiss parameters of the y phase plane
      twissZ - twiss parameters of the z phase plane
      vecCen - mean value vector of the phase space coordinates, i.e., <z>
      Returns:
      correlation matrix corresponding to the above twiss parameters and mean value vector

    • loadFrom

      public static CovarianceMatrix loadFrom(DataAdaptor daSource) throws IllegalArgumentException, DataFormatException
      Create a new CovarianceMatrix object and initialize with the data source behind the given DataAdaptor interface. Currently we are checking for symmetry within the loaded matrix so this method is using extended CPU time.
      Parameters:
      daSource - data source containing initialization data
      Throws:
      DataFormatException - malformed data in data source
      IllegalArgumentException - the described matrix is not symmetric
      Since:
      Jan 4, 2016, Christopher K. Allen
      See Also:

    • forceRmsEmittances

      public void forceRmsEmittances(double[] arrEmitNew)

      (Re)sets the rms emittances for the beam. This method scales the X,Y,Z diagonal blocks of the correlation matrix so the beam has the rms emittances provided.

      NOTES:

      Since the emittance values are contained in the correlation matrix attempting to set emittances with an empty (zero) correlation matrix causes a floating point exception. As such, this method can really only change existing emittances and is to be regarded as a convenience function.

      IMPORTANT:

      The current implementation is valid ONLY FOR ZERO-MEAN correlations.

      TODO

      Fix the implementation so that it is valid for off-centered distributions.

      Parameters:
      arrEmitNew - three element vector of rms emittances for X,Y,Z planes, respectively Units radian-meters

    • getMeanX

      public double getMeanX()
      Return the mean value of the x phase variable.
      Returns:
      the value of <x>

    • getMeanY

      public double getMeanY()
      Return the mean value of the y phase variable.
      Returns:
      the value of <y>

    • getMeanZ

      public double getMeanZ()
      Return the mean value of the z phase variable.
      Returns:
      the value of <z>

    • getMean

      public PhaseVector getMean()
      Return the phase space coordinates of the centroid in homogeneous coordinates. Since the correlation matrix is represented in homogeneous coordinates the mean values are elements of the correlation matrix. These values are extracted and returned as a vector.
      Returns:
      PhaseVector representing the mean values of the correlation

    • computeCentralCovXX

      public double computeCentralCovXX()
      Compute and return the covariance value of the xx phase space coordinate monomial.
      Returns:
      the value <x^2>-<x>^2

    • computeCentralCovXY

      public double computeCentralCovXY()
      Compute and return the covariance value of the xy phase space coordinate monomial.
      Returns:
      the value <xy>-<x><y>

    • computeCentralCovYY

      public double computeCentralCovYY()
      Compute and return the covariance value of the yy phase space coordinate monomial.
      Returns:
      the value <y^2>-<y>^2

    • computeCentralCovYZ

      public double computeCentralCovYZ()
      Compute and return the covariance value of the yz phase space coordinate monomial.
      Returns:
      the value <yz>-<y><z>

    • computeCentralCovZZ

      public double computeCentralCovZZ()
      Compute and return the covariance value of the zz phase space coordinate monomial.
      Returns:
      the value <z^2>-<z>^2

    • computeCentralCovXZ

      public double computeCentralCovXZ()
      Compute and return the covariance value of the xz phase space coordinate monomial.
      Returns:
      the value <xz>-<x><z>

    • computeSpatialCovariance

      public R3x3 computeSpatialCovariance()
      Compute and return the 3x3 symmetric matrix of all centralized spatial covariance values. Recall that the covariance matrix sig is the matrix of central second moments and is related to the correlation matrix <zz> according to sig = <zz> - <z><z> where z = (x x' y y' z z' 1) is the phase space coordinate vector. Thus, the returned spatial covariance matrix has the form | <xx>-<x><x> <xy>-<x><y> <xz>-<x><z> | | <xy>-<x><y> <yy>-<y><y> <yz>-<y><z> | | <xz>-<x><z> <yz>-<x><z> <zz>-<z><z> |
      Returns:
      3x3 symmetric matrix of central, spatial covariance moments

    • getSigmaX

      public double getSigmaX()
      Compute and return the standard deviation of the x phase variable
      Returns:
      sqrt( <x^2> - <x>^2 )

    • getSigmaY

      public double getSigmaY()
      Compute and return the standard deviation of the y phase variable
      Returns:
      sqrt( <y^2> - <y>^2 )

    • getSigmaZ

      public double getSigmaZ()
      Compute and return the standard deviation of the z phase variable
      Returns:
      sqrt( <z^2> - <z>^2 )

    • computeCentralCovariance

      public CovarianceMatrix computeCentralCovariance()
      Compute and return the covariance matrix of the distribution. Note that this can be computed from the correlation matrix in homogeneous coordinates since the mean values are included in that case.
      Returns:
      <(z-<z>)*(z-<z>)^T> = <z*z^T> - <z>*<z>^T

    • computeRmsEmittances

      public double[] computeRmsEmittances()
      Return the x,y,z plane rms emittance of the beam Units: radian-meters NOTE: This method ignores any coupling between phase planes and any offsets of the beam centroid from the beam axis. (To implement a method which gives the emittances if the beam where centered use the method this.phaseCovariance() instead of this.phaseCorrelation().)
      Returns:
      array of double with length 3 where array[0] = emittance in x plane array[1] = emittance in y plane array[2] = emittance in z plane

    • computeTwiss

      public Twiss[] computeTwiss()
      Return the Twiss parameters for each plane that correspond to the current correlation matrix. NOTE: This method ignores any coupling between phase planes. 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.
      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

    • clone

      public CovarianceMatrix clone()
      Creates and returns a deep copy of this matrix.
      Overrides:
      clone in class PhaseMatrix
      Since:
      Jul 3, 2014
      See Also:

    • newInstance

      protected PhaseMatrix newInstance(int row, int cnt)
      Handles object creation required by the base class.
      Overrides:
      newInstance in class PhaseMatrix
      Parameters:
      row - Number of rows.
      cnt - Number of columns.
      Returns:
      uninitialized matrix object of type M
      Since:
      Jun 17, 2014
      See Also:
      • xal.tools.beam.PhaseMatrix#newInstance()