mici.matrices module

Structured matrix classes implementing basic linear algebra operations.

class mici.matrices.BlockColumnMatrix(blocks)

Bases: BlockMatrix

Matrix composed of vertical concatenation of a series of blocks.

Parameters:

blocks (Iterable[Matrix]) – Sequence of matrices defining a column of blocks in order top-to-bottom which when vertically concatenated give the overall matrix.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property blocks: tuple[Matrix]

Blocks of matrix in top-to-bottom order.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.BlockMatrix(shape, **kwargs)

Bases: ImplicitArrayMatrix

Matrix with non-zero entries defined by a series of submatrix blocks.

Args: shape: Shape of matrix (num_rows, num_columns).

Parameters:

shape (tuple[int, int])

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

abstract property blocks: tuple[Matrix]

Non-zero blocks of matrix as a tuple of Matrix instances.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.BlockRowMatrix(blocks)

Bases: BlockMatrix

Matrix composed of horizontal concatenation of a series of blocks.

Parameters:

blocks (Iterable[Matrix]) – Sequence of matrices defining a row of blocks in order left-to-right which when horizontally concatenated give the overall matrix.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property blocks: tuple[Matrix]

Blocks of matrix in left-to-right order.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.DenseDefiniteMatrix(array, factor=None, *, is_posdef=True)

Bases: _BaseTriangularFactoredDefiniteMatrix, DifferentiableMatrix, ExplicitArrayMatrix

Definite matrix specified by a dense 2D array.

Parameters:

• array (NDArray) – 2D array specifying matrix entries.

• factor (TriangularMatrix | InverseTriangularMatrix | None) – Optional argument giving the triangular factorisation of the matrix such that matrix = factor @ factor.T if is_posdef=True or matrix = -factor @ factor.T otherwise. If not pre-computed and specified at initialisation a factorisation will only be computed when first required by an operation which depends on the factor.

• is_posdef (bool) – Whether matrix (and so corresponding array representation) is positive definite, with the matrix assumed to be negative-definite if not. This is not checked on initialisation, and so if array is positive (negative) definite and is_posdef is False (True) then a LinAlgError exception will be if a later attempt is made to factorize the matrix.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property factor: TriangularMatrix | InverseTriangularMatrix

Triangular matrix with matrix = sign * factor @ factor.T.

property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sign: int

Signed binary value with matrix = sign * factor @ factor.T.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.DensePositiveDefiniteMatrix(array, factor=None)

Bases: DenseDefiniteMatrix, PositiveDefiniteMatrix

Positive-definite matrix specified by a dense 2D array.

Parameters:

• array (NDArray) – 2D array specifying matrix entries.

• factor (TriangularMatrix | InverseTriangularMatrix | None) – Optional argument giving the triangular factorisation of the matrix such that matrix = factor @ factor.T. If not pre-computed and specified at initialisation a factorisation will only be computed when first required by an operation which depends on the factor.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property factor: TriangularMatrix | InverseTriangularMatrix

Triangular matrix with matrix = sign * factor @ factor.T.

property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sign: int

Signed binary value with matrix = sign * factor @ factor.T.

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.DensePositiveDefiniteProductMatrix(rect_matrix, pos_def_matrix=None)

Bases: DensePositiveDefiniteMatrix

Positive-definite matrix specified as a signed symmetric product.

The matrix is assumed to have the form

matrix = rect_matrix @ pos_def_matrix @ rect_matrix.T

for a dense rectangular matrix rect_matrix with shape (dim_0, dim_1) (dim_1 > dim_0) positive definite matrix pos_def_matrix with shape (dim_1, dim_1), with the resulting matrix being positive definite under the assumption that rect_matrix has full row rank.

Parameters:

• rect_matrix (NDArray | Matrix) – Rectangular matrix of shape (dim_0, dim_1) with it and its transpose forming the leftmost and righmost term respectively in the symmetric matrix product defining the matrix.

• pos_def_matrix (PositiveDefiniteMatrix | None) – Optional positive positive definite matrix with shape (dim_inner, dim_inner) specifying inner term in symmetric matrix product defining matrix. If None an identity matrix is used.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property factor: TriangularMatrix | InverseTriangularMatrix

Triangular matrix with matrix = sign * factor @ factor.T.

property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sign: int

Signed binary value with matrix = sign * factor @ factor.T.

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.DenseRectangularMatrix(array)

Bases: ExplicitArrayMatrix

Dense rectangular matrix.

Parameters:

array (NDArray) – 2D array specifying matrix entries.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.DenseSquareMatrix(array, lu_and_piv=None, lu_transposed=None)

Bases: InvertibleMatrix, ExplicitArrayMatrix

Dense non-singular square matrix.

Parameters:

• array (NDArray) – 2D array specifying matrix entries.

• lu_and_piv (tuple[NDArray, NDArray] | None) – Pivoted LU factorisation represented as a tuple with first element a 2D array containing the lower and upper triangular factors (with the unit diagonal of the lower triangular factor not stored) and the second element a 1D array containing the pivot indices. Corresponds to the output of scipy.linalg.lu_factor and input to scipy.linalg.lu_solve.

• lu_transposed (bool | None) – Whether LU factorisation is of original array or its transpose.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property lu_and_piv: tuple[NDArray, NDArray]

Pivoted LU factorisation of matrix.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.DenseSymmetricMatrix(array, eigvec=None, eigval=None)

Bases: SymmetricMatrix, InvertibleMatrix, ExplicitArrayMatrix

Dense non-singular symmetric matrix.

Parameters:

• array (NDArray) – Explicit 2D array representation of matrix.

• eigvec (NDArray | OrthogonalMatrix | None) – Optional. If specified either a 2D array or an OrthogonalMatrix instance, in both cases the columns of the matrix corresponding to the orthonormal set of eigenvectors of the matrix being constructed.

• eigval (NDArray | None) – Optional. If specified a 1D array containing the eigenvalues of the matrix being constructed, with eigval[i] the eigenvalue associated with column i of eigvec.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.DiagonalMatrix(diagonal)

Bases: SymmetricMatrix, DifferentiableMatrix, ImplicitArrayMatrix

Matrix with non-zero elements only along its diagonal.

Parameters:

diagonal (NDArray) – 1D array specifying diagonal elements of matrix.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: IdentityMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.DifferentiableMatrix(shape, **kwargs)

Bases: InvertibleMatrix

Parameterically defined matrix defining gradient of scalar operations.

Parameterically-defined here means the matrix is constructed as a function of one or more parameters, with the convention that the parameters correspond to the first parameter in the `__init__` method of the `DifferentiableMatrix` subclass, with multiple parameters wrapped in to for example a tuple, dict or list.

The gradient is defined for the scalar functions of the matrix parameters implemented by the method log_abs_det, corresponding to

f(params) = log(abs(det(matrix(params))))

and by the quadratic form vector @ matrix(params).inv @ vector.

In both cases the gradients are with respect to the parameter(s). The returned gradients will have the same structure as the first parameter of the __init__ method of the relevant DifferentiableMatrix subclass, for example if the first parameter is a tuple or dict of arrays then the returned gradients will be respectively a tuple or dict of arrays of the same shapes and with the same indices / keys.

Parameters:

shape (tuple[int, int]) – Shape of matrix (num_rows, num_columns).

property T: Matrix

Transpose of matrix.

abstract property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

abstract property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

abstract grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

abstract property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.EigendecomposedPositiveDefiniteMatrix(eigvec, eigval)

Bases: EigendecomposedSymmetricMatrix, PositiveDefiniteMatrix

Positive definite matrix parametrized by its eigendecomposition.

The matrix is assumed to have the parameterisation

matrix = eigvec @ diag(eigval) @ eigvec.T

where eigvec is an orthogonal matrix, with columns corresponding to the eigenvectors of matrix and eigval is 1D array of the corresponding strictly positive eigenvalues of matrix.

Parameters:

• eigvec (NDArray | OrthogonalMatrix) – Either a 2D array or an OrthogonalMatrix instance, in both cases the columns of the matrix corresponding to the orthonormal set of eigenvectors of the matrix being constructed.

