Matrix Classes

Back to: Main contents.

Contents

The base index and looping
The class Zmat
The tag classes (Zutmat, Zltmat, Zpsdmat)
The class Zdiagmat
This section is devoted to the matrix classes of Jampack. Matrix classes can be real or complex. Real classes are prefixed with a D (denoting double). Complex classes are prefixed with a Z (denoting double complex). At present all classes are complex.

Matrix classes are also divided into core classes and tag classes. Core classes are those for which all the standard matrix operations are defined. Currently there are two core classes: the Zmat, which represents a general complex matrix, and the Zdiagmat, which represents a complex diagonal matrix. It is planned to add a class to handle band matrices, as well as real versions of the matrix classes.

Tag classes are subclasses of the core classes that inform Jampack of special properties of the matrix in question. For example, the tag class Zutmat specifies that the matrix is complex upper triangular. At present there are three tag classes, Zutmat, Zltmat, and Zpsdmat, all extending Zmat. They specify that the Zmat in question is upper triangular, lower triangular, and positive semidefinite.

The base index and looping

Back to: Main contents, Top of section.

As discussed in the Parameters section each matrix has a base index. If the base index of a matrix A is bx, then the element of the matrix in the northwest corner is abx,bx. Since different disciplines have different indexing conventions, Jampack allows a limited control of the base index. The limitations insure that an application cannot create matrices with different base indices. For more see Parameters.BaseIndex.

The existence of a base index leads to two styles of programming. Suppose the base index is zero and we wish to initialize the elements of an mxn Zmat A to one. One way is the following 

   for (i=0; i<m; i++){
      for (j=0; j<n; j++){
         A.put(i, j, Z.ONE);
      }
   }
(Here the method "put" sets the (i,j)-element of A to the value of its third argument.) We call this style of indexing absolute indexing .

On the other hand, when the Zmat A was created, its constructor set its public class members bx, rx, and cx of A to 0, bx+m-1, bx+n-1, so that we can write the above loop in the form 

   for (i=A.bx; i<=A.rx; i++){
      for (j=A.bx; j<=A.cx; j++){
         A.put(i, j, Z.ONE);
      }
   }
We call this style of indexing relative indexing.

Absolute indexing is more natural that relative indexing, and in most applications it makes no difference which you use--especially, since the method Parameters.adjustBaseIndex can be used to a bring nonconforming matrix in line with its companions. However, if you are writing general purpose code designed to work with any base index, you must use relative indexing.

The class Zmat

Back to: Main contents, Top of section.

The class Zmat (along with its companion to be, the Dmat) is the workhorse of Jampack. It implements a general complex matrix and has a rich variety of constructors. Its methods are restricted to those that manipulate elements and submatrices. General matrix functions like addition and multiplication are handled by special suites of functions like Plus and Times. In what follows A will denote a generic Zmat.

Public members

Zmat has five public members, provided to make relative indexing easy.
int bx
The base index
int rx
The upper row index
int nr
The number of rows
int cx
The upper column index
int nc
The number of columns
These numbers are related by the equations
rx = bx + nr - 1,
cx = bx + nc - 1.

The Jampack convention is that these parameters are never to be altered. But if you think someone has been playing fast and loose with them, you can restore their values by coding 

A.getProperties();

Zmat has the following constructors.

public Zmat(int nrow, int ncol)
Creates a Zmat and initializes it to zero.

public Zmat(double re[][], double im[][])
Creates a Zmat and initializes its real and imaginary parts to a pair of arrays.

public Zmat(Z A[][])
Creates a Zmat and initializes it to an array of class Z.

public Zmat(double A[][])
Creates a Zmat and initializes its real part to to an array of class double. The imaginary part is set to zero.

public Zmat(Zmat A)
Creates a Zmat and initializes it to a Zmat.

public Zmat(Z1 A)
Creates a Zmat and initialize it to a Z1.

public Zmat(Zdiagmat D)
Creates a Zmat and initialize it to a Zdiagmat.

Zmat has a number of methods for retrieving parts of its matrix. In the following descriptions the notation (i1:i2,:) and (:,j1,j2) refers to rows i1...i2 and columns j1...j2 of a matrix. If ii[] is an integer array of length k, then (ii[],:) refers to rows ii[0],...,ii[k-1] of a matrix. Similarly if jj[] is an integer array of length l, then (:,jj[]) refers to rows jj[1],...,jj[l-1] of a matrix. These notations can be mixed to produce submatrices; e.g., (ii[], j1:j2) refers to the submatrix subtended by rows ii[0],...,ii[k-1] and columns, j1,...,j2.

public double[][] getRe()
Returns a copy of the real part of a Zmat.

public double[][] getIm()
Returns a copy of the imaginary part of a Zmat.

public Z[][] getZ()
Returns a copy of the real and imaginary parts as a complex array.

public Z get(int i, int j)
Returns the (i,j)-element of a Zmat.

public Zmat get(int i1, int i2, int j1, int j2)
Returns the submatrix (i1:i2, j1:j2)

public Zmat get(int ii[], int j1, int j2)
Returns the submatrix (ii[], j1:j2).

public Zmat get(int i1, int i2, int jj[])
Returns the submatrix (i1:i2, jj[]).

public Zmat get(int ii[] , int jj[])
Returns the submatrix (ii[], jj[]).
Zmat also contains methods for altering elements and submatrices.

public void put(int i, int j, Z a)
Writes the (i,j) element of a Zmat.

public void put(int i1, int i2, int j1, int j2, Zmat A)
Overwrites the submatrix (i1:i2, j1:j2) with a Zmat.

public void put(int ii[], int j1, int j2, Zmat A)
Overwrites the submatrix (ii[], j1:j2) with a Zmat.

