Functions

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

Decompose a matrix

matrix.decompose(A, permutation=None, return_type=None, check_finite=True, overwrite_A=False)[source]

Computes a decomposition of a matrix.

Parameters:
  • A (numpy.ndarray or scipy.sparse.spmatrix) – Matrix to be decomposed. A must be Hermitian.
  • permutation (str or numpy.ndarray) – The symmetric permutation method that is applied to the matrix before it is decomposed. It has to be a value in matrix.UNIVERSAL_PERMUTATION_METHODS. If A is sparse, it can also be a value in matrix.SPARSE_ONLY_PERMUTATION_METHODS. It is also possible to directly pass a permutation vector. optional, default: no permutation
  • return_type (str) – The type of the decomposition that should be calculated. It has to be a value in matrix.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
  • check_finite (bool) – Whether to check that A contains only finite numbers. Disabling may result in problems (crashes, non-termination) if the inputs do contain infinities or NaNs. Disabling gives a performance gain. optional, default: True
  • overwrite_A (bool) – Whether it is allowed to overwrite A. Enabling may result in performance gain. optional, default: False
Returns:

A decomposition of A of type return_type.
Return type:

matrix.decompositions.DecompositionBase
Raises:
matrix.UNIVERSAL_PERMUTATION_METHODS = ('none', 'decreasing_diagonal_values', 'increasing_diagonal_values', 'decreasing_absolute_diagonal_values', 'increasing_absolute_diagonal_values')

Supported permutation methods for decompose dense and sparse matrices.

matrix.SPARSE_ONLY_PERMUTATION_METHODS = ()

Supported permutation methods only for sparse matrices.

matrix.DECOMPOSITION_TYPES = ('LDL', 'LDL_compressed', 'LL')

Supported types of decompositions.

Approximate a matrix

matrix.approximate.decomposition(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, max_diag_D=None, min_abs_value_D=None, permutation=None, overwrite_A=False, return_type=None)[source]

Computes an approximative decomposition of a matrix with the specified properties.

Returns a decomposition of A if has such a decomposition and otherwise a decomposition of an approximation of A.

Parameters:
  • A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be approximated by a decomposition. A must be Hermitian.
  • min_diag_B (numpy.ndarray or float) – Each component of the diagonal of the composed matrix B of an approximated \(LDL^H\) decomposition is forced to be greater or equal to min_diag_B. optional, default : No minimal value is forced.
  • max_diag_B (numpy.ndarray or float) – Each component of the diagonal of the composed matrix B of an approximated \(LDL^H\) decomposition is forced to be lower or equal to max_diag_B. optional, default : No maximal value is forced.
  • min_diag_D (float) – Each component of the diagonal of the matrix D in an approximated \(LDL^H\) decomposition is forced to be greater or equal to min_diag_D. min_diag_D must be greater than 0. optional, default : The square root of the resolution of the underlying data type.
  • max_diag_D (float) – Each component of the diagonal of the matrix D in an approximated \(LDL^H\) decomposition is forced to be lower or equal to max_diag_D. optional, default : No maximal value is forced.
  • min_abs_value_D (float) – Absolute values below min_abs_value_D are considered as zero in the matrix D of an approximated \(LDL^H\) decomposition. min_abs_value_D must be greater or equal to 0. optional, default : The square root of the resolution of the underlying data type.
  • permutation (str or numpy.ndarray) – The symmetric permutation method that is applied to the matrix before it is decomposed. It has to be a value in matrix.UNIVERSAL_PERMUTATION_METHODS or matrix.APPROXIMATION_ONLY_PERMUTATION_METHODS. If A is sparse, it can also be a value in matrix.SPARSE_ONLY_PERMUTATION_METHODS. It is also possible to directly pass a permutation vector. optional, default: The permutation is chosen by the algorithm.
  • overwrite_A (bool) – Whether it is allowed to overwrite A. Enabling may result in performance gain. optional, default: False
  • return_type (str) – The type of the decomposition that should be returned. It has to be a value in matrix.DECOMPOSITION_TYPES. optional, default : The type of the decomposition is chosen by the function itself.
Returns:

An (approximative) decomposition of A of type return_type.
Return type:

matrix.decompositions.DecompositionBase
Raises:
matrix.approximate.positive_definite_matrix(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, max_diag_D=None, permutation=None, overwrite_A=False)[source]

Computes a positive definite approximation of A.

