Symmetrical Matrices

A SymmetricMatrix<T> represents a matrix whose elements are symmetrical about the main diagonal. A symmetric matrix is equal to its transpose.

How symmetrical matrices are stored

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

Symmetrical matrices are constructed using factory methods in the Matrix class. Since symmetrical matrices are always square, only one dimension needs to be specified.

The simplest way to create a symmetric matrix is with the Matrix.CreateSymmetric method, which constructs a symmetric matrix with all elements initially set to zero. The element type must be specified as a generic type argument. For example, for a 5x5 symmetrical matrix, we have:

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

To create a symmetric matrix from existing data, use the CopyFromSymmetric<T> method. This method copies the data, so changes to the original array will not affect the matrix. The first argument specifies the dimension (number of rows and columns). The second argument is an array containing the elements of the 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.

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

To create a symmetric matrix that wraps an existing array without copying (creating a "view"), use the WrapSymmetric method. Any changes to the wrapped array will affect the matrix, and vice versa.

C# 
var s4 = Matrix.WrapSymmetric(elements, 3,
    MatrixTriangle.Upper, MatrixElementOrder.ColumnMajor);

Methods specific to symmetrical matrices

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.

C# 
var a = Matrix.CopyFrom(new [] { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 }, 3, 2,
    MatrixElementOrder.ColumnMajor);
var s = Numerics.NET.LinearAlgebra.SymmetricMatrix<double>.FromOuterProduct(a);

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

C# 
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);

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

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

The ApplyMatrixFunction calculates a matrix function. Its only argument is a Func<T, 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:

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