xal.tools.beam

Class PhaseMatrix

java.lang.Object

xal.tools.math.BaseMatrix<M>

xal.tools.math.SquareMatrix<PhaseMatrix>

xal.tools.beam.PhaseMatrix

All Implemented Interfaces:

java.io.Serializable, IArchive

Direct Known Subclasses:

CovarianceMatrix, TranslationMatrix

public class PhaseMatrix
extends SquareMatrix<PhaseMatrix>
implements java.io.Serializable

Class .

Since:

Oct 16, 2013

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PhaseMatrix.IND Enumeration for the element position indices of a homogeneous phase space objects.

Field Summary

Fields

Modifier and Type	Field and Description
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
static int	INT_SIZE number of dimensions (DIM=7)

Fields inherited from class xal.tools.math.BaseMatrix

ATTR_DATA, matImpl

Constructor Summary

Constructors

Constructor and Description
PhaseMatrix() Creates a new instance of PhaseMatrix initialized to zero.
PhaseMatrix(DataAdaptor daSource) Create a new PhaseMatrix object and initialize with the data source behind the DataAdaptor interface.
PhaseMatrix(double[][] arrValues) Initializing constructor for class PhaseMatrix.
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

Modifier and Type	Method and Description
PhaseMatrix	clone() Creates and returns a deep copy of this matrix.
void	homogenize() Explicitly enforce the homogeneous nature of this matrix.
static PhaseMatrix	identity() Create an identity phase matrix
double	max() We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate.
PhaseMatrix	minus(PhaseMatrix matSub) Non-destructive matrix subtraction.
void	minusEquals(PhaseMatrix matSub) In-place matrix subtraction.
protected PhaseMatrix	newInstance() Handles object creation required by the base class.
double	norm1() We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate.
double	norm2() We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate.
double	normF() We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate.
double	normInf() We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate.
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 matAddend) Non-destructive matrix addition.
void	plusEquals(PhaseMatrix matAddend) In-place matrix addition.
R6	projectColumn(int j) Projects the jth column onto R6.
R6	projectColumn(PhaseMatrix.IND j) Projects the jth column onto R6.
R4x4	projectR4x4() Projects the PhaseMatrix onto the space of 4×4 matrices.
R6x6	projectR6x6() Projects the PhaseMatrix onto the space of 6×6 matrices.
R6	projectRow(int i) Projects the ith row onto R6.
R6	projectRow(PhaseMatrix.IND i) Projects the ith row onto R6.
static PhaseMatrix	rotationProduct(R3x3 matSO3) Compute the rotation matrix in phase space that is essentially the Cartesian product of the given rotation matrix in SO(3).
void	setElem(PhaseMatrix.IND iRow, PhaseMatrix.IND iCol, double s) Element assignment - assigns matrix element to the specified value
static PhaseMatrix	spatialTranslation(R3 vecDispl) Create a phase matrix representing a linear translation operator on homogeneous phase space that only affects the spatial coordinates.
static PhaseMatrix	translation(PhaseVector vecTrans) Create a phase matrix representing a linear translation operator on homogeneous phase space.
static PhaseMatrix	zero() Create a new instance of a zero phase matrix.

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

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

INT_SIZE

public static final int INT_SIZE

number of dimensions (DIM=7)

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(DataAdaptor daSource)
            throws DataFormatException

Create a new PhaseMatrix object and initialize with the data source behind the DataAdaptor interface.

Parameters:

daSource - data source containing initialization data

Throws:

DataFormatException - malformed data

See Also:

IArchive.load(xal.tools.data.DataAdaptor)

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:

BaseMatrix.setMatrix(java.lang.String)

PhaseMatrix

public PhaseMatrix(double[][] arrValues)
            throws java.lang.ArrayIndexOutOfBoundsException

Initializing constructor for class PhaseMatrix. The values of the new matrix object are set to the given Java primitive type array (the array is not modified).

Parameters:

arrValues - initial values for the new matrix

Throws:

java.lang.ArrayIndexOutOfBoundsException - the argument must have dimensions 7×7

Since:

Oct 7, 2013

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

translation

public static PhaseMatrix translation(PhaseVector vecTrans)

Create a phase matrix representing a linear translation operator on homogeneous phase space. Multiplication by the returned PhaseMatrix object is equivalent to translation by the given PhaseVector argument. Specifically, if the argument Δ has coordinates

