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:

java.io.Serializable, IArchive

public class CovarianceMatrix
extends PhaseMatrix

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

 <zzT>  = | <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.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class xal.tools.beam.PhaseMatrix

PhaseMatrix.IND

Field Summary

Fields inherited from class xal.tools.beam.PhaseMatrix

IND_HOM, IND_X, IND_XP, IND_Y, IND_YP, IND_Z, IND_ZP, INT_SIZE

Fields inherited from class xal.tools.math.BaseMatrix

ATTR_DATA, matImpl

Constructor Summary

Constructors

Constructor and Description
CovarianceMatrix() Constructor for CovarianceMatrix.
CovarianceMatrix(PhaseMatrix matInit) Constructor for CovarianceMatrix.
CovarianceMatrix(java.lang.String strTokens) Constructor for CovarianceMatrix.

Method Summary

Modifier and Type	Method and Description
static CovarianceMatrix	buildCovariance(Twiss3D envTwiss) Create and return a CovarianceMatrix built according to the given set of Twiss parameters.
static CovarianceMatrix	buildCovariance(Twiss twissX, Twiss twissY, Twiss twissZ) Create a PhaseMatrix that is the correlation matrix corresponding to the given Twiss parameters.
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).
CovarianceMatrix	clone() Creates and returns a deep copy of this matrix.
CovarianceMatrix	computeCentralCovariance() Compute and return the covariance matrix of the distribution.
double	computeCentralCovXX() Compute and return the covariance value of the xx phase space coordinate monomial.
double	computeCentralCovXY() Compute and return the covariance value of the xy phase space coordinate monomial.
double	computeCentralCovXZ() Compute and return the covariance value of the xz phase space coordinate monomial.
double	computeCentralCovYY() Compute and return the covariance value of the yy phase space coordinate monomial.
double	computeCentralCovYZ() Compute and return the covariance value of the yz phase space coordinate monomial.
double	computeCentralCovZZ() Compute and return the covariance value of the zz phase space coordinate monomial.
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.
R3x3	computeSpatialCovariance() Compute and return the 3x3 symmetric matrix of all centralized spatial covariance values.
Twiss[]	computeTwiss() Return the Twiss parameters for each plane that correspond to the current correlation matrix.
void	forceRmsEmittances(double[] arrEmitNew) (Re)sets the rms emittances for the beam.
PhaseVector	getMean() Return the phase space coordinates of the centroid in homogeneous coordinates.
double	getMeanX() Return the mean value of the x phase variable.
double	getMeanY() Return the mean value of the y phase variable.
double	getMeanZ() Return the mean value of the z phase variable.
double	getSigmaX() Compute and return the standard deviation of the x phase variable
double	getSigmaY() Compute and return the standard deviation of the y phase variable
double	getSigmaZ() Compute and return the standard deviation of the z phase variable
static CovarianceMatrix	newCenter(PhaseVector vecCen) Create a "center matrix" corresponding the given mean values (centroid location).
static CovarianceMatrix	newIdentity() Create an identity correlation matrix
protected PhaseMatrix	newInstance() Handles object creation required by the base class.
static CovarianceMatrix	newZero() Create a new instance of a zero phase matrix.

Methods inherited from class xal.tools.beam.PhaseMatrix

homogenize, identity, max, minus, minusEquals, norm1, norm2, normF, normInf, parse, plus, plusEquals, projectColumn, projectColumn, projectR4x4, projectR6x6, projectRow, projectRow, rotationProduct, setElem, spatialTranslation, translation, zero

Methods inherited from class xal.tools.math.SquareMatrix

assignIdentity, conjugateInv, conjugateTrans, det, getSize, inverse, isEquivalentTo, isSymmetric, setElem, solve, solveInPlace, times, times, times, timesEquals, timesEquals, transpose

Methods inherited from class xal.tools.math.BaseMatrix

assignMatrix, assignZero, conditionNumber, copy, equals, getArrayCopy, getColCnt, getElem, getElem, getMatrix, getRowCnt, hashCode, load, newInstance, print, save, setElem, setMatrix, setMatrix, setSubMatrix, toString, toStringMatrix, toStringMatrix, toStringMatrix

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CovarianceMatrix

public CovarianceMatrix()

Constructor for CovarianceMatrix. Creates a zero values correlation matrix.

CovarianceMatrix

public CovarianceMatrix(PhaseMatrix matInit)
                 throws java.lang.IllegalArgumentException

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

Parameters:

matInit - symmetric PhaseMatrix object to initial this

Throws:

java.lang.IllegalArgumentException - initializing matrix is not symmetric

CovarianceMatrix

public CovarianceMatrix(java.lang.String strTokens)
                 throws java.lang.IllegalArgumentException,
                        java.lang.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:

java.lang.IllegalArgumentException - wrong number of token string in argument

java.lang.NumberFormatException - malformatted number in argument string

See Also:

PhaseMatrix.PhaseMatrix(String)

Method Detail

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

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(Twiss, Twiss, Twiss)

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


| R_xx 0 0 0 |
| 0 R_yy 0 0 |
| 0 0 R_zz 0 |
| 0 0 0 1 |

where R_ii 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.,

Returns:

correlation matrix corresponding to the above twiss parameters and mean value vector

clone

public CovarianceMatrix clone()

Creates and returns a deep copy of this matrix.

Overrides:

clone in class PhaseMatrix

Since:

Jul 3, 2014

See Also:

BaseMatrix.clone()

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

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

newInstance

protected PhaseMatrix newInstance()

Handles object creation required by the base class.

Overrides:

newInstance in class PhaseMatrix

Returns:

uninitialized matrix object of type M

Since:

Jun 17, 2014

See Also:

PhaseMatrix.newInstance()