• eigval (NDArray) – A 1D array containing the eigenvalues of the matrix being constructed, with eigval[i] the eigenvalue associated with column i of eigvec.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.EigendecomposedSymmetricMatrix(eigvec, eigval)

Bases: SymmetricMatrix, InvertibleMatrix, ImplicitArrayMatrix

Symmetric matrix parametrized by its eigendecomposition.

The matrix is assumed to have the parameterisation

matrix = eigvec @ diag(eigval) @ eigvec.T

where eigvec is an orthogonal matrix, with columns corresponding to the eigenvectors of matrix and eigval is 1D array of the corresponding eigenvalues of matrix.

Parameters:

• eigvec (NDArray | OrthogonalMatrix) – Either a 2D array or an OrthogonalMatrix instance, in both cases the columns of the matrix corresponding to the orthonormal set of eigenvectors of the matrix being constructed.

• eigval (NDArray) – A 1D array containing the eigenvalues of the matrix being constructed, with eigval[i] the eigenvalue associated with column i of eigvec.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.ExplicitArrayMatrix(shape, **kwargs)

Bases: Matrix

Matrix with an explicit array representation.

Parameters:

shape (tuple[int, int]) – Shape of matrix (num_rows, num_columns).

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.IdentityMatrix(size=None)

Bases: PositiveDefiniteMatrix, ImplicitArrayMatrix

Matrix representing identity operator on a vector space.

Array representation has ones on diagonal elements and zeros elsewhere. May be defined with an implicit shape represented by (None, None) which will allow use for subset of operations where shape is not required to be known.

Parameters:

size (int | None) – Number of rows / columns in matrix or None if matrix is to be implicitly shaped.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: IdentityMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.ImplicitArrayMatrix(shape, **kwargs)

Bases: Matrix

Matrix with an implicit array representation.

Args: shape: Shape of matrix (num_rows, num_columns).

Parameters:

shape (tuple[int, int])

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.InverseLUFactoredSquareMatrix(inv_array, inv_lu_and_piv, *, inv_lu_transposed)

Bases: InvertibleMatrix, ImplicitArrayMatrix

Square matrix implicitly defined by LU factorisation of inverse.

Parameters:

• inv_array (NDArray) – 2D array specifying inverse matrix entries.

• inv_lu_and_piv (tuple[NDArray, NDArray]) – Pivoted LU factorisation represented as a tuple with first element a 2D array containing the lower and upper triangular factors (with the unit diagonal of the lower triangular factor not stored) and the second element a 1D array containing the pivot indices. Corresponds to the output of scipy.linalg.lu_factor and input to scipy.linalg.lu_solve.

• inv_lu_transposed (bool) – Whether LU factorisation is of inverse of array or transpose of inverse of array.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.InverseTriangularMatrix(inverse_array, *, lower=True, make_triangular=True)

Bases: InvertibleMatrix, ImplicitArrayMatrix

Triangular matrix implicitly specified by its inverse.

Parameters:

• inverse_array (NDArray) – 2D containing values of inverse of this matrix, with the inverse of a lower (upper) triangular matrix being itself lower (upper) triangular. Any values above (below) diagonal are ignored for lower (upper) triangular matrices i.e. when lower == True (lower == False).

• lower (bool) – Whether the matrix is lower-triangular (True) or upper-triangular (False).

• make_triangular (bool) – Whether to ensure inverse_array is triangular by explicitly zeroing entries in upper triangle if lower == True and in lower triangle if lower == False.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property lower: bool

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.InvertibleMatrix(shape, **kwargs)

Bases: SquareMatrix

Base class for non-singular square matrices.

Parameters:

shape (tuple[int, int]) – Shape of matrix (num_rows, num_columns).

property T: Matrix

Transpose of matrix.

abstract property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

abstract property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.InvertibleMatrixProduct(matrices, *, check_shapes=True)

Bases: SquareMatrixProduct, InvertibleMatrix

Matrix defined as a product of a sequence of invertible matrices.

All the matrices must have the same shape.

Parameters:

• matrices (Iterable[InvertibleMatrix]) – Sequence of matrices forming product in left-to-right order.

• check_shapes (bool) – Whether to check if all successive pairs of he matrix sequence have compatible shapes, i.e. equal inner dimensions.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property matrices: tuple[Matrix]

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.Matrix(shape, **kwargs)

Bases: ABC

Base class for matrix-like objects.

Implements overloads of the matrix multiplication operator @, as well as the standard multiplication and division operators * and / when the second argument is a scalar quantity.

Parameters:

shape (tuple[int, int]) – Shape of matrix (num_rows, num_columns).

property T: Matrix

Transpose of matrix.

abstract property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.MatrixProduct(matrices, *, check_shapes=True)

Bases: ImplicitArrayMatrix

Matrix implicitly defined as a product of a sequence of matrices.

Each adjacent pair of matrices in the sequence must have compatible shapes.

Parameters:

• matrices (Iterable[Matrix]) – Sequence of matrices forming product in left-to-right order.

• check_shapes (bool) – Whether to check if all successive pairs of he matrix sequence have compatible shapes, i.e. equal inner dimensions.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property matrices: tuple[Matrix]

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.OrthogonalMatrix(array)

Bases: InvertibleMatrix, ExplicitArrayMatrix

Square matrix with columns and rows that are orthogonal unit vectors.

Parameters:

array (NDArray) – Explicit 2D array representation of matrix.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.PositiveDefiniteBlockDiagonalMatrix(blocks)

Bases: SquareBlockDiagonalMatrix, PositiveDefiniteMatrix, DifferentiableMatrix

Positive definite specialisation of SymmetricBlockDiagonalMatrix.

All matrix blocks in diagonal are restricted to be positive definite.

Parameters:

blocks (Iterable[PositiveDefiniteMatrix]) – Sequence of positive-definite matrices defining non-zero blocks along diagonal of matrix in order left-to-right.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property blocks: tuple[SquareMatrix]

Blocks containing non-zero values left-to-right along diagonal.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: SquareBlockDiagonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property grad_log_abs_det: float

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.PositiveDefiniteLowRankUpdateMatrix(factor_matrix, pos_def_matrix, inner_pos_def_matrix=None, capacitance_matrix=None, sign=1)

Bases: SymmetricLowRankUpdateMatrix, PositiveDefiniteMatrix, DifferentiableMatrix

Positive-definite matrix equal to low-rank update to a square matrix.

The matrix is assumed to have the parametrisation

matrix = (

pos_def_matrix + sign * factor_matrix @ inner_pos_def_matrix @ factor_matrix.T)

where factor_matrix is rectangular with shape (dim_outer, dim_inner), pos_def_matrix is positive-definite with shape (dim_outer, dim_outer), inner_pos_def_matrix is positive-definite with shape (dim_inner, dim_inner) and sign is one of {-1, +1} and determines whether a low-rank update (sign = 1) or ‘downdate’ (sign = -1) is peformed.

By exploiting the Woodbury matrix identity and matrix determinant lemma the inverse, determinant and square-root of the matrix can all be computed at a cost of O(dim_inner**3 + dim_inner**2 * dim_outer) plus the cost of inverting / evaluating the determinant / square_root of pos_def_matrix, which for pos_def_matrix instances with special structure such as diagonality or with an existing factorisation, will typically be cheaper than the O(dim_outer**3) cost of evaluating the inverse, determinant or square-root directly.

Parameters:

• factor_matrix (Matrix) – Rectangular matrix with shape (dim_outer, dim_inner) with it and its transpose forming the leftmost and righmost term respectively in the matrix product defining the low-rank update.

• pos_def_matrix (PositiveDefiniteMatrix) – Positive-definite matrix to perform low-rank update (or downdate) to.

• inner_pos_def_matrix (PositiveDefiniteMatrix | None) – Optional positive definite matrix with shape (dim_inner, dim_inner) specifying inner term in matrix product defining low-rank update. If None an identity matrix is used.

• capacitance_matrix (PositiveDefiniteMatrix | None) –

  Positive-definite matrix equal to.

  inner_pos_def_matrix.inv + factor_matrix.T @ pos_def_matrix.inv @ factor_matrix

  and with shape (dim_inner, dim_inner) which is used in constructing inverse and computation of determinant of the low-rank updated matrix, with this argument optional and typically only passed when this matrix has already been computed in a previous computation.

• sign (Literal[-1, 1]) – One of {-1, +1}, determining whether a low-rank update (sign = 1) or ‘downdate’ (sign = -1) is peformed.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property capacitance_matrix: DensePositiveDefiniteMatrix

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.PositiveDefiniteMatrix(shape, **kwargs)

Bases: SymmetricMatrix, InvertibleMatrix

Base class for positive definite matrices.

Parameters:

shape (tuple[int, int]) – Shape of matrix (num_rows, num_columns).

property T: Matrix

Transpose of matrix.

abstract property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.PositiveDiagonalMatrix(diagonal)

Bases: DiagonalMatrix, PositiveDefiniteMatrix

Specialisation of DiagonalMatrix with positive diagonal parameter.

Restricts all values in diagonal array parameter to be strictly positive.

Parameters:

diagonal (NDArray) – 1D array specifying diagonal elements of matrix.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: IdentityMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.PositiveScaledIdentityMatrix(scalar, size=None)

Bases: ScaledIdentityMatrix, PositiveDefiniteMatrix

Specialisation of ScaledIdentityMatrix with positive scalar parameter.

Restricts the scalar parameter to be strictly positive.

Parameters:

• scalar (ScalarLike) – Scalar multiplier for identity matrix.

• size (int | None) – Number of rows / columns in matrix. If None the matrix will be implicitly-shaped and only the subset of operations which do not rely on an explicit shape will be available.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: IdentityMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property grad_log_abs_det: ScalarLike

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

float

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property scalar: float

Scalar multiplier.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.ScaledIdentityMatrix(scalar, size=None)

Bases: SymmetricMatrix, DifferentiableMatrix, ImplicitArrayMatrix

Matrix representing scalar multiplication operation on a vector space.

Array representation has common scalar on diagonal elements and zeros elsewhere. May be defined with an implicit shape reprsented by (None, None) which will allow use for subset of operations where shape is not required to be known.

Parameters:

• scalar (float) – Scalar multiplier for identity matrix.

• size (int | None) – Number of rows / columns in matrix. If None the matrix will be implicitly-shaped and only the subset of operations which do not rely on an explicit shape will be available.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: IdentityMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property grad_log_abs_det: ScalarLike

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

float

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property scalar: float

Scalar multiplier.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.ScaledOrthogonalMatrix(scalar, orth_array)

Bases: InvertibleMatrix, ImplicitArrayMatrix

Matrix corresponding to orthogonal matrix multiplied by a scalar.

Matrix is assumed to have the paramterisation

matrix = scalar * orth_array

where scalar is a real-valued scalar and orth_array is an orthogonal matrix represented as a square 2D array.

Parameters:

• scalar (float) – Scalar multiplier as a floating point value.

• orth_array (NDArray) – 2D array representation of orthogonal matrix.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.SoftAbsRegularizedPositiveDefiniteMatrix(symmetric_array, softabs_coeff)

Bases: EigendecomposedPositiveDefiniteMatrix, DifferentiableMatrix

Matrix transformed to be positive definite by regularising eigenvalues.

Matrix is parametrized by a symmetric array symmetric_array, of which an eigendecomposition is formed eigvec, eigval = eigh(symmetric_array), with the output matrix then matrix = eigvec @ softabs(eigval) @ eigvec.T where softabs is a smooth approximation to the absolute function.

Parameters:

• symmetric_array (NDArray) – 2D square array with symmetric values, i.e. symmetric_array[i, j] == symmetric_array[j, i] for all indices i and j which represents symmetric matrix to form eigenvalue-regularized transformation of.

• softabs_coeff (float) – Positive regularisation coefficient for smooth approximation to absolute value. As the value tends to infinity the approximation becomes increasingly close to the absolute function.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

grad_softabs(x)

Derivative of smooth approximation to absolute function.

Parameters:

x (NDArray)

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

softabs(x)

Smooth approximation to absolute function.

Parameters:

x (NDArray)

Return type:

NDArray

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.SquareBlockDiagonalMatrix(blocks)

Bases: InvertibleMatrix, BlockMatrix

Square matrix with non-zero values only in blocks along diagonal.

Parameters:

blocks (Iterable[SquareMatrix]) – Sequence of square matrices defining non-zero blocks along diagonal of matrix in order left-to-right.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property blocks: tuple[SquareMatrix]

Blocks containing non-zero values left-to-right along diagonal.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

property eigvec: SquareBlockDiagonalMatrix

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.SquareLowRankUpdateMatrix(left_factor_matrix, right_factor_matrix, square_matrix, inner_square_matrix=None, capacitance_matrix=None, sign=1)

Bases: InvertibleMatrix, ImplicitArrayMatrix

Square matrix equal to a low-rank update to a square matrix.

The matrix is assumed to have the parametrisation

matrix = (

square_matrix + sign * left_factor_matrix @ inner_square_matrix @ right_factor_matrix)

where left_factor_matrix and right_factor_matrix are rectangular with shapes (dim_outer, dim_inner) and (dim_inner, dim_outer) resp., square_matrix is square with shape (dim_outer, dim_outer), inner_square_matrix is square with shape (dim_inner, dim_inner) and sign is one of {-1, +1} and determines whether a low-rank update (sign = 1) or ‘downdate’ (sign = -1) is peformed.

By exploiting the Woodbury matrix identity and matrix determinant lemma the inverse and determinant of the matrix can be computed at a cost of O(dim_inner**3 + dim_inner**2 * dim_outer) plus the cost of inverting / evaluating the determinant of square_matrix, which for square_matrix instances with special structure such as diagonality or with an existing factorisation, will typically be cheaper than the O(dim_outer**3) cost of evaluating the inverse or determinant directly.

Parameters:

• left_factor_matrix (Matrix) – Rectangular matrix with shape (dim_outer, dim_inner) forming leftmost term in matrix product defining low-rank update.

• right_factor_matrix (Matrix) – Rectangular matrix with shape (dim_inner, dim_outer) forming rightmost term in matrix product defining low-rank update.

• square_matrix (SquareMatrix) – Square matrix to perform low-rank update (or downdate) to.

• inner_square_matrix (SquareMatrix | None) – Optional square matrix with shape (dim_inner, dim_inner) specifying inner term in matrix product defining low-rank update. If None an identity matrix is used.

• capacitance_matrix (SquareMatrix | None) –

  Square matrix equal to.

  inner_square_matrix.inv + right_factor_matrix @ square_matrix.inv @ left_factor_matrix

  and with shape (dim_inner, dim_inner) which is used in constructing inverse and computation of determinant of the low-rank updated matrix, with this argument optional and typically only passed when this matrix has already been computed in a previous computation.

• sign (Literal[-1, 1]) – One of {-1, +1}, determining whether a low-rank update (sign = 1) or ‘downdate’ (sign = -1) is peformed.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property capacitance_matrix: DenseSquareMatrix

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.SquareMatrix(shape, **kwargs)

Bases: Matrix

Base class for matrices with equal numbers of rows and columns.

Parameters:

shape (tuple[int, int]) – Shape of matrix (num_rows, num_columns).

property T: Matrix

Transpose of matrix.

abstract property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

abstract property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.SquareMatrixProduct(matrices, *, check_shapes=True)

Bases: MatrixProduct, SquareMatrix

Matrix implicitly defined as a product of a sequence of square matrices.

All the matrices must have the same shape.

Parameters:

• matrices (Iterable[Matrix]) – Sequence of matrices forming product in left-to-right order.

• check_shapes (bool) – Whether to check if all successive pairs of he matrix sequence have compatible shapes, i.e. equal inner dimensions.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property matrices: tuple[Matrix]

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.SymmetricBlockDiagonalMatrix(blocks)

Bases: SquareBlockDiagonalMatrix, SymmetricMatrix

