Detailed Description

Provides routines to solve linear systems.

Author: Creighton, T. D.

Synopsis

#include <lal/MatrixUtils.h>

This header covers routines to solve linear systems of equations and eigensystems, using algorithms adapted from Chapters~2 and~11 of Numerical Recipes [22] . The only routines at present are for computing eigenvalues and eigenvectors of real symmetric matrices. Routines for inverting or computing the determinant of arbitrary square matrices will likely follow.

Notation

A matrix is represented in LAL by a <datatype>Array structure with a dimLength->length field of 2; the dimLength->data field gives the dimensions \([M,N]\) of the matrix. Using the place-index notation common in tensor calculus, a matrix is a two-index tensor:

\begin{equation} \mathsf{A}^a{}_b = \left[\begin{array}{cccc} A^1{}_1 & A^1{}_2 & \cdots & A^1{}_N \\ A^2{}_1 & A^2{}_2 & \cdots & A^2{}_N \\ \vdots & \vdots & \ddots & \vdots \\ A^M{}_1 & A^M{}_2 & \cdots & A^M{}_N \end{array}\right] \;, \end{equation}

that is, the first (raised) index represents the row number and the second (lowered) index the column number. The standard C array structure declares this object as, say, float a[M][N], where the element \(A^i{}_j\) is stored in a[i][j]. The LAL array structure REAL4Array a stores data in a flattened block of memory, where the element \(A^i{}_j\) is stored in a.data[i*M+j].

A row vector is a matrix with only one row ( \(M=1\)). In the above place-index notation, it is represented with a single lowered index:

\begin{equation} \mathsf{r}_a = \left[\begin{array}{cccc} r_1 & r_2 & \cdots & r_N \end{array}\right] \;. \end{equation}

A column vector is a matrix with only one column ( \(N=1\)). In the above place-index notation, it is represented with a single raised index:

\begin{equation} \mathsf{c}^a = \left[\begin{array}{c} c^1 \\ c^2 \\ \vdots \\ c^M \end{array}\right] \;. \end{equation}

In LAL, both of these objects are conventionally represented as a LAL vector structure. Whether the object is to be used as a row or column vector must be determined from context; it is not specified by the datatype.

Properties

The basic matrix operations are addition, scalar multiplication, and vector multiplication. We assume the reader is familiar with these. In addition, we will refer to the following unary operations on square matrices:

Inversion: The inverse \((\mathsf{A}^{-1}){}^a{}_b\) of a matrix \(\mathsf{A}^a{}_b\) is one such that their matrix product is the identity matrix \(\delta^a{}_b\) (whose elements \(\delta^i{}_j\) are just the Kronecker delta function).

Transposition: The transpose \((\mathsf{A}^T){}^a{}_b\) of a matrix \(\mathsf{A}^a{}_b\) is given by interchanging the indecies on each component: \((A^T){}^i{}_j=A^j{}_i\).

Conjugation: The Hermitian conjugate (adjoint) \((\mathsf{A}^\dag){}^a{}_b\) of a matrix \(\mathsf{A}^a{}_b\) is given by interchanging the indecies and taking the complex conjugate of each component: \((A^\dag){}^i{}_j={A^j{}_i}^*\).

A matrix that is identical to its own transpose is called symmetric. A matrix whose transpose is identical to the original matrix's inverse is called orthogonal. A matrix that is identical to its own Hermitian conjugate is called Hermitian (or self-adjoint. A matrix whose Hermitian conjugate is identical to the original matrix's inverse is called unitary.

At present, the routines under this header only deal with real matrices (i.e. matrices, vectors, and scalars whose components are all real). In this case, symmetric is equivalent to Hermitian, and orthogonal is equivalent to unitary.

Modules
	Module DetInverse.c
	Routines to compute matrix determinants and inverses.

	Module Eigen.c
	Routines to compute eigenvalues and eigenvectors.

	Module MatrixOps.c
	Routines to perform basic matrix operations.

Files
file	DetInverseTest.c
	Computes the inverse and determinant of a matrix.

file	EigenTest.c
	Computes the eigenvalues and eigenvectors of a matrix.

Error Codes
#define	MATRIXUTILSH_ENUL 1
	Unexpected null pointer in arguments. More...

#define	MATRIXUTILSH_EDIM 2
	Bad matrix dimensions. More...

#define	MATRIXUTILSH_EITER 3
	Did not converge after maximum iterations. More...

#define	MATRIXUTILSH_ESING 4
	Singular matrix. More...

#define	MATRIXUTILSH_EMEM 5
	Memory allocation error. More...

Macro Definition Documentation

◆ MATRIXUTILSH_ENUL

#define MATRIXUTILSH_ENUL 1

Unexpected null pointer in arguments.

Definition at line 128 of file MatrixUtils.h.

◆ MATRIXUTILSH_EDIM

#define MATRIXUTILSH_EDIM 2

Bad matrix dimensions.

Definition at line 129 of file MatrixUtils.h.

◆ MATRIXUTILSH_EITER

#define MATRIXUTILSH_EITER 3

Did not converge after maximum iterations.

Definition at line 130 of file MatrixUtils.h.

◆ MATRIXUTILSH_ESING

#define MATRIXUTILSH_ESING 4

Singular matrix.

Definition at line 131 of file MatrixUtils.h.

◆ MATRIXUTILSH_EMEM

#define MATRIXUTILSH_EMEM 5

Memory allocation error.

Definition at line 132 of file MatrixUtils.h.