public void put(int i1, int i2, int jj[], Zmat A)
Overwrites the submatrix (i1:i2, jj[]) with a Zmat.

public void put(int ii[] , int jj[], Zmat A)
Overwrites the submatrix (ii[], jj[]) with a Zmat.

Some of the Jampack suites require a matrix decomposition to perform their computations. When they compute the decomposition, they store a pointer to it on the history list of the Zmat in question. To preserve the integrity of the decomposition, it is not directly available to the user. Zmat provides three methods that return decompositions provided they exist.

public Zludpp getLU()
Returns an LU decomposition if a valid one exists. Otherwise returns null.

public Zhqrd getHQR()
Returns a Householder QR decomposition if a valid one exists. Otherwise returns null.

public Zchol getCHOL()
Returns a Cholesky decomposition if a valid one exists. Otherwise returns null.
Note that a call to one of these methods results in the decomposition being removed from the history list of the Zmat.

Implementation details and private members

For reason's explained in the subsection on the class Z1, a Zmat is not implemented as an array of Zs. Instead, the elements of a Zmat are stored in two two-dimensional arrays of type double, one for the real part and the other for the imaginary part. Specifically, the matrix is defined by the following class members.

protected int nrow
The number of rows

protected int ncol
The number of columns

protected int basex
The base index

protected double re[][]
The real part of the matrix

protected double im[][]
The imaginary part of the matrix

The history option is implemented by four data fields and a method. The data fields are

protected boolean dirty
True if the matrix has been altered.

protected Zludpp LU
Points to an LU decomposition if there is one. Otherwise null.

protected Hqrd HQR
Points to a Householder QR decomposition if there is one. Otherwise null.

protected Zludpp CHOL
Points to a Cholesky decomposition if there is one. Otherwise null.
The method is

protected void clean()
Nullifies the history pointers if the matrix is dirty and sets the dirty flag to false.

These members work as follows to insure that decompositions on the history list actually correspond to the matrix in a Zmat. Only Jampack methods can alter a matrix, and by convention any method that alters the matrix sets the dirty flag. Before attempting to use a decomposition on the history list, a Jampack method runs clean(), which nullifies the history list if the matrix is dirty. The method then interrogates the pointer. If it is nonnull, it points to a valid decomposition. If it is null, the method must compute the decomposition from scratch.

To illustrate the use of these data items and clean, here is the code for the function getCHOL. 

public Zchol getCHOL(){
   clean();
   Zchol temp = CHOL;
   CHOL = null;
   return temp;
}
Note that when a user requests a decomposition from history list, it is removed from the list. This prevents the user from altering decompositions on the history list.

The tag classes

Back to: Main contents, Top of section.

Tag classes are subclasses of a matrix class that tell Jampack methods what they can assume about a matrix. Currently all tag classes are subclasses of Zmat. They are

Zltmat
Assume the matrix is lower triangular (or if not square lower trapezoidal).

Zpsdmat
Assume the matrix is Hermitian positive semidefinite.

Zutmat
Assume the matrix is upper triangular (or if not square, upper trapezoidal).
The tag classes are null extensions of Zmat. They have no constructors, data, or methods of their own. They do no error checking, and the user is entirely responsible for seeing that they have the properties they announce.

In point of fact, the casual user is unlikely to encounter tag classes. Most tag class matrices are generated automatically--usually as a part of a decomposition--and the Jampack methods treat them properly without user intervention.

In the course of a reduction, a general Zmat A may become, say, upper triangular. In Java one cannot simply assign the result of the reduction to variable of type Zutmat. Instead one must copy the matrix into a Zutmat: 

Zutmat U = new Zutmat(A)
An alternative is to copy the original matrix into a Zutmat and perform the reduction there.

The class Zdiagmat

Back to: Main contents, Top of section.

The Zdiagmat implements a complex diagonal matrix. In what follows D will denote a generic Zdiagmat.

Public members

Zdiagmat has three public parameters designed to make relative indexing easy.

public int n
The order of the matrix

public int bx
The base index

public int dx
The index of the last diagonal entry
These quantities are related by the following equation.
dx = bx + n - 1.

As with the Zmat, these public values should not be altered. However, if they are you can restore them by coding 

D.getProperties();

Zdiagmat has the following constructors.

public Zdiagmat(int order)
Creates a Zdiagmat and initializes it to zero.

public Zdiagmat(int order, Z val)
Creates a Zdiagmat and initializes it to a constant.

public Zdiagmat(Z1 val)
Creates a Zdiagmat and initializes it to a Z1.

public Zdiagmat(Zmat A, int k)
Creates a Zdiagmat and initializes to to a diagonal of a Zmat. If k=0 the diagonal is the principal diagonal; if k<0, the diagonal is the kth subdiagonal; if k>0, the diagonal is the kth superdiagonal.
Throws a Jampack exception if k is too large or too small.

public Zdiagmat(Zmat A)
Creates a Zdiagmat and initializes it to the principal diagonal of a Zmat.

public Zdiagmat(Zdiagmat D)
Constructs a Zdiagmat and initializes it to another Zdiagmat.

Zdiagmat has two methods to get and retrieve elements.

public Z get(int i)
Returns the ith diagonal element of this Z.

public void put(int ii, Z val)
Writes the ith diagonal element of this Z with val.

Implementation details and private members

The elements of a Zdiagmat are stored in two one-dimensional arrays of type double, one for the real part of the diagonal and the other for the imaginary part. Specifically, the matrix is defined by the following class members.

protected int order
The order of the matrix

protected int basex
The base index

protected double re[]
The real part of the diagonal

protected double im[]
The imaginary part of the diagonal