Package 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:
Serializable, IArchive
Direct Known Subclasses:
CovarianceMatrix, FieldMapIntegrator
public class PhaseMatrix extends SquareMatrix<PhaseMatrix> implements 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 translations, 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.

Since:
March, 2003
Version:
Oct, 2013
Author:
Christopher Allen
See Also:

  • Field Details

  • Constructor Details

    • 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:

    • PhaseMatrix

      public PhaseMatrix(String strValues) throws IllegalArgumentException, 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:
      IllegalArgumentException - wrong number of token strings
      NumberFormatException - bad number format, unparseable
      See Also:

    • PhaseMatrix

      public PhaseMatrix(double[][] arrValues) throws 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:
      ArrayIndexOutOfBoundsException - the argument must have dimensions 7×7
      Since:
      Oct 7, 2013

  • Method Details

    • 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:

    • 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 R6×6×{1}. Thus, M ∈ SO(6) ⊂ R6×6×{1}.

      Viewing phase-space as a 6D manifold built as the tangent bundle over R3 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) ⊂ R3×3
      Returns:
      rotation matrix in S0(7) which is direct product of rotations in S0(3)

    • parse

      public static PhaseMatrix parse(String strTokens) throws IllegalArgumentException, 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:
      IllegalArgumentException - wrong number of token strings
      NumberFormatException - bad number format, unparseable

    • loadFrom

      public static PhaseMatrix loadFrom(DataAdaptor daSource) throws DataFormatException
      Create a new PhaseMatrix object and initialize with the data source behind the given DataAdaptor interface.
      Parameters:
      daSource - data source containing initialization data
      Throws:
      DataFormatException - malformed data
      Since:
      Jan 4, 2016, Christopher K. Allen
      See Also:

    • 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:

    • newInstance

      protected PhaseMatrix newInstance(int row, int cnt)
      Handles object creation required by the base class.
      Specified by:
      newInstance in class BaseMatrix<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.math.BaseMatrix#newInstance()

    • 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 ith row onto R6. Specifically, the projective element (the 7th element in this case) is dropped and that part of the ith 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

      public R6 projectRow(int i)
      Projects the ith row onto R6. Specifically, the projective element (the 7th element in this case) is dropped and that part of the ith 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 jth column onto R6. Specifically, the projective element (the 7th element in this case) is dropped and that part of the jth 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

      public R6 projectColumn(int j)
      Projects the jth column onto R6. Specifically, the projective element (the 7th element in this case) is dropped and that part of the jth 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:
      maxi,j | Ai,j |
      Since:
      Nov 21, 2013
      See Also:

    • 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||1 = maxi Σj |Mi,j|
      Since:
      Nov 21, 2013
      See Also:

    • 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||1 = maxi Σj |Mi,j|
      Since:
      Nov 21, 2013
      See Also:

    • 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:

    • 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 Aij2 ]1/2
      Since:
      Nov 21, 2013
      See Also: