Symmetrical Matrices

Symmetrical matrices are stored in the upper or lower triangular part of a rectangular array. The MatrixTriangle property indicates how elements are stored. It is of type MatrixTriangle and can have values Upper and Lower. The element order is always column major order. Row major storage in the upper triangle is exactly equivalent to column major storage in the lower triangle.

Constructing symmetrical matrices is analogous to triangular matrices, by calling the MatrixCreateSymmetric method. The fact that symmetrical matrices are always square means only one dimension needs to be passed to the method. The method has several overloads.

The simplest overload has just one argument. It constructs a symmetrical matrix with the specified number of rows and columns. All elements are initially set to zero. The element type must be specified as a generic type argument. For example, for a 5x5 symmetrical matrix, we have:

var s1 = Matrix.CreateSymmetric<double>(5);

Dim s1 = Matrix.CreateSymmetric(Of Double)(5)

let s1 = Matrix.CreateSymmetric<double>(5)

The two remaining overloads allow you to initialize the elements of the matrix. The first argument once again specifies the number of rows and columns. The second argument is an array containing the elements of the new matrix. The third argument is of type MatrixTriangle, and indicates whether the elements are taken from the upper or lower triangular part of the element array. The fourth argument is of type MatrixElementOrder, and indicates whether the elements in the array are stored in column-major or row-major order.

double[] elements = { 1, 0, 0, 2, 3, 0, 4, 5, 6 };
var s2 = Matrix.CreateSymmetric(3, elements,
    MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor);
var s3 = Matrix.CreateSymmetric(3, elements,
    MatrixTriangle.Lower, MatrixElementOrder.RowMajor);

Dim elements As Double() = {1, 0, 0, 2, 3, 0, 4, 5, 6}
Dim s2 = Matrix.CreateSymmetric(3, elements,
    MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor)
Dim s3 = Matrix.CreateSymmetric(3, elements,
    MatrixTriangle.Lower, MatrixElementOrder.RowMajor)

let elements = [| 1.0; 0.0; 0.0; 2.0; 3.0; 0.0; 4.0; 5.0; 6.0 |]
let s2 = Matrix.CreateSymmetric(3, elements,
            MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor)
let s3 = Matrix.CreateSymmetric(3, elements,
            MatrixTriangle.Lower, MatrixElementOrder.RowMajor)

The last overload adds one Boolean argument that lets you specify whether the element array should be reused or copied. If the element array is reused, any changes to its elements will result in changes to the corresponding elements of the matrix.

var s4 = Matrix.CreateSymmetric(3, elements,
    MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor, true);

Dim s4 = Matrix.CreateSymmetric(3, elements,
    MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor, True)

let s4 = Matrix.CreateSymmetric(3, elements,
            MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor, true)

The static FromOuterProduct methods return a symmetric matrix that is the product of a matrix with its transpose. An optional second argument of type MatrixOperationSide specifies which of the two operands should be transposed. The default is MatrixOperationSide.Left The following example creates a 2x2 symmetrical matrix that is the product of a 2x3 matrix with its transpose.

var a = Matrix.Create(3, 2, new [] { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 },
    MatrixElementOrder.ColumnMajor);
var s = Extreme.Mathematics.LinearAlgebra.SymmetricMatrix<double>.FromOuterProduct(a);

Dim x = Matrix.Create(3, 2, New Double() {1.0, 2.0, 3.0, 4.0, 5.0, 6.0},
    MatrixElementOrder.ColumnMajor)
Dim s5 = SymmetricMatrix(Of Double).FromOuterProduct(x)

let a = Matrix.Create(3, 2, [| 1.0; 2.0; 3.0; 4.0; 5.0; 6.0 |],
            MatrixElementOrder.ColumnMajor)
let s = Extreme.Mathematics.LinearAlgebra.SymmetricMatrix<double>.FromOuterProduct(a)

The SymmetricMatrixT class has two specific instance methods. The AddOuterProduct method adds the outer product of a vector or a matrix with its transpose to a SymmetricMatrixT. You may supply a scale factor for the outer product, as in the following example:

var A = Matrix.CreateSymmetric<double>(4);
var v = Vector.Create(1.0, 2.0, 3.0, 4.0);
var w = Vector.Create(1.0, 2.0, 3.0, 4.0);
A.AddOuterProduct(2, v);
A.AddSymmetricOuterProduct(1.0, v, w);

Dim A = Matrix.CreateSymmetric(Of Double)(4)
Dim v = Vector.Create(1.0, 2.0, 3.0, 4.0)
Dim w = Vector.Create(1.0, 2.0, 3.0, 4.0)
A.AddOuterProduct(2, v)
A.AddSymmetricOuterProduct(1.0, v, w)

let A = Matrix.CreateSymmetric<double>(4)
let v = Vector.Create(1.0, 2.0, 3.0, 4.0)
let w = Vector.Create(1.0, 2.0, 3.0, 4.0)
A.AddOuterProduct(2.0, v) |> ignore
A.AddSymmetricOuterProduct(1.0, v, w) |> ignore

Complementary to this method is the SubtractOuterProduct method, which subtracts an outer product.

The GetEigenvalues method returns a DenseVectorT that contains the eigenvalues of the matrix. If you also need the eigenvectors, it is more efficient to create a EigenvalueDecompositionT object from the matrix and use its Eigenvalues and Eigenvectors properties.

The ApplyMatrixFunction calculates a matrix function. Its only argument is a FuncT, TResult delegate that specifies the function to calculate. The matrix function is computed by computing the eigenvalue decomposition and applying the function to each of the eigenvalues, and finally computing the matrix with the same eigenvectors but the transformed eigenvalues. The example below calculates the exponential of a 2x2 symmetrical matrix:

var S = Matrix.CreateSymmetric(2, new[] { 1.0, 0.0, 3.0, 4.0 },
    MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor);
var expS = s.ApplyMatrixFunction(Math.Exp);

Dim S = Matrix.CreateSymmetric(2, New Double() {1.0, 0.0, 3.0, 4.0},
    MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor)
Dim expS = s.ApplyMatrixFunction(AddressOf Math.Exp)

let S = Matrix.CreateSymmetric(2, [| 1.0; 0.0; 3.0; 4.0 |],
            MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor)
let expS = s.ApplyMatrixFunction(Func<_,_>(Math.Exp))