Returns A if A is positive definite and otherwise an approximation of A.

Parameters:
  • A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be approximated. A must be Hermitian.
  • min_diag_B (numpy.ndarray or float) – Each component of the diagonal of the returned matrix is forced to be greater or equal to min_diag_B. optional, default : No minimal value is forced.
  • max_diag_B (numpy.ndarray or float) – Each component of the diagonal of the returned matrix is forced to be lower or equal to max_diag_B. optional, default : No maximal value is forced.
  • min_diag_D (float) – Each component of the diagonal of the matrix D in a \(LDL^H\) decomposition of the returned matrix is forced to be greater or equal to min_diag_D. min_diag_D must be greater than 0. optional, default : The square root of the resolution of the underlying data type.
  • max_diag_D (float) – Each component of the diagonal of the matrix D in a \(LDL^H\) decomposition of the returned matrix is forced to be lower or equal to max_diag_D. optional, default : No maximal value is forced.
  • permutation (str or numpy.ndarray) – The symmetric permutation method that is applied to the matrix before it is decomposed. It has to be a value in matrix.UNIVERSAL_PERMUTATION_METHODS or matrix.APPROXIMATION_ONLY_PERMUTATION_METHODS. If A is sparse, it can also be a value in matrix.SPARSE_ONLY_PERMUTATION_METHODS. It is also possible to directly pass a permutation vector. optional, default: The permutation is chosen by the algorithm.
  • overwrite_A (bool) – Whether it is allowed to overwrite A. Enabling may result in performance gain. optional, default: False
Returns:

B – An approximation of A which is positive definite.
Return type:

numpy.ndarray or scipy.sparse.spmatrix (same type as A)
Raises:
matrix.APPROXIMATION_ONLY_PERMUTATION_METHODS = ('minimal_difference',)

Supported permutation methods only for approximate dense and sparse matrices.

Examine a matrix

matrix.is_positive_semidefinite(A, check_finite=True)[source]

Returns whether the passed matrix is positive semi-definite.

Parameters:
  • A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be checked. A must be Hermitian.
  • check_finite (bool) – Whether to check that A contain only finite numbers. Disabling may result in problems (crashes, non-termination) if they contain infinities or NaNs. Disabling gives a performance gain. optional, default: True
Returns:

Whether A is positive semi-definite.
Return type:

bool
Raises:

matrix.errors.MatrixNotFiniteError – If A is not a finite matrix and check_finite is True.
matrix.is_positive_definite(A, check_finite=True)[source]

Returns whether the passed matrix is positive definite.

Parameters:
  • A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be checked. A must be Hermitian.
  • check_finite (bool) – Whether to check that A contain only finite numbers. Disabling may result in problems (crashes, non-termination) if they contain infinities or NaNs. Disabling gives a performance gain. optional, default: True
Returns:

Whether A is positive definite.
Return type:

bool
Raises:

matrix.errors.MatrixNotFiniteError – If A is not a finite matrix and check_finite is True.
matrix.is_invertible(A, check_finite=True)[source]

Returns whether the passed matrix is an invertible matrix.

Parameters:
  • A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be checked. A must be Hermitian and positive semidefinite.
  • check_finite (bool) – Whether to check that A contain only finite numbers. Disabling may result in problems (crashes, non-termination) if they contain infinities or NaNs. Disabling gives a performance gain. optional, default: True
Returns:

Whether A is invertible.
Return type:

bool
Raises:

matrix.errors.MatrixNotFiniteError – If A is not a finite matrix and check_finite is True.

Solve system of linear equations

matrix.solve(A, b, overwrite_b=False, check_finite=True)[source]

Solves the equation A x = b regarding x.

Parameters:
  • A (numpy.ndarray or scipy.sparse.spmatrix) – The matrix that should be checked. A must be Hermitian and positive definite.
  • b (numpy.ndarray) – Right-hand side vector or matrix in equation A x = b. It must hold b.shape[0] == A.shape[0].
  • overwrite_b (bool) – Allow overwriting data in b. Enabling gives a performance gain. optional, default: False
  • check_finite (bool) – Whether to check that A and b` contain only finite numbers. Disabling may result in problems (crashes, non-termination) if they contain infinities or NaNs. Disabling gives a performance gain. optional, default: True
Returns:

An x so that A x = b. The shape of x matches the shape of b.
Return type:

numpy.ndarray
Raises: