gov.sns.tools.beam
Class PhaseMatrix

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

All Implemented Interfaces:

IArchive, java.io.Serializable

Direct Known Subclasses:

CorrelationMatrix

public class PhaseMatrix

extends java.lang.Object

implements IArchive, java.io.Serializable

Represents a two-tensor on the space of homogeneous phase space coordinates in three spatial dimensions. Thus, each PhaseMatrix is an element of R7x7, the set of real 7x7 matrices.

The coordinates in homogeneous phase space are as follows: (x, xp, y, yp, z, zp, 1)' where the prime indicates transposition and x = x-plane position xp = x-plane momentum y = y-plane position yp = y-plane momentum z = z-plane position zp = z-plane momentum

Homogeneous coordinates are parameterizations of the projective spaces Pn. They are useful here to allow vector transpositions, normally produced by vector addition, to be represented as matrix multiplications. These operations can be embodied by PhaseMatrix. Thus, PhaseMatrix objects can represent any linear operation, including translation, on PhaseVector objects.

See Also:

Matrix, PhaseVector, CorrelationMatrix, Serialized Form

Field Summary

static java.lang.String	ATTR_DATA attribute marker for data
static int	DIM number of dimensions (DIM=7)
static int	IND_HOM index of homogeneous coordinate
static int	IND_X index of x position
static int	IND_XP index of x' position
static int	IND_Y index of y position
static int	IND_YP index of y' position
static int	IND_Z index of z position
static int	IND_ZP index of z' position

Constructor Summary

PhaseMatrix()
Creates a new instance of PhaseMatrix initialized to zero.

PhaseMatrix(Jama.Matrix matInit)
Construct a PhaseMatrix from a suitable Jama.Matrix.

PhaseMatrix(PhaseMatrix matInit)
Copy Constructor - create a deep copy of the target phase matrix.

PhaseMatrix(java.lang.String strValues)
Parsing Constructor - create a PhaseMatrix instance and initialize it according to a token string of element values.

Method Summary

R3	compPhaseAdvance(Twiss[] twissOld, Twiss[] twissNew) Compute and return the betatron phase advance for a particle produced by this matrix when used as a transfer matrix.
PhaseMatrix	conjugateInv(PhaseMatrix matPhi) Function for inverse conjugation of this matrix by the argument matrix.
PhaseMatrix	conjugateTrans(PhaseMatrix matPhi) Function for transpose conjugation of this matrix by the argument matrix.
double	det() Matrix determinant function.
boolean	equals(java.lang.Object o) Return true if this object is equal to o, false otherwise.
double	getElem(int i, int j) Return matrix element value.
int	hashCode() "Borrowed" implementation from AffineTransform, since it is based on double attribute values.
static PhaseMatrix	identity() Create an identity phase matrix
PhaseMatrix	inverse() Nondestructive inverse of this matrix.
void	load(DataAdaptor daptArchive) Restore the value of the this PhaseMatrix from the contents of a data archive.
static void	main(java.lang.String[] arrArgs) Testing Driver
PhaseMatrix	minus(PhaseMatrix mat) Nondestructive matrix subtraction.
void	minusEquals(PhaseMatrix mat) In-place matrix subtraction.
double	norm1() Return the l1 norm of this matrix.
double	norm2() Return the l2 norm of this matrix
double	normInf() Return the l-infinity norm of this matrix
static PhaseMatrix	parse(java.lang.String strTokens) Create a PhaseMatrix instance and initialize it according to a token string of element values.
PhaseMatrix	plus(PhaseMatrix mat) Nondestructive matrix addition.
void	plusEquals(PhaseMatrix mat) In-place matrix addition.
void	print(java.io.PrintWriter os) Print out the contents of the PhaseMatrix in text format.
void	save(DataAdaptor daptArchive) Save the value of this PhaseMatrix to a data sink represented by the DataAdaptor interface.
void	setElem(int i, int j, double s) Element assignment - assigns matrix element to the specified value
void	setMatrix(java.lang.String strValues) Parsing assigment - set the PhaseMatrix value according to a token string of element values.
void	setSubMatrix(int i0, int i1, int j0, int j1, double[][] arrSub) Set a submatrix within the phase matrix.
PhaseMatrix	times(double s) Nondestructive scalar multiplication.
PhaseMatrix	times(PhaseMatrix matRight) Matrix multiplication.
PhaseVector	times(PhaseVector vec) Nondestructive Matrix-Vector multiplication.
void	timesEquals(double s) In-place scalar multiplication.
void	timesEquals(PhaseMatrix matRight) In-place matrix multiplication.
java.lang.String	toString() Convert the contents of the matrix to a string representation.
PhaseMatrix	transpose() Nondestructive transpose of this matrix.
static PhaseMatrix	zero() Create a new instance of a zero phase matrix.

