NMath User's Guide

TOC | Previous | Next | Index

18.6 Functions of Matrices (.NET, C#, CSharp, VB, Visual Basic, F#)

NMath provides a variety of functions that take structured sparse matrices as arguments.

Matrix Transposition

The structured sparse matrix classes provide Transpose() member functions for calculating the transpose of a matrix: B[i,j] = A[j,i]. Class MatrixFunctions also provides a static Transpose() method that returns the transpose of a matrix. Data is copied. For instance:

Code Example – C# matrix

var A = new FloatTriDiagMatrix( 50, 50 );
A.Diagonal(1)++;    // increments the superdiagonal
A.Diagonal(-1)--;   // decrements the subdiagonal
FloatTriDiagMatrix B = A.Transpose();
FloatTriDiagMatrix C = MatrixFunctions.Transpose( A );   // B == C

Code Example – VB matrix

Dim A As New FloatTriDiagMatrix(50, 50)
A.Diagonal(1).Increment()    ' increments the superdiagonal
A.Diagonal(-1).Decrement()   ' decrements the subdiagonal
Dim B As FloatTriDiagMatrix = A.Transpose()
Dim C As FloatTriDiagMatrix = MatrixFunctions.Transpose(A) ' B == C

NOTE—By definition, a symmetric matrix is equal to its own transpose, so the Trans­pose() method has no effect for these types.

Matrix Inner Products

Class MatrixFunctions provides the static Product() method for calculating the inner product of a matrix and a vector:

Code Example – C# matrix

var data = new DoubleVector( 10, 1, 1 );
var A = new DoubleSymmetricMatrix( data, 4 );
var x = new DoubleVector( 4, 1, 1 );
DoubleVector y = MatrixFunctions.Product( A, x );

Code Example – VB matrix

Dim Data As New DoubleVector(10, 1.0, 1.0)
Dim A As New DoubleSymmetricMatrix(Data, 4)
Dim X As New DoubleVector(4, 1.0, 1.0)
Dim Y As DoubleVector = MatrixFunctions.Product(A, X)

For banded matrices, additional overloads of the Product() method calculate the product of two matrices. For example:

Code Example – C# matrix

int rows = 8, cols = 6, lb = 2, ub = 1;
DoubleComplexVector data =
  new DoubleComplexVector( (ub+lb+1)*cols, 0, 1 );
DoubleComplexBandMatrix A =
  new DoubleComplexBandMatrix( data, rows, cols, lb, ub );
DoubleComplexBandMatrix B =
  new DoubleComplexBandMatrix( ++data, cols, cols, lb, ub );
DoubleComplexBandMatrix C =
  MatrixFunctions.Product( A, B );

Code Example – VB matrix

Dim Rows As Integer = 8
Dim Cols As Integer = 6
Dim LB As Integer = 2
Dim UB As Integer = 1
Dim Data As New DoubleComplexVector((UB + LB + 1) * Cols, 0, 1)
Dim A As New DoubleComplexBandMatrix(Data, Rows, Cols, LB, UB)
Dim B As New DoubleComplexBandMatrix(Data.Increment(), Cols, Cols, 
  LB, UB)
Dim C As DoubleComplexBandMatrix = MatrixFunctions.Product(A, B)

Also for banded matrices, the static TransposeProduct() method on NMathFunctions computes the matrix inner product of the transpose of a given matrix and a second matrix. Thus, assuming A and B are DoubleBandMatrix instances, this code calculates the inner product of the transpose of A with B:

Code Example – C# matrix

DoubleBandMatrix C = MatrixFunctions.TransposeProduct( A, B );

Code Example – VB matrix

Dim C As DoubleBandMatrix = MatrixFunctions.TransposeProduct(A, B)

Matrix Norms

MatrixFunctions provides static functions OneNorm() to compute the 1-norm (or largest column sum) of a matrix, and InfinityNorm() to compute the infinity-norm (or largest row sum) of a matrix. For instance:

Code Example – C# matrix

var A = new DoubleMatrix( "3x3 [1 2 3  4 5 6  7 8 9]" );
double d1 = A.OneNorm();
double d2 = A.InfinityNorm();

Code Example – VB matrix

Dim A As New DoubleMatrix("3x3 [1 2 3  4 5 6  7 8 9]")
Dim D1 As Double = A.OneNorm()
Dim D2 As Double = A.InfinityNorm()

The OneNorm() method has overloads for all structured sparse matrix types; InfinityNorm() only for banded and tridiagonal types.

Trigonometric and Transcendental Functions

In general, NMath does not provide trigonometric and transcendental functions for sparse matrix types. Such functions may change unstored zero values to non-zero values, thus changing a sparse matrix type into a general matrix. If you want to apply a trigonometric or transcendental function to all elements of a sparse matrix, including unstored zero values, convert the matrix to a general matrix first, using the ToGeneralMatrix() method. Alternatively, to apply a trigonometric or transcendental function only to stored values, apply the function to the underlying data vector. These techniques are described in more detail in Section 18.7.

Symmetric matrices are in a different category than the other sparse matrix types, because unstored values are not constrained to be zero. Therefore, NMath extends standard trigonometric functions Acos(), Asin(), Atan(), Cos(), Cosh(), Sin(), Sinh(), Tan(), and Tanh() to take symmetric matrix arguments. Class MatrixFunctions provides these functions as static methods. For instance, this code construct a symmetric matrix whose contents are the cosines of another symmetric matrix:

Code Example – C# matrix

var genMat = new FloatMatrix( 10, 10, 0, Math.Pi/4 );
var A = new FloatSymmetricMatrix( genMat );
FloatSymmetricMatrix cosA = MatrixFunctions.Cos( A );

Code Example – VB matrix

Dim GenMat As New FloatMatrix(10, 10, 0.0F, Math.PI / 4.0F)
Dim A As New FloatSymmetricMatrix(GenMat)
Dim CosA As FloatSymmetricMatrix = MatrixFunctions.Cos(A)

The static Atan2() method takes two symmetric matrices and applies the two-argument arc tangent function to corresponding pairs of elements.

MatrixFunctions also provides standard transcendental functions Log() and Log10() that take symmetric matrix arguments.

Absolute Value

The static Abs() function on class MatrixFunctions applies the absolute value function to each element of a given matrix:

Code Example – C# matrix

int order = 5, hb = 2;
var data = new DoubleComplexVector( "(0,0) (0,0) 
  (1,-2) (0,0) (2,-4) (3,-6) (4,-8) (5,-10) (6,-12) (7,-14) (8,-16) 
  (9,-18) (10,-20) (11,-22) (12,-24)" );
var A = new DoubleHermitianBandMatrix( data, order, hb );
DoubleSymBandMatrix B = MatrixFunctions.Abs( A );

Code Example – VB matrix

Dim Order As Integer = 5
Dim HB As Integer = 2
Dim Data As New DoubleComplexVector("(0,0) (0,0) " & _
  "(1,-2) (0,0) (2,-4) (3,-6) (4,-8) (5,-10) (6,-12) (7,-14) " &
  "(8,-16) (9,-18) (10,-20) (11,-22) (12,-24)")
Dim A As New DoubleHermitianBandMatrix(Data, Order, HB)
Dim B As DoubleSymBandMatrix = MatrixFunctions.Abs(A)

Complex Matrix Functions

Static methods Real() and Imag() on class MatrixFunctions return the real and imaginary part of the elements of a matrix. If the elements of the given matrix are real, Real() simply returns the given matrix and Imag() returns a matrix of the same dimensions containing all zeros.

Static methods Arg() and Conj() on class MatrixFunctions return the arguments (or phases) and complex conjugates of the elements of a matrix. If the elements of the given matrix are real, both methods simply return the given matrix.

For instance:

Code Example – C# matrix

var initValue = new FloatComplex( 1, -1.5F );
var increment = new FloatComplex( 1, 0.25F );
var getMat = new FloatComplexMatrix( 7, 6, initValue, increment );
var A = new FloatComplexTriDiagMatrix( getMat );

FloatTriDiagMatrix AImag = MatrixFunctions.Imag( A );

Code Example – VB matrix

Dim InitValue As New FloatComplex(1, -1.5F)
Dim Increment As New FloatComplex(1, 0.25F)
Dim GetMat As New FloatComplexMatrix(7, 6, InitValue, Increment)
Dim A As New FloatComplexTriDiagMatrix(GetMat)

Dim AImag As FloatTriDiagMatrix = MatrixFunctions.Imag(A)