3.1 Creating Matrices

This section describes how to create instances of the structured sparse matrix classes.

Creating Default Matrices

You can construct default structured sparse matrices by supplying the necessary parameters to describe the matrix shape, as shown in Table 2. All stored values are initialized to zero.

Square matrix types are characterized by their order--that is, the number of rows and columns. For example, a matrix of order 3 is a 3 x 3 matrix. Thus, this code creates a default 5 x 5 Hermitian matrix of double-precision complex numbers:

DoubleHermitianMatrix A = new DoubleHermitianMatrix( 5 );

Constructors for rectangular matrix types accept separate row and column shape parameters. For example:

DoubleTriDiagMatrix A = new DoubleTriDiagMatrix ( 3, 5 );

Constructors for banded matrix types also accept bandwidth parameters that describe the width of the banded region. Thus, the following code creates a 4 x 5 FloatComplexBandMatrix with a lower bandwidth of 1 and an upper bandwidth of 2:

FloatComplexBandMatrix A =
   new FloatComplexMatrixMatrix( 4, 5, 1, 2 );

This creates an 8 x 8 FloatSymBandMatrix with a half bandwidth of 2:

FloatSymBandMatrix A = new FloatSymBandMatrix( 8, 2 );

Once you've constructed a default matrix, you can set individual values using the provided indexers (Section 3.2). In some case, methods are also provided that return vector views of the underlying data, which can also be used to set matrix values (Section 3.5).

Creating Sparse Matrices from General Matrices

You can construct all NMath Matrix structured sparse matrix types from NMath Core general matrix types. Such constructors extract the appropriate values from the general matrix. Data is copied.

For example, this code constructs a FloatUpperTriMatrix instance by extracting the upper triangular region of a square general matrix:

FloatMatrix getMat = new FloatMatrix( 5, 5, 0, 1 );
FloatUpperTriMatrix A = new FloatUpperTriMatrix( genMat );

Constructors for square matrix types, such as upper triangular matrices, throw a MatrixNotSquareException if the given general matrix is not square. Alternatively, you can pass in a non-square general matrix and specify the order of the square submatrix to extract. Thus, this code creates a 3 x 3 DoubleSymmetricMatrix by extracting the upper triangular region of the 3 x 3 leading submatrix from the given 4 x 6 general matrix:

DoubleMatrix genMat = new DoubleMatrix( 4, 6, 0, 0.25 );
DoubleSymmatricMatrix A = new DoubleSymmetricMatrix( A, 3 );

An IndexOutOfRangeException is raised if the given order specifies a submatrix that is out of bounds.

Banded matrix types can also be constructed from general matrices by specifying the desired bandwidth. For instance, the following code extracts the values required to construct a Hermitian banded matrix with a half bandwidth of 3 from the given general matrix:

DoubleComplex incr = new DoubleComplex( 1, 0.25 );
DoubleComplexMatrix genMat =
   new DoubleComplexMatrix( 12, 12, 0, incr );
DoubleHermitianBandMatrix A =
   new DoubleHermitianBandMatrix( A, 3 );

Creating Sparse Matrices from Other Sparse Matrices

Some structured sparse matrix types can be constructed from other structured sparse matrices. For example, a tridiagonal matrix is really a special case of a banded matrix with lower and upper bandwidth equal to 1. Therefore, banded matrices can be constructed from tridiagonal matrices, and vice versa. For example:

int rows = 8, cols = 8, ub = 0, lb = 2;
FloatVector data = new FloatVector( (ub+lb+1)*cols, 1, 1 );
FloatBandMatrix A =
  new FloatBandMatrix( data, rows, cols, lb, ub );
FloatTriDiagMatrix B = new FloatTriDiagMatrix( A );

Similarly, you can construct banded matrices from symmetric or Hermitian banded matrices, or triangular matrices from symmetric or Hermitian matrices, and vice versa.

Creating Sparse Matrices from a Data Vector

You can construct all NMath Matrix structured sparse matrix types from an appropriate data vector and shape parameters. The vector storage scheme used by each structured sparse matrix type is described in Chapter 2. For example, you could create this 4 x 4 symmetric matrix:

like this:

DoubleVector data = new DoubleVector( 10, 0, 1 );
DoubleSymmetricMatrix A = new DoubleSymmetricMatrix( data, 4 );

Similarly, you could create this 5 x 7 banded matrix with an upper bandwidth of 1 and a lower bandwidth of 0:

using this code:

FloatVector data = new FloatVector( 14, 1 );
FloatBandMatrix A = new FloatBandMatrix( data, 5, 7, 0, 1 );

Implicit Conversion

NMath Matrix provides implicit conversion operators for the structured sparse matrix classes. Single-precision types are implicitly promoted to double-precision types, and real types are implicitly promoted to complex types, as shown in Figure 1. An arrow indicates implicit promotion.

Figure 1 - Implicit conversion for matrix data types

For example, Figure 2 shows the pattern for implicit conversion among the tridiagonal types.

Figure 2 - Implicit conversion for tridiagonal matrices

Copying Matrices

The NMath Matrix structured sparse matrix classes provide three copy methods:

• Clone() returns a deep copy of a matrix. Data is copied; each matrix references different data.
• ShallowCopy() returns a shallow copy of a matrix. Data is not copied; both matrices reference the same data.
• DeepenThisCopy() copies the data viewed by a matrix to new data block. This guarantees that there is only one reference to the underlying data, and that this data is in contiguous storage.

For instance:

FloatUpperTriMatrix A = new FloatUpperTriMatrix( 5 );
FloatUpperTriMatrix B = A.ShallowCopy();

B[0,0] = 1;   // A[0,0] == B[0,0]
B.DeepenThisCopy();
B[0,0] = 2;   // A[0,0] != B[0,0]

TOC |  Previous |  Next |  Index