Matrix.h File Reference

Lightweight dense real-matrix utilities built on top of STL storage and GSL backends. More...

#include <gsl/gsl_matrix.h>
#include <gsl/gsl_linalg.h>
#include <gsl/gsl_eigen.h>
#include <vector>
#include <array>
#include <memory>
#include <stdexcept>
#include <algorithm>
#include "../special/special_generic.h"

Include dependency graph for Matrix.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SignedLogDet
	Signed logarithmic determinant representation. More...
class	RealMatrix
	Dense real-valued matrix with STL storage and GSL-backed linear algebra. More...
struct	EigenSystem
	Container for an eigendecomposition. More...

Typedefs
using	Vector = std::vector< double >
	Convenient alias for a dense vector of real values.
using	gsl_matrix_sptr = std::unique_ptr< gsl_matrix, decltype(&gsl_matrix_free)>
	Owning smart pointer for a GSL matrix.
using	gsl_vector_sptr = std::unique_ptr< gsl_vector, decltype(&gsl_vector_free)>
	Owning smart pointer for a GSL vector.
using	gsl_permutation_sptr = std::unique_ptr< gsl_permutation, decltype(&gsl_permutation_free)>
	Owning smart pointer for a GSL permutation.
using	gsl_eigen_workspace_sptr = std::unique_ptr< gsl_eigen_symmv_workspace, decltype(&gsl_eigen_symmv_free)>
	Owning smart pointer for a GSL symmetric-eigensystem workspace.

Functions
gsl_matrix_sptr	make_gsl_matrix (size_t rows, size_t cols)
	Allocates a GSL matrix with automatic RAII destruction.
gsl_vector_sptr	make_gsl_vector (size_t size)
	Allocates a GSL vector with automatic RAII destruction.
gsl_permutation_sptr	make_gsl_permutation (size_t size)
	Allocates a GSL permutation with automatic RAII destruction.
gsl_eigen_workspace_sptr	make_eigen_workspace (size_t n)
	Allocates a GSL symmetric eigensolver workspace with RAII destruction.
RealMatrix	eye (std::size_t n)
	Returns the identity matrix of size n.
RealMatrix	diag (const gsl_vector *X)
	Builds a diagonal matrix from a GSL vector.
RealMatrix	nearest_psd (RealMatrix R, double thr=1e-12)
	Projects a matrix to the nearest positive semi-definite correlation-like matrix.
RealMatrix	cholesky_L (RealMatrix R)
	Returns the lower-triangular Cholesky factor of a PSD matrix.
RealMatrix	block_diag (const std::vector< RealMatrix > &blocks)
	Builds a block-diagonal matrix from several square blocks.
template<typename... Ms>
RealMatrix	block_diag (const Ms &... ms)
	Variadic convenience overload for block_diag.

Detailed Description

Lightweight dense real-matrix utilities built on top of STL storage and GSL backends.

This file provides:

• a small RAII layer for owning GSL pointers safely,
• the RealMatrix class for dense real-valued matrices,
• the EigenSystem and SignedLogDet helper structs,
• several utility constructors and decompositions:
  • identity matrix,
  • diagonal matrix from a GSL vector,
  • nearest positive semi-definite projection,
  • Cholesky factor extraction,
  • block-diagonal concatenation.

Design goals:

• keep ownership simple using std::vector<double> row-major storage,
• expose a minimal, readable matrix API,
• delegate numerically sensitive operations (LU, eigensystem, Cholesky) to GSL,
• provide enough functionality for the statistics / covariance layer.

Storage convention:

• matrices are stored in row-major order,
• element (i,j) is stored at data[i * cols + j].

Note

This is a real-matrix utility only. Complex-valued matrix algebra is intentionally out of scope here.

Definition in file Matrix.h.

Typedef Documentation

gsl_eigen_workspace_sptr

using gsl_eigen_workspace_sptr = std::unique_ptr<gsl_eigen_symmv_workspace, decltype(&gsl_eigen_symmv_free)>

Owning smart pointer for a GSL symmetric-eigensystem workspace.

Definition at line 62 of file Matrix.h.

gsl_matrix_sptr

using gsl_matrix_sptr = std::unique_ptr<gsl_matrix, decltype(&gsl_matrix_free)>

Owning smart pointer for a GSL matrix.

Definition at line 53 of file Matrix.h.

gsl_permutation_sptr

using gsl_permutation_sptr = std::unique_ptr<gsl_permutation, decltype(&gsl_permutation_free)>

Owning smart pointer for a GSL permutation.

Definition at line 59 of file Matrix.h.

gsl_vector_sptr

using gsl_vector_sptr = std::unique_ptr<gsl_vector, decltype(&gsl_vector_free)>

Owning smart pointer for a GSL vector.

Definition at line 56 of file Matrix.h.

Vector

using Vector = std::vector<double>

Convenient alias for a dense vector of real values.

Definition at line 50 of file Matrix.h.

Function Documentation

block_diag() [1/2]

template<typename... Ms>

RealMatrix block_diag

(

const Ms &...

ms

)

Variadic convenience overload for block_diag.

Template Parameters

Ms	Matrix-like arguments convertible to RealMatrix.

Parameters

ms	Input blocks.

Returns

Block-diagonal concatenation.

Definition at line 562 of file Matrix.h.

block_diag() [2/2]

RealMatrix block_diag

(

const std::vector< RealMatrix > &

blocks

)

Builds a block-diagonal matrix from several square blocks.

Parameters

blocks

List of square matrices.

Returns

Block-diagonal concatenation of all input matrices.

Exceptions

std::invalid_argument

if one input block is not square.

Definition at line 529 of file Matrix.cpp.

cholesky_L()

RealMatrix cholesky_L

(

RealMatrix

R

)

Returns the lower-triangular Cholesky factor of a PSD matrix.

If R = L L^T, this function returns L.

Parameters

R	Input matrix.

Returns

Lower-triangular Cholesky factor.

Exceptions

std::invalid_argument	if the matrix is not square.
std::runtime_error	if Cholesky decomposition fails.

Definition at line 508 of file Matrix.cpp.

diag()

RealMatrix diag

(

const gsl_vector *

X

)

Builds a diagonal matrix from a GSL vector.

Parameters

X	Input vector.

Returns

Square diagonal matrix whose diagonal entries are the values of X.

Definition at line 464 of file Matrix.cpp.

eye()

RealMatrix eye

(

std::size_t

n

)

Returns the identity matrix of size n.

Parameters

n	Matrix dimension.

Returns

n × n identity matrix.

Definition at line 453 of file Matrix.cpp.

make_eigen_workspace()

gsl_eigen_workspace_sptr make_eigen_workspace ( size_t  n )

inline

Allocates a GSL symmetric eigensolver workspace with RAII destruction.

Parameters

n	Matrix dimension.

Returns

Unique pointer owning the workspace.

Definition at line 97 of file Matrix.h.

make_gsl_matrix()

gsl_matrix_sptr make_gsl_matrix ( size_t  rows, size_t  cols  )

inline

Allocates a GSL matrix with automatic RAII destruction.

Parameters

rows	Number of rows.
cols	Number of columns.

Returns

Unique pointer owning the allocated matrix.

Definition at line 70 of file Matrix.h.

make_gsl_permutation()

gsl_permutation_sptr make_gsl_permutation ( size_t  size )

inline

Allocates a GSL permutation with automatic RAII destruction.

Parameters

size	Permutation size.

Returns

Unique pointer owning the allocated permutation.

Definition at line 88 of file Matrix.h.

make_gsl_vector()

gsl_vector_sptr make_gsl_vector ( size_t  size )

inline

Allocates a GSL vector with automatic RAII destruction.

Parameters

size	Vector size.

Returns

Unique pointer owning the allocated vector.

Definition at line 79 of file Matrix.h.

nearest_psd()

RealMatrix nearest_psd	(	RealMatrix	R,
		double	thr = 1e-12
	)

Projects a matrix to the nearest positive semi-definite correlation-like matrix.

Algorithm:

• symmetrize the input,
• diagonalize it,
• clip eigenvalues below thr,
• reconstruct the matrix,
• renormalize the diagonal to 1,
• symmetrize again.

This is especially useful for repairing numerically inconsistent correlation matrices.

Parameters

R	Input matrix.
thr	Lower bound applied to eigenvalues during clipping.

Returns

Positive semi-definite, unit-diagonal repaired matrix.

Exceptions

std::invalid_argument

if the matrix is not square.

Definition at line 475 of file Matrix.cpp.