Symmetric specialisation of SquareBlockDiagonalMatrix.

All matrix blocks in diagonal are restricted to be symmetric, i.e. block.T == block.

Parameters:

blocks (Iterable[SymmetricMatrix]) – Sequence of symmetric matrices defining non-zero blocks along diagonal of matrix in order left-to-right.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property blocks: tuple[SquareMatrix]

Blocks containing non-zero values left-to-right along diagonal.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: SquareBlockDiagonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.SymmetricLowRankUpdateMatrix(factor_matrix, symmetric_matrix, inner_symmetric_matrix=None, capacitance_matrix=None, sign=1)

Bases: SquareLowRankUpdateMatrix, SymmetricMatrix, InvertibleMatrix

Symmetric matrix equal to a low-rank update to a symmetric matrix.

The matrix is assumed to have the parametrisation

matrix = (

symmetric_matrix + sign * factor_matrix @ inner_symmetric_matrix @ factor_matrix.T)

where factor_matrix is rectangular with shape (dim_outer, dim_inner), symmetric_matrix is symmetric with shape (dim_outer, dim_outer), inner_symmetric_matrix is symmetric with shape (dim_inner, dim_inner) and sign is one of {-1, +1} and determines whether a low-rank update (sign = 1) or ‘downdate’ (sign = -1) is peformed.

By exploiting the Woodbury matrix identity and matrix determinant lemma the inverse and determinant of the matrix can be computed at a cost of O(dim_inner**3 + dim_inner**2 * dim_outer) plus the cost of inverting / evaluating the determinant of square_matrix, which for square_matrix instances with special structure such as diagonality or with an existing factorisation, will typically be cheaper than the O(dim_outer**3) cost of evaluating the inverse or determinant directly.

Parameters:

• factor_matrix (Matrix) – Rectangular matrix with shape (dim_outer, dim_inner) with it and its transpose forming the leftmost and righmost term respectively in the matrix product defining the low-rank update.

• symmetric_matrix (SymmetricMatrix) – Symmetric matrix to perform low-rank update (or downdate) to.

• inner_symmetric_matrix (SymmetricMatrix | None) – Optional symmetric matrix with shape (dim_inner, dim_inner) specifying inner term in matrix product defining low-rank update. If None an identity matrix is used.

• capacitance_matrix (SymmetricMatrix | None) –

  Symmetric matrix equal to.

  inner_symmetric_matrix.inv + factor_matrix.T @ symmetric_matrix.inv @ factor_matrix

  and with shape (dim_inner, dim_inner) which is used in constructing inverse and computation of determinant of the low-rank updated matrix, with this argument optional and typically only passed when this matrix has already been computed in a previous computation.

• sign (Literal[-1, 1]) – One of {-1, +1}, determining whether a low-rank update (sign = 1) or ‘downdate’ (sign = -1) is peformed.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property capacitance_matrix: DenseSymmetricMatrix

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.SymmetricMatrix(shape, **kwargs)

Bases: SquareMatrix

Base class for square matrices which are equal to their transpose.

Parameters:

shape (tuple[int, int]) – Shape of matrix (num_rows, num_columns).

property T: Matrix

Transpose of matrix.

abstract property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.

class mici.matrices.TriangularFactoredDefiniteMatrix(factor, sign=1, factor_is_lower=None)

Bases: _BaseTriangularFactoredDefiniteMatrix, DifferentiableMatrix, ImplicitArrayMatrix

Matrix specified as a signed self-product of a triangular factor.

The matrix is assumed to have the form

matrix = sign * factor @ factor.T

for and upper- or lower-trinagular matrix factor and signed binary value sign (i.e. sign == +1 or sign == -1), with the matrix being positive definite if sign == +1 and negative definite if sign == -1 under the assumption that factor is non-singular.

Parameters:

• factor (NDArray | TriangularMatrix | InverseTriangularMatrix) – The triangular factor parameterising the matrix. Defined either a 2D array, in which case only the lower- or upper-triangular elements are used depending on the value of the factor_is_lower boolean keyword argument, or as a TriangularMatrix / InverseTriangularMatrix instance in which case factor_is_lower is ignored, with factor.lower instead determining if the factor is lower- or upper-triangular.

• sign (Literal[-1, 1]) – +/-1 multiplier of factor product, corresponding respectively to a strictly positive- or negative-definite matrix.

• factor_is_lower (bool | None) – Whether the array factor is lower- or upper-triangular.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property factor: TriangularMatrix | InverseTriangularMatrix

Triangular matrix with matrix = sign * factor @ factor.T.

property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sign: int

Signed binary value with matrix = sign * factor @ factor.T.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.TriangularFactoredPositiveDefiniteMatrix(factor, *, factor_is_lower=True)

Bases: TriangularFactoredDefiniteMatrix, PositiveDefiniteMatrix

Positive definite matrix parametrized a triangular matrix product.

The matrix is assumed to have the parameterisation

matrix = factor @ factor.T

where factor is an upper- or lower-triangular matrix. Note for the case factor is lower-triangular this corresponds to the standard Cholesky factorisation of a positive definite matrix.

Parameters:

• factor (NDArray | TriangularMatrix | InverseTriangularMatrix) – The triangular factor parameterising the matrix. Defined either a 2D array, in which case only the lower- or upper-triangular elements are used depending on the value of the factor_is_lower boolean keyword argument, or as a TriangularMatrix / InverseTriangularMatrix instance in which case factor_is_lower is ignored, with factor.lower instead determining if the factor is lower- or upper-triangular.

• factor_is_lower (bool) – Whether the array factor is lower- or upper-triangular.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

Generally accessing this property should be avoided wherever possible as the resulting array object may use a lot of memory and operations with it will not be able to exploit any structure in the matrix.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property eigval: NDArray

Eigenvalues of matrix as a 1D array.

property eigvec: OrthogonalMatrix

Eigenvectors of matrix stacked as columns of a Matrix object.

property factor: TriangularMatrix | InverseTriangularMatrix

Triangular matrix with matrix = sign * factor @ factor.T.

property grad_log_abs_det: NDArray

Gradient of logarithm of absolute value of determinant of matrix.

grad_quadratic_form_inv(vector)

Gradient of quadratic form vector @ matrix.inv @ vector.

Parameters:

vector (NDArray) – 1D array representing vector to evaluate quadratic form at.

Return type:

NDArray

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property sign: int

Signed binary value with matrix = sign * factor @ factor.T.

property sqrt: Matrix

Square-root of matrix satisfying matrix == sqrt @ sqrt.T.

This will in general not correspond to the unique, if defined, symmetric square root of a symmetric matrix but instead may return any matrix satisfying the above property.

property transpose: Matrix

Transpose of matrix.

class mici.matrices.TriangularMatrix(array, *, lower=True, make_triangular=True)

Bases: InvertibleMatrix, ExplicitArrayMatrix

Matrix with non-zero values only in lower or upper triangle elements.

Parameters:

• array (NDArray) – 2D array containing lower / upper triangular element values of matrix. Any values above (below) diagonal are ignored for lower (upper) triangular matrices i.e. when lower == True (lower == False).

• lower (bool) – Whether the matrix is lower-triangular (True) or upper-triangular (False).

• make_triangular (bool) – Whether to ensure array is triangular by explicitly zeroing entries in upper triangle if lower == True and in lower triangle if lower == False.

property T: Matrix

Transpose of matrix.

property array: NDArray

Full dense representation of matrix as a 2D array.

property diagonal: NDArray

Diagonal of matrix as a 1D array.

property inv: SquareMatrix

Inverse of matrix as a Matrix object.

This will not necessarily form an explicit representation of the inverse matrix but may instead return a Matrix object that implements the matrix multiplication operators by solving the linear system defined by the original matrix object.

property log_abs_det: float

Logarithm of absolute value of determinant of matrix.

For matrix representations of metrics it is proportional to the logarithm of the density of then Riemannian measure associated with metric with respect to the Lebesgue measure.

property lower: bool

property shape: tuple[int, int]

Shape of matrix as a tuple (num_rows, num_columns).

property transpose: Matrix

Transpose of matrix.