Welcome to matrix_decomposition’s documentation!¶

Functions¶

Several functions are included in this package. The most important are summarized here.

decompose¶

matrix.calculate.decompose(A, permutation_method=None, check_finite=True, return_type=None)[source]¶

Computes a decomposition of a matrix.

Parameters:	A (numpy.ndarray or scipy.sparse.spmatrix) – Matrix to be decomposed. It is assumed, that A is Hermitian. The matrix must be a squared matrix. permutation_method (str) – The symmetric permutation method that is applied to the matrix before it is decomposed. It has to be a value in `matrix.constants.PERMUTATION_METHODS`. If A is sparse, it can also be a value in `matrix.sparse.constants.SPARSE_PERMUTATION_METHODS`. optional, default: no permutation check_finite (bool) – Whether to check that the input matrix contains only finite numbers. Disabling may result in problems (crashes, non-termination) if the inputs do contain infinities or NaNs. (disabling may improve performance) optional, default: True return_type (str) – The type of the decomposition that should be calculated. It has to be a value in `matrix.constants.DECOMPOSITION_TYPES`. If return_type is None the type of the returned decomposition is chosen by the function itself. optional, default: the type of the decomposition is chosen by the function itself
Returns:	A decompostion of A of type return_type.
Return type:	matrix.decompositions.DecompositionBase
Raises:	`matrix.errors.MatrixNoDecompositionPossibleError` – If the decomposition of A is not possible.

matrix.constants.PERMUTATION_METHODS = (None, '', 'none', 'natural', 'decreasing_diagonal_values', 'increasing_diagonal_values', 'decreasing_absolute_diagonal_values', 'increasing_absolute_diagonal_values')¶: Supported permutation methods for dense and sparse matrices.

matrix.sparse.constants.SPARSE_PERMUTATION_METHODS = ()¶: Supported permutation methods only for sparse matrices.

matrix.constants.DECOMPOSITION_TYPES = ('LDL', 'LDL_compressed', 'LL')¶: Supported types of decompositions.

Matrix decompositions¶

Several matrix decompositions are supported. They are available in matrix.decompositions:

LL decomposition¶

class matrix.decompositions.LL_Decomposition(L, p=None)[source]¶

Bases: matrix.decompositions.DecompositionBase

A matrix decomposition where \(LL^H\) is the decomposed (permuted) matrix.

L is a lower triangle matrix with ones on the diagonal. This decomposition is also called Cholesky decomposition.

Parameters:	L (numpy.ndarray or scipy.sparse.spmatrix) – The matrix L of the decomposition. p (numpy.ndarray) – The permutation vector used for the decomposition. This decomposition is of A[p[:, np.newaxis], p[np.newaxis, :]] where A is a matrix. optional, default: no permutation

L¶: numpy.matrix or scipy.sparse.spmatrix – The matrix L of the decomposition.

P¶: scipy.sparse.dok_matrix – The permutation matrix. P @ A @ P.H is the matrix A permuted by the permutation of the decomposition

composed_matrix¶: numpy.matrix or scipy.sparse.spmatrix – The composed matrix represented by this decomposition.

copy()¶

Copy this decomposition.

Returns:	A copy of this decomposition.
Return type:	matrix.decompositions.DecompositionBase

decomposition_type¶: str – The type of this decompositon.

is_permuted¶: bool – Whether this is a decompositon with permutation.

is_sparse¶: bool – Whether this is a sparse decompositon.

is_type(decomposition_type)¶

Whether this is a decomposition of the passed type.

Parameters:	decomposition_type (str) – The decomposition type according to which is checked.
Returns:	Whether this is a decomposition of the passed type.
Return type:	bool

n¶: int – The dimension of the squared decomposed matrix.

p¶: numpy.ndarray – The permutation vector. A[p[:, np.newaxis], p[np.newaxis, :]] is the matrix A permuted by the permutation of the decomposition

p_inverse¶: numpy.ndarray – The permutation vector that undos the permutation.

permute_matrix(A)¶

Permute a matrix by the permutation of the decomposition.

Parameters:	A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be permuted.
Returns:	The matrix A permuted by the permutation of the decomposition.
Return type:	numpy.ndarray or scipy.sparse.spmatrix

to(decomposition_type, copy=False)[source]¶

Convert decomposition to passed type.

Parameters:	decomposition_type (str) – The decomposition type to which this decomposition is converted. copy (bool) – Whether the data of this decomposition should always be copied or only if needed.
Returns:	If the type of this decomposition is not decomposition_type, a decompostion of type decomposition_type is returned which represents the same decomposed matrix as this decomposition. Otherwise this decomposition or a copy of it is returned, depending on copy.
Return type:	matrix.decompositions.DecompositionBase

to_LDL_Decomposition()[source]¶

to_any(*decomposition_types, copy=False)¶

Convert decomposition to any of the passed types.

Parameters:	decomposition_types (str) – The decomposition types to any of them this this decomposition is converted. copy* (bool) – Whether the data of this decomposition should always be copied or only if needed.
Returns:	If the type of this decomposition is not in decomposition_types, a decompostion of type decomposition_type[0] is returned which represents the same decomposed matrix as this decomposition. Otherwise this decomposition or a copy of it is returned, depending on copy.
Return type:	matrix.decompositions.DecompositionBase

unpermute_matrix(A)¶

Unpermute a matrix permuted by the permutation of the decomposition.

Parameters:	A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be unpermuted.
Returns:	The matrix A unpermuted by the permutation of the decomposition.
Return type:	numpy.ndarray or scipy.sparse.spmatrix

LDL decomposition¶

class matrix.decompositions.LDL_Decomposition(L, d, p=None)[source]¶

Bases: matrix.decompositions.DecompositionBase

A matrix decomposition where \(LDL^H\) is the decomposed (permuted) matrix.

L is a lower triangle matrix with ones on the diagonal. D is a diagonal matrix. Only the diagonal values of D are stored.

Parameters:	L (numpy.ndarray or scipy.sparse.spmatrix) – The matrix L of the decomposition. d (numpy.ndarray) – The vector of the diagonal components of D of the decompositon. p (numpy.ndarray) – The permutation vector used for the decomposition. This decomposition is of A[p[:, np.newaxis], p[np.newaxis, :]] where A is a matrix. optional, default: no permutation

D¶: scipy.sparse.dia_matrix – The permutation matrix.

L¶: numpy.matrix or scipy.sparse.spmatrix – The matrix L of the decomposition.

LD¶: numpy.matrix or scipy.sparse.spmatrix – A matrix whose diagonal values are the diagonal values of D and whose off-diagonal values are those of L.

P¶: scipy.sparse.dok_matrix – The permutation matrix. P @ A @ P.H is the matrix A permuted by the permutation of the decomposition

composed_matrix¶: numpy.matrix or scipy.sparse.spmatrix – The composed matrix represented by this decomposition.

copy()¶

Copy this decomposition.

Returns:	A copy of this decomposition.
Return type:	matrix.decompositions.DecompositionBase

d¶: numpy.ndarray – The diagonal vector of the matrix D of the decomposition.

decomposition_type¶: str – The type of this decompositon.

is_permuted¶: bool – Whether this is a decompositon with permutation.

is_sparse¶: bool – Whether this is a sparse decompositon.

is_type(decomposition_type)¶

Whether this is a decomposition of the passed type.

Parameters:	decomposition_type (str) – The decomposition type according to which is checked.
Returns:	Whether this is a decomposition of the passed type.
Return type:	bool

n¶: int – The dimension of the squared decomposed matrix.

p¶: numpy.ndarray – The permutation vector. A[p[:, np.newaxis], p[np.newaxis, :]] is the matrix A permuted by the permutation of the decomposition

p_inverse¶: numpy.ndarray – The permutation vector that undos the permutation.

permute_matrix(A)¶

