gov.sns.tools.beam
Class CorrelationMatrix

java.lang.Object
  |
  +--gov.sns.tools.beam.PhaseMatrix
        |
        +--gov.sns.tools.beam.CorrelationMatrix

All Implemented Interfaces:

IArchive, java.io.Serializable

public class CorrelationMatrix

extends PhaseMatrix

A CorrelationMatrix in homogeneous coordinates represents all momements 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 <z*z'> = | <x*x> <x*xp <x*y> <x*yp> <x*z> <x*zp> <x> | | <xp*x> <xp*xp> <xp*y> <xp*yp> <xp*z> <xp*zp> <xp> | | <y*x> <y*xp> <y*y> <y*yp> <y*z> <y*zp> <y> | | <yp*x> <yp*xp> <yp*y> <yp*yp> <yp*z> <yp*zp> <yp> | | <z*x> <z*xp> <z*y> <z*yp> <z*z> <z*zp> <z> | | <zp*x> <zp*xp> <zp*y> <zp*yp> <zp*z> <zp*zp> <zp> | | <x> <xp> <y> <yp> <z> <zp> <1> |

See Also:

Serialized Form

Field Summary

Fields inherited from class gov.sns.tools.beam.PhaseMatrix

ATTR_DATA, DIM, IND_HOM, IND_X, IND_XP, IND_Y, IND_YP, IND_Z, IND_ZP

Constructor Summary

CorrelationMatrix()
Constructor for CorrelationMatrix.

CorrelationMatrix(Jama.Matrix matInit)
Constructor for CorrelationMatrix.

CorrelationMatrix(PhaseMatrix matInit)
Constructor for CorrelationMatrix.

CorrelationMatrix(java.lang.String strTokens)
Constructor for CorrelationMatrix.

Method Summary

static CorrelationMatrix	buildCorrelation(Twiss twissX, Twiss twissY, Twiss twissZ) Create a PhaseMatrix that is the correlation matrix corresponding to the given Twiss parameters.
static CorrelationMatrix	buildCorrelation(Twiss twissX, Twiss twissY, Twiss twissZ, PhaseVector vecMean) Create a CorrelationMatrix corresponding to the given Twiss parameters and having the given mean values (centroid values).
CorrelationMatrix	getCovariance() Compute and return the covariance matrix of the distribution.
double	getCovXX() Compute and return the covariance value of the xx phase space coordinate monomial.
double	getCovXY() Compute and return the covariance value of the xy phase space coordinate monomial.
double	getCovXZ() Compute and return the covariance value of the xz phase space coordinate monomial.
double	getCovYY() Compute and return the covariance value of the yy phase space coordinate monomial.
double	getCovYZ() Compute and return the covariance value of the yz phase space coordinate monomial.
double	getCovZZ() Compute and return the covariance value of the zz phase space coordinate monomial.
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 CorrelationMatrix	newIdentity() Create an identity correlation matrix
static CorrelationMatrix	newZero() Create a new instance of a zero phase matrix.
double[]	rmsEmittances() 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.
void	setRmsEmittances(double[] arrEmitNew) (Re)sets the rms emittances for the beam.
Twiss[]	twissParameters() Return the Twiss parameters for each plane that correspond to the current correlation matrix.

Methods inherited from class gov.sns.tools.beam.PhaseMatrix

compPhaseAdvance, conjugateInv, conjugateTrans, det, equals, getElem, hashCode, identity, inverse, load, main, minus, minusEquals, norm1, norm2, normInf, parse, plus, plusEquals, print, save, setElem, setMatrix, setSubMatrix, times, times, times, timesEquals, timesEquals, toString, transpose, zero

Methods inherited from class java.lang.Object

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

Constructor Detail

CorrelationMatrix

public CorrelationMatrix()

Constructor for CorrelationMatrix. Creates a zero values correlation matrix.

CorrelationMatrix

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

Constructor for CorrelationMatrix. 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

CorrelationMatrix

public CorrelationMatrix(java.lang.String strTokens)
                  throws java.lang.IllegalArgumentException,
                         java.lang.NumberFormatException

Constructor for CorrelationMatrix. 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)

CorrelationMatrix

public CorrelationMatrix(Jama.Matrix matInit)
                  throws java.lang.IllegalArgumentException

Constructor for CorrelationMatrix. Takes a symmetric Jama Matrix object to initialize the correlation matrix.

Parameters:

matInit - symmetric Jama Matrix object for initial value

Throws:

java.lang.IllegalArgumentException - initializing matrix is not symmetric

Method Detail

newZero

public static CorrelationMatrix newZero()

Create a new instance of a zero phase matrix.

Returns:

zero vector

newIdentity

public static CorrelationMatrix newIdentity()

Create an identity correlation matrix

Returns:

7x7 real identity matrix

buildCorrelation

public static CorrelationMatrix buildCorrelation(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

buildCorrelation

public static CorrelationMatrix buildCorrelation(Twiss twissX,
                                                 Twiss twissY,
                                                 Twiss twissZ,
                                                 PhaseVector vecMean)

Create a CorrelationMatrix corresponding to the given Twiss parameters and having the given mean values (centroid values). 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

vecMean - mean value vector of the phase space coordinates, i.e.,

Returns:

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

setRmsEmittances

public void setRmsEmittances(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 included in the correlation. These values are extracted and returned as a vector.

Returns:

PhaseVector representing the mean values of the correlation

getCovXX

public double getCovXX()

Compute and return the covariance value of the xx phase space coordinate monomial.

Returns:

the value <x^2>-<x>^2

getCovXY

public double getCovXY()

Compute and return the covariance value of the xy phase space coordinate monomial.

Returns:

the value <xy>-<x><y>

getCovYY

public double getCovYY()

Compute and return the covariance value of the yy phase space coordinate monomial.

Returns:

the value <y^2>-<y>^2

getCovYZ

public double getCovYZ()

Compute and return the covariance value of the yz phase space coordinate monomial.

Returns:

the value <yz>-<y><z>

getCovZZ

public double getCovZZ()

Compute and return the covariance value of the zz phase space coordinate monomial.

Returns:

the value <z^2>-<z>^2

getCovXZ

public double getCovXZ()

Compute and return the covariance value of the xz phase space coordinate monomial.

Returns:

the value <xz>-<x><z>

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 )

getCovariance

public CorrelationMatrix getCovariance()

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

rmsEmittances

public double[] rmsEmittances()

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

twissParameters

public Twiss[] twissParameters()

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