Δ = (Δx, Δx', Δdy, Δdy', Δdz, Δdz', 1)^T

then the returned matrix T(Δ) has the form

 
          |1 0 0 0 0 0 Δx |
          |0 1 0 0 0 0 Δx'|
   T(Δ) = |0 0 1 0 0 0 Δy |
          |0 0 0 1 0 0 Δy'|
          |0 0 0 0 1 0 Δz |
          |0 0 0 0 0 1 Δz'|
          |0 0 0 0 0 0  1 |
 

Consequently, given a phase vector v of the form

          |x |
          |x'|
      v = |y |
          |y'|
          |z |
          |z'|
          |1 |
 

Then operation on v by T(Δ) has the result

           |x + Δx |
           |x'+ Δx'|
   T(Δ)v = |y + Δy |
           |y'+ Δy'|
           |z + Δz |
           |z'+ Δz'|
           |  1    |
 

which we see is equivalent to the simple vector addition v + Δ.

Parameters:

vecTrans - translation vector Δ

Returns:

translation operator T(Δ) as a phase matrix

spatialTranslation

public static PhaseMatrix spatialTranslation(R3 vecDispl)

Create a phase matrix representing a linear translation operator on homogeneous phase space that only affects the spatial coordinates. Multiplication by the returned PhaseMatrix object is equivalent to translation by the given R3 argument projected into phase space. Specifically, if the argument Δ has coordinates

Δ = (Δx, Δdy, Δdz)^T

then the returned matrix T(dv) has the form

 
          |1 0 0 0 0 0 Δx|
          |0 1 0 0 0 0 0 |
  T(dv) = |0 0 1 0 0 0 Δy|
          |0 0 0 1 0 0 0 |
          |0 0 0 0 1 0 Δz|
          |0 0 0 0 0 1 0 |
          |0 0 0 0 0 0  1|
 

which is the translation operator in phase space restricted to the spatial coordinates.

See translation(PhaseVector) for further discussion of translation operators and their representation by homogeneous phase-space matrices.

Parameters:

vecDispl - the spatial displacement vector Δ

Returns:

the translation operator matrix representation T(Δ)

Since:

Aug 25, 2011

See Also:

translation(PhaseVector)

rotationProduct

public static PhaseMatrix rotationProduct(R3x3 matSO3)

Compute the rotation matrix in phase space that is essentially the Cartesian product of the given rotation matrix in SO(3). That is, if the given argument is the rotation O, the returned matrix, denoted M, is the M = O×O×I embedding into homogeneous phase space R^6×6×{1}. Thus, M ∈ SO(6) ⊂ R^6×6×{1}.

Viewing phase-space as a 6D manifold built as the tangent bundle over R³ configuration space, then the fibers of 3D configuration space at a point (x,y,z) are represented by the Cartesian planes (x',y',z'). The returned phase matrix rotates these fibers in the same manner as their base point (x,y,z).

This is a convenience method to build the above rotation matrix in SO(7).

Parameters:

matSO3 - a rotation matrix in three dimensions, i.e., a member of SO(3) ⊂ R^3×3

Returns:

rotation matrix in S0(7) which is direct product of rotations in S0(3)

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

Returns:

phase matrix with elements initialized by the given numeric tokens

Throws:

java.lang.IllegalArgumentException - wrong number of token strings

java.lang.NumberFormatException - bad number format, unparseable

clone

public PhaseMatrix clone()

Creates and returns a deep copy of this matrix.

Specified by:

clone in class BaseMatrix<PhaseMatrix>

Since:

Jul 3, 2014

See Also:

BaseMatrix.clone()

newInstance

protected PhaseMatrix newInstance()

Handles object creation required by the base class.

Specified by:

newInstance in class BaseMatrix<PhaseMatrix>

Returns:

uninitialized matrix object of type M

Since:

Jun 17, 2014

See Also:

BaseMatrix.newInstance()

setElem

public void setElem(PhaseMatrix.IND iRow,
                    PhaseMatrix.IND iCol,
                    double s)

Element assignment - assigns matrix element to the specified value

Parameters:

iRow - row index

iCol - column index

s - new matrix element value

homogenize

public void homogenize()

Explicitly enforce the homogeneous nature of this matrix. That is, make sure that it is can represent a linear operator on 6D projective space which does not translate vectors. The condition is that the last row and last column consist of all zeros, except for the diagonal element, which is 1.

Since:

Oct 10, 2013

projectR6x6

public R6x6 projectR6x6()

Projects the PhaseMatrix onto the space of 6×6 matrices. The projective dimension of this phase matrix is lost in the projection, that is, the homogeneous coordinate and all the actions associated with it (primarily translations).

This method is useful when the phase matrix represents the statistics of a centered beam, or when it represents a transfer map without any translation.

Returns:

the top 6×6 diagonal block of this matrix

Since:

Oct 16, 2013

projectR4x4

public R4x4 projectR4x4()

Projects the PhaseMatrix onto the space of 4×4 matrices. The projective dimension of this phase matrix is lost in the projection, as is the longitudinal components of the matrix. that is, the last three columns and the last three rows are truncated.

This method is useful when the phase matrix represents the transverse properties of a beam, or when it represents a transverse action on a beam.

Returns:

the top 6×6 diagonal block of this matrix

Since:

Oct 16, 2013

projectRow

public R6 projectRow(PhaseMatrix.IND i)

Projects the i^th row onto R⁶. Specifically, the projective element (the 7^th element in this case) is dropped and that part of the i^th row in the 6 dimensional phase space is returned.

Parameters:

i - index of the matrix row to be returned, i ∈ {0,...,5}

Returns:

matrix row at the above index, less the final projective element

Since:

Oct 16, 2013

See Also:

projectRow(int)

projectRow

public R6 projectRow(int i)

Projects the i^th row onto R⁶. Specifically, the projective element (the 7^th element in this case) is dropped and that part of the i^th row in the 6 dimensional phase space is returned.

Parameters:

i - index of the matrix row to be returned, i ∈ {0,...,5}

Returns:

matrix row at the above index, less the final projective element

Since:

Oct 16, 2013

projectColumn

public R6 projectColumn(PhaseMatrix.IND j)

Projects the j^th column onto R⁶. Specifically, the projective element (the 7^th element in this case) is dropped and that part of the j^th column in the 6 dimensional phase space is returned.

Parameters:

j - index of the matrix column to be returned, j ∈ {0,...,5}

Returns:

matrix row at the above index, less the final projective element

Since:

Oct 16, 2013

See Also:

projectColumn(int)

projectColumn

public R6 projectColumn(int j)

Projects the j^th column onto R⁶. Specifically, the projective element (the 7^th element in this case) is dropped and that part of the j^th column in the 6 dimensional phase space is returned.

Parameters:

j - index of the matrix column to be returned, j ∈ {0,...,5}

Returns:

matrix row at the above index, less the final projective element

Since:

Oct 16, 2013

plus

public PhaseMatrix plus(PhaseMatrix matAddend)

Non-destructive matrix addition. The homogeneous pivot element on the diagonal is unchanged at value 1.

NOTE:

BE VERY CAREFUL when using this function. The homogeneous coordinates are not meant for addition operations.

Overrides:

plus in class BaseMatrix<PhaseMatrix>

Parameters:

matAddend - matrix to be added to this

Returns:

element wise sum of two matrices

plusEquals

public void plusEquals(PhaseMatrix matAddend)

In-place matrix addition. The homogeneous pivot element on the diagonal is unchanged at value 1.

NOTE:

BE VERY CAREFUL when using this function. The homogeneous coordinates are not meant for addition operations.

Overrides:

plusEquals in class BaseMatrix<PhaseMatrix>

Parameters:

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

minus

public PhaseMatrix minus(PhaseMatrix matSub)

Non-destructive matrix subtraction. The homogeneous pivot element on the diagonal is unchanged at value 1.

NOTE:

BE VERY CAREFUL when using this function. The homogeneous coordinates are not meant for subtraction operations.

Overrides:

minus in class BaseMatrix<PhaseMatrix>

Parameters:

matSub - matrix to be subtracted from this one (subtrahend)

Returns:

difference of this matrix and the given one

minusEquals

public void minusEquals(PhaseMatrix matSub)

In-place matrix subtraction. The homogeneous pivot element on the diagonal is unchanged at value 1.

NOTE:

BE VERY CAREFUL when using this function. The homogeneous coordinates are not meant for addition operations.

Overrides:

minusEquals in class BaseMatrix<PhaseMatrix>

Parameters:

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

max

public double max()

We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate. See the base class BaseMatrix for information on the specific norm.

Overrides:

max in class BaseMatrix<PhaseMatrix>

Returns:

max_i,j | A_i,j |

Since:

Nov 21, 2013

See Also:

BaseMatrix.max()

normInf

public double normInf()

We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate. See the base class BaseMatrix for information on the specific norm.

Overrides:

normInf in class BaseMatrix<PhaseMatrix>

Returns:

||M||₁ = max_i Σ_j |M_i,j|

Since:

Nov 21, 2013

See Also:

BaseMatrix.normInf()

norm1

public double norm1()

We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate. See the base class BaseMatrix for information on the specific norm.

Overrides:

norm1 in class BaseMatrix<PhaseMatrix>

Returns:

||M||₁ = max_i Σ_j |M_i,j|

Since:

Nov 21, 2013

See Also:

BaseMatrix.norm1()

norm2

public double norm2()

We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate. See the base class BaseMatrix for information on the specific norm.

Overrides:

norm2 in class BaseMatrix<PhaseMatrix>

Returns:

the maximum singular value of this matrix

Since:

Nov 21, 2013

See Also:

BaseMatrix.norm2()

normF

public double normF()

We must redefine the norm of any matrix on projective space to eliminate the homogeneous coordinate. See the base class BaseMatrix for information on the specific norm.

Overrides:

normF in class BaseMatrix<PhaseMatrix>

Returns:

||A||_F = [ Σ_i,j A_ij² ]^1/2

Since:

Nov 21, 2013

See Also:

BaseMatrix.normF()