Permute a matrix by the permutation of the decomposition.

Parameters:	A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be permuted.
Returns:	The matrix A permuted by the permutation of the decomposition.
Return type:	numpy.ndarray or scipy.sparse.spmatrix

to(decomposition_type, copy=False)[source]¶

Convert decomposition to passed type.

Parameters:	decomposition_type (str) – The decomposition type to which this decomposition is converted. copy (bool) – Whether the data of this decomposition should always be copied or only if needed.
Returns:	If the type of this decomposition is not decomposition_type, a decompostion of type decomposition_type is returned which represents the same decomposed matrix as this decomposition. Otherwise this decomposition or a copy of it is returned, depending on copy.
Return type:	matrix.decompositions.DecompositionBase

to_LDL_DecompositionCompressed()[source]¶

to_LL_Decomposition()[source]¶

to_any(*decomposition_types, copy=False)¶

Convert decomposition to any of the passed types.

Parameters:	decomposition_types (str) – The decomposition types to any of them this this decomposition is converted. copy* (bool) – Whether the data of this decomposition should always be copied or only if needed.
Returns:	If the type of this decomposition is not in decomposition_types, a decompostion of type decomposition_type[0] is returned which represents the same decomposed matrix as this decomposition. Otherwise this decomposition or a copy of it is returned, depending on copy.
Return type:	matrix.decompositions.DecompositionBase

unpermute_matrix(A)¶

Unpermute a matrix permuted by the permutation of the decomposition.

Parameters:	A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be unpermuted.
Returns:	The matrix A unpermuted by the permutation of the decomposition.
Return type:	numpy.ndarray or scipy.sparse.spmatrix

LDL decomposition compressed¶

class matrix.decompositions.LDL_DecompositionCompressed(LD, p=None)[source]¶

Bases: matrix.decompositions.DecompositionBase

A matrix decomposition where \(LDL^H\) is the decomposed (permuted) matrix.

L is a lower triangle matrix with ones on the diagonal. D is a diagonal matrix. L and D are stored in one matrix whose diagonal values are the diagonal values of D and whose off-diagonal values are those of L.

Parameters:	LD (numpy.ndarray or scipy.sparse.spmatrix) – A matrix whose diagonal values are the diagonal values of D and whose off-diagonal values are those of L. p (numpy.ndarray) – The permutation vector used for the decomposition. This decomposition is of A[p[:, np.newaxis], p[np.newaxis, :]] where A is a matrix. optional, default: no permutation

D¶: scipy.sparse.dia_matrix – The permutation matrix.

L¶: numpy.matrix or scipy.sparse.spmatrix – The matrix L of the decomposition.

LD¶: numpy.matrix or scipy.sparse.spmatrix – A matrix whose diagonal values are the diagonal values of D and whose off-diagonal values are those of L.

P¶: scipy.sparse.dok_matrix – The permutation matrix. P @ A @ P.H is the matrix A permuted by the permutation of the decomposition

composed_matrix¶: numpy.matrix or scipy.sparse.spmatrix – The composed matrix represented by this decomposition.

copy()¶

Copy this decomposition.

Returns:	A copy of this decomposition.
Return type:	matrix.decompositions.DecompositionBase

d¶: numpy.ndarray – The diagonal vector of the matrix D of the decomposition.

decomposition_type¶: str – The type of this decompositon.

is_permuted¶: bool – Whether this is a decompositon with permutation.

is_sparse¶: bool – Whether this is a sparse decompositon.

is_type(decomposition_type)¶

Whether this is a decomposition of the passed type.

Parameters:	decomposition_type (str) – The decomposition type according to which is checked.
Returns:	Whether this is a decomposition of the passed type.
Return type:	bool

n¶: int – The dimension of the squared decomposed matrix.

p¶: numpy.ndarray – The permutation vector. A[p[:, np.newaxis], p[np.newaxis, :]] is the matrix A permuted by the permutation of the decomposition