Methods inherited from class java.lang.Object

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

Field Detail

IND_X

public static final int IND_X

index of x position

See Also:

Constant Field Values

IND_XP

public static final int IND_XP

index of x' position

See Also:

Constant Field Values

IND_Y

public static final int IND_Y

index of y position

See Also:

Constant Field Values

IND_YP

public static final int IND_YP

index of y' position

See Also:

Constant Field Values

IND_Z

public static final int IND_Z

index of z position

See Also:

Constant Field Values

IND_ZP

public static final int IND_ZP

index of z' position

See Also:

Constant Field Values

IND_HOM

public static final int IND_HOM

index of homogeneous coordinate

See Also:

Constant Field Values

DIM

public static final int DIM

number of dimensions (DIM=7)

See Also:

Constant Field Values

ATTR_DATA

public static final java.lang.String ATTR_DATA

attribute marker for data

See Also:

Constant Field Values

Constructor Detail

PhaseMatrix

public PhaseMatrix()

Creates a new instance of PhaseMatrix initialized to zero.

PhaseMatrix

public PhaseMatrix(PhaseMatrix matInit)

Copy Constructor - create a deep copy of the target phase matrix.

Parameters:

matInit - initial value

PhaseMatrix

public PhaseMatrix(java.lang.String strValues)
            throws java.lang.IllegalArgumentException,
                   java.lang.NumberFormatException

Parsing Constructor - create a PhaseMatrix instance and initialize it according to a token string of element values. The token string argument is assumed to be one-dimensional and packed by column (ala FORTRAN).

Parameters:

strValues - token vector of 7x7=49 numeric values

Throws:

java.lang.IllegalArgumentException - wrong number of token strings

java.lang.NumberFormatException - bad number format, unparseable

See Also:

setMatrix(java.lang.String)

PhaseMatrix

public PhaseMatrix(Jama.Matrix matInit)

Construct a PhaseMatrix from a suitable Jama.Matrix. Note that the argument should be a new object not owned by another object, because the internal matrix representation is assigned to the target argument.

Parameters:

matInit - a 7x7 Jama.Matrix object

Method Detail

zero

public static PhaseMatrix zero()

Create a new instance of a zero phase matrix.

Returns:

zero vector

identity

public static PhaseMatrix identity()

Create an identity phase matrix

Returns:

7x7 real identity matrix

parse

public static PhaseMatrix parse(java.lang.String strTokens)
                         throws java.lang.IllegalArgumentException,
                                java.lang.NumberFormatException

Create a PhaseMatrix instance and initialize it according to a token string of element values. The token string argument is assumed to be one-dimensional and packed by column (ala FORTRAN).

Parameters:

strTokens - token vector of 7x7=49 numeric values

Throws:

java.lang.IllegalArgumentException - wrong number of token strings

java.lang.NumberFormatException - bad number format, unparseable

getElem

public double getElem(int i,
                      int j)
               throws java.lang.ArrayIndexOutOfBoundsException

Return matrix element value. Get matrix element value at specified index

Parameters:

i - row index

j - column index

Throws:

java.lang.ArrayIndexOutOfBoundsException - index must be in {0,1,2,3,4,5,6}

setMatrix

public void setMatrix(java.lang.String strValues)
               throws DataFormatException,
                      java.lang.IllegalArgumentException

Parsing assigment - set the PhaseMatrix value according to a token string of element values. The token string argument is assumed to be one-dimensional and packed by column (ala FORTRAN).

Parameters:

strValues - token vector of 7x7=49 numeric values

Throws:

java.lang.IllegalArgumentException - wrong number of token strings

java.lang.NumberFormatException - bad number format, unparseable

DataFormatException

setElem

public void setElem(int i,
                    int j,
                    double s)
             throws java.lang.ArrayIndexOutOfBoundsException

Element assignment - assigns matrix element to the specified value

Parameters:

i - row index

j - column index

Throws:

java.lang.ArrayIndexOutOfBoundsException - index must be in {0,1,2,3,4,5,6}

setSubMatrix

public void setSubMatrix(int i0,
                         int i1,
                         int j0,
                         int j1,
                         double[][] arrSub)
                  throws java.lang.ArrayIndexOutOfBoundsException

Set a submatrix within the phase matrix.

Parameters:

i0 - row index of upper left block

i1 - row index of lower right block

j0 - column index of upper left block

j1 - column index of lower right block

arrSub - two-dimensional sub element array

Throws:

java.lang.ArrayIndexOutOfBoundsException - submatrix does not fit into 7x7 phase matrix

save

public void save(DataAdaptor daptArchive)

Save the value of this PhaseMatrix to a data sink represented by the DataAdaptor interface.

Specified by:

save in interface IArchive

Parameters:

daptArchive - interface to data sink

See Also:

IArchive.save(gov.sns.tools.data.DataAdaptor)

load

public void load(DataAdaptor daptArchive)
          throws DataFormatException

Restore the value of the this PhaseMatrix from the contents of a data archive.

Specified by:

load in interface IArchive

Parameters:

daptArchive - interface to data source

Throws:

DataFormatException - malformed data

java.lang.IllegalArgumentException - wrong number of string tokens

See Also:

IArchive.load(gov.sns.tools.data.DataAdaptor)

equals

public boolean equals(java.lang.Object o)

Return true if this object is equal to o, false otherwise.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

"Borrowed" implementation from AffineTransform, since it is based on double attribute values. Must implement hashCode to be consistent with equals as specified by contract of hashCode in Object.

Overrides:

hashCode in class java.lang.Object

Returns:

a hashCode for this object

compPhaseAdvance

public R3 compPhaseAdvance(Twiss[] twissOld,
                           Twiss[] twissNew)

Compute and return the betatron phase advance for a particle produced by this matrix when used as a transfer matrix.

Returns:

vector (sigx,sigy,sigz) of phase advances in radians

det

public double det()

Matrix determinant function.

Returns:

det(this)

transpose

public PhaseMatrix transpose()

Nondestructive transpose of this matrix.

Returns:

transposed matrix

inverse

public PhaseMatrix inverse()

Nondestructive inverse of this matrix.

Returns:

the algebraic inverse of this matrix

plus

public PhaseMatrix plus(PhaseMatrix mat)

Nondestructive matrix addition.

Parameters:

mat - matrix to be added to this

Returns:

this + mat (elementwise)

plusEquals

public void plusEquals(PhaseMatrix mat)

In-place matrix addition.

Parameters:

mat - matrix to be added to this (result replaces this)

minus

public PhaseMatrix minus(PhaseMatrix mat)

Nondestructive matrix subtraction.

Parameters:

mat - matrix to be subtracted from this

Returns:

this - mat (elementwise)

minusEquals

public void minusEquals(PhaseMatrix mat)

In-place matrix subtraction.

Parameters:

mat - matrix to be subtracted from this (result replaces this)

times

public PhaseMatrix times(double s)

Nondestructive scalar multiplication.

Parameters:

s - scalar value to multiply this matrix

Returns:

new matrix equal to s*this

timesEquals

public void timesEquals(double s)

In-place scalar multiplication.

Parameters:

s - scalar value to multiply this matrix (result replaces this)

times

public PhaseVector times(PhaseVector vec)

Nondestructive Matrix-Vector multiplication.

Returns:

this*vec

times

public PhaseMatrix times(PhaseMatrix matRight)

Matrix multiplication.

Parameters:

matRight - right operand of matrix multiplication operator

Returns:

this*matRight

timesEquals

public void timesEquals(PhaseMatrix matRight)

In-place matrix multiplication.

Parameters:

matRight - right operand of matrix multiplication operator

Returns:

this*matRight

conjugateTrans

public PhaseMatrix conjugateTrans(PhaseMatrix matPhi)

Function for transpose conjugation of this matrix by the argument matrix. This method is nondestructive, return a new matrix.

Parameters:

matPhi - conjugating matrix (typically a tranfer matrix)

Returns:

matPhi*this*matPhi^T

conjugateInv

public PhaseMatrix conjugateInv(PhaseMatrix matPhi)

Function for inverse conjugation of this matrix by the argument matrix. This method is nondestructive, return a new matrix.

Parameters:

matPhi - conjugating matrix (typically a tranfer matrix)

Returns:

matPhi*this*matPhi^-1

norm1

public double norm1()

Return the l1 norm of this matrix.

Returns:

||M||_1 = Sum |m_ij|

norm2

public double norm2()

Return the l2 norm of this matrix

Returns:

||M||_2 = [ Sum (m_ij)^2 ]^1/2

normInf

public double normInf()

Return the l-infinity norm of this matrix

Returns:

||M||_inf = sup_ij |m_ij|

toString

public java.lang.String toString()

Convert the contents of the matrix to a string representation. The format is similar to that of Mathematica, e.g. { {a b }{c d } }

Overrides:

toString in class java.lang.Object

Returns:

string representation of the matrix

print

public void print(java.io.PrintWriter os)

Print out the contents of the PhaseMatrix in text format.

Parameters:

os - output stream to receive text dump

main

public static void main(java.lang.String[] arrArgs)

Testing Driver