p_inverse¶: numpy.ndarray – The permutation vector that undos the permutation.

permute_matrix(A)¶

Permute a matrix by the permutation of the decomposition.

Parameters:	A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be permuted.
Returns:	The matrix A permuted by the permutation of the decomposition.
Return type:	numpy.ndarray or scipy.sparse.spmatrix

to(decomposition_type, copy=False)[source]¶

Convert decomposition to passed type.

Parameters:	decomposition_type (str) – The decomposition type to which this decomposition is converted. copy (bool) – Whether the data of this decomposition should always be copied or only if needed.
Returns:	If the type of this decomposition is not decomposition_type, a decompostion of type decomposition_type is returned which represents the same decomposed matrix as this decomposition. Otherwise this decomposition or a copy of it is returned, depending on copy.
Return type:	matrix.decompositions.DecompositionBase

to_LDL_Decomposition()[source]¶

to_any(*decomposition_types, copy=False)¶

Convert decomposition to any of the passed types.

Parameters:	decomposition_types (str) – The decomposition types to any of them this this decomposition is converted. copy* (bool) – Whether the data of this decomposition should always be copied or only if needed.
Returns:	If the type of this decomposition is not in decomposition_types, a decompostion of type decomposition_type[0] is returned which represents the same decomposed matrix as this decomposition. Otherwise this decomposition or a copy of it is returned, depending on copy.
Return type:	matrix.decompositions.DecompositionBase

unpermute_matrix(A)¶

Unpermute a matrix permuted by the permutation of the decomposition.

Parameters:	A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be unpermuted.
Returns:	The matrix A unpermuted by the permutation of the decomposition.
Return type:	numpy.ndarray or scipy.sparse.spmatrix

base decomposition¶

class matrix.decompositions.DecompositionBase(p=None, decomposition_type=None)[source]¶

Bases: object

A matrix decomposition.

This class is a base class for matrix decompositions.

Parameters:	p (numpy.ndarray) – The permutation vector used for the decomposition. This decomposition is of A[p[:, np.newaxis], p[np.newaxis, :]] where A is a matrix. optional, default: no permutation decomposition_type (str) – Type of this decomposition. optional, default: type not specified

P¶: scipy.sparse.dok_matrix – The permutation matrix. P @ A @ P.H is the matrix A permuted by the permutation of the decomposition

composed_matrix¶: numpy.matrix or scipy.sparse.spmatrix – The composed matrix represented by this decomposition.

copy()[source]¶

Copy this decomposition.

Returns:	A copy of this decomposition.
Return type:	matrix.decompositions.DecompositionBase

decomposition_type¶: str – The type of this decompositon.

is_permuted¶: bool – Whether this is a decompositon with permutation.

is_sparse¶: bool – Whether this is a sparse decompositon.

is_type(decomposition_type)[source]¶

Whether this is a decomposition of the passed type.

Parameters:	decomposition_type (str) – The decomposition type according to which is checked.
Returns:	Whether this is a decomposition of the passed type.
Return type:	bool

n¶: int – The dimension of the squared decomposed matrix.

p¶: numpy.ndarray – The permutation vector. A[p[:, np.newaxis], p[np.newaxis, :]] is the matrix A permuted by the permutation of the decomposition

p_inverse¶: numpy.ndarray – The permutation vector that undos the permutation.

permute_matrix(A)[source]¶

Permute a matrix by the permutation of the decomposition.

Parameters:	A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be permuted.
Returns:	The matrix A permuted by the permutation of the decomposition.
Return type:	numpy.ndarray or scipy.sparse.spmatrix

to(decomposition_type, copy=False)[source]¶

Convert decomposition to passed type.

Parameters:	decomposition_type (str) – The decomposition type to which this decomposition is converted. copy (bool) – Whether the data of this decomposition should always be copied or only if needed.
Returns:	If the type of this decomposition is not decomposition_type, a decompostion of type decomposition_type is returned which represents the same decomposed matrix as this decomposition. Otherwise this decomposition or a copy of it is returned, depending on copy.
Return type:	matrix.decompositions.DecompositionBase

to_any(*decomposition_types, copy=False)[source]¶

Convert decomposition to any of the passed types.

Parameters:	decomposition_types (str) – The decomposition types to any of them this this decomposition is converted. copy* (bool) – Whether the data of this decomposition should always be copied or only if needed.
Returns:	If the type of this decomposition is not in decomposition_types, a decompostion of type decomposition_type[0] is returned which represents the same decomposed matrix as this decomposition. Otherwise this decomposition or a copy of it is returned, depending on copy.
Return type:	matrix.decompositions.DecompositionBase

unpermute_matrix(A)[source]¶

Unpermute a matrix permuted by the permutation of the decomposition.

Parameters:	A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be unpermuted.
Returns:	The matrix A unpermuted by the permutation of the decomposition.
Return type:	numpy.ndarray or scipy.sparse.spmatrix

Errors¶

This is an overview about the exceptions that could arise in this package. They are available in matrix.errors:

MatrixNoDecompositionPossibleError¶

class matrix.errors.MatrixNoDecompositionPossibleError(matrix=None, decomposition_decription=None, message=None)[source]¶

Bases: matrix.errors.MatrixError

The matrix decomposition is not possible for this matrix.

MatrixNoLDLDecompositionPossibleError¶

class matrix.errors.MatrixNoLDLDecompositionPossibleError(matrix=None, problematic_leading_principal_submatrix_index=None, subdecomposition=None)[source]¶

Bases: matrix.errors.MatrixNoDecompositionPossibleWithProblematicSubdecompositionError

A LDL decomposition is not possible for this matrix.

MatrixNoLLDecompositionPossibleError¶

class matrix.errors.MatrixNoLLDecompositionPossibleError(matrix=None, problematic_leading_principal_submatrix_index=None, subdecomposition=None)[source]¶

Bases: matrix.errors.MatrixNoDecompositionPossibleWithProblematicSubdecompositionError

A LL decomposition is not possible for this matrix.

MatrixDecompositionNoConversionImplementedError¶

class matrix.errors.MatrixDecompositionNoConversionImplementedError(original_decomposition=None, desired_decomposition_type=None)[source]¶

Bases: matrix.errors.MatrixError

A decomposition conversion is not implemented for this type.

MatrixNoDecompositionPossibleWithProblematicSubdecompositionError¶

class matrix.errors.MatrixNoDecompositionPossibleWithProblematicSubdecompositionError(matrix=None, decomposition_decription=None, problematic_leading_principal_submatrix_index=None, subdecomposition=None)[source]¶

Bases: matrix.errors.MatrixNoDecompositionPossibleError

The desired matrix decomposition is not possible for this matrix. Only a subdecompostion could be calculated

MatrixError¶

class matrix.errors.MatrixError(matrix=None, message=None)[source]¶

Bases: Exception

An exception related to a matrix.

This is the base exception for all exceptions in this package.

Changelog¶

v0.3¶

dense and sparse matrices are now decomposable into several types (LL, LDL, LDL compressed)

v0.2¶

decompositons are now convertable to other decompositon types

decompositions are now comparable

v0.1¶

several decompositions types added (LL, LDL, LDL compressed)

permutation capabilities added

Welcome to matrix_decomposition’s documentation!¶

Functions¶

decompose¶

Matrix decompositions¶

LL decomposition¶

LDL decomposition¶

LDL decomposition compressed¶

base decomposition¶

Errors¶

MatrixNoDecompositionPossibleError¶

MatrixNoLDLDecompositionPossibleError¶

MatrixNoLLDecompositionPossibleError¶

MatrixDecompositionNoConversionImplementedError¶

MatrixNoDecompositionPossibleWithProblematicSubdecompositionError¶

MatrixError¶

Changelog¶

v0.3¶

v0.2¶

v0.1¶

Indices and tables¶

matrix-decomposition

Navigation

Related Topics