Functions¶
Several functions are included in this package. The most important ones are summarized here.
Positive semidefinite approximation of a matrix¶
-
matrix.approximation.positive_semidefinite.
positive_semidefinite_matrix
(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, max_diag_D=None, min_abs_value_D=None, min_abs_value_L=None, permutation=None, overwrite_A=False)[source]¶ Computes an approximation of A which has a \(LDL^H\) decomposition with the specified properties.
Returns A if A has such a decomposition 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 or equal to 0. optional, default : Is chosen by the algorithm.
- 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.
- min_abs_value_D (float) – Absolute values below min_abs_value_D are considered as zero in the matrix D in a \(LDL^H\) decomposition of the returned matrix. min_abs_value_D must be greater or equal to 0. optional, default : The square root of the resolution of the underlying data type.
- min_abs_value_L (float) – Absolute values below min_abs_value_L are considered as zero in the matrix L of an approximated \(LDL^H\) decomposition. min_abs_value_L must be greater or equal to 0. optional, default : 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
orAPPROXIMATION_ONLY_PERMUTATION_METHODS
. If A is sparse, it can also be a value inmatrix.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 has a \(LDL^H\) decomposition.
Return type: numpy.ndarray or scipy.sparse.spmatrix (same type as A)
Raises: matrix.errors.MatrixNotSquareError
– If A is not a square matrix.matrix.errors.MatrixComplexDiagonalValueError
– If A has complex diagonal values.
-
matrix.approximation.positive_semidefinite.
decomposition
(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, max_diag_D=None, min_abs_value_D=None, min_abs_value_L=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 or equal to 0. optional, default : Is chosen by the algorithm.
- 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.
- min_abs_value_L (float) – Absolute values below min_abs_value_L are considered as zero in the matrix L of an approximated \(LDL^H\) decomposition. min_abs_value_L must be greater or equal to 0. optional, default : 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
orAPPROXIMATION_ONLY_PERMUTATION_METHODS
. If A is sparse, it can also be a value inmatrix.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: Raises: matrix.errors.MatrixNotSquareError
– If A is not a square matrix.matrix.errors.MatrixComplexDiagonalValueError
– If A has complex diagonal values.
-
matrix.approximation.positive_semidefinite.
APPROXIMATION_ONLY_PERMUTATION_METHODS
= ('minimal_difference', 'maximal_stability')¶ Permutation methods supported only by the decomposition and the positive_semidefinite_matrix algorithm.
-
matrix.approximation.positive_semidefinite.
GMW_81
(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, overwrite_A=False)[source]¶ Computes a positive definite approximation of A.
Returns A if A is positive definite and meets the constrains and otherwise a positive definite approximation of A.
Parameters: - A (numpy.ndarray) – The matrix that should be approximated. A must be symmetric.
- 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^T\) decomposition of the returned matrix is forced to be greater or equal to min_diag_D. min_diag_D must be positive. optional, default : 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: Raises: matrix.errors.MatrixNotSquareError
– If A is not a square matrix.Notes
The algorithm is introduced in [1]. Is is also described in [2]. This discription has been used for this implementation. The implementation has been extended to allow restrictions on the diagonal values.
References
- [1] Gill, P. E.; Murray, W. & Wright, M. H.,
- Practical optimization, Academic press, 1981
- [2] Fang, H.-r. & O’Leary, D. P.,
- Modified Cholesky algorithms: a catalog with new approaches, Mathematical Programming, 2008, 115, 319-349
-
matrix.approximation.positive_semidefinite.
GMW_T1
(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, overwrite_A=False)[source]¶ Computes a positive definite approximation of A.
Returns A if A is positive definite and meets the constrains and otherwise a positive definite approximation of A.
Parameters: - A (numpy.ndarray) – The matrix that should be approximated. A must be symmetric.
- 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^T\) decomposition of the returned matrix is forced to be greater or equal to min_diag_D. min_diag_D must be positive. optional, default : 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: Raises: matrix.errors.MatrixNotSquareError
– If A is not a square matrix.Notes
The algorithm is introduced in [1]. This discription has been used for this implementation. The algorithm is based on [2]. The implementation has been extended to allow restrictions on the diagonal values.
References
- [1] Fang, H.-r. & O’Leary, D. P.,
- Modified Cholesky algorithms: a catalog with new approaches, Mathematical Programming, 2008, 115, 319-349
- [2] Gill, P. E.; Murray, W. & Wright, M. H.,
- Practical optimization, Academic press, 1981
-
matrix.approximation.positive_semidefinite.
GMW_T2
(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, overwrite_A=False)[source]¶ Computes a positive definite approximation of A.
Returns A if A is positive definite and meets the constrains and otherwise a positive definite approximation of A.
Parameters: - A (numpy.ndarray) – The matrix that should be approximated. A must be symmetric.
- 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^T\) decomposition of the returned matrix is forced to be greater or equal to min_diag_D. min_diag_D must be positive. optional, default : 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: Raises: matrix.errors.MatrixNotSquareError
– If A is not a square matrix.Notes
The algorithm is introduced in [1]. This discription has been used for this implementation. The algorithm is based on [2]. The implementation has been extended to allow restrictions on the diagonal values.
References
- [1] Fang, H.-r. & O’Leary, D. P.,
- Modified Cholesky algorithms: a catalog with new approaches, Mathematical Programming, 2008, 115, 319-349
- [2] Gill, P. E.; Murray, W. & Wright, M. H.,
- Practical optimization, Academic press, 1981
-
matrix.approximation.positive_semidefinite.
SE_90
(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, overwrite_A=False)[source]¶ Computes a positive definite approximation of A.
Returns A if A is positive definite and meets the constrains and otherwise a positive definite approximation of A.
Parameters: - A (numpy.ndarray) – The matrix that should be approximated. A must be symmetric.
- 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^T\) decomposition of the returned matrix is forced to be greater or equal to min_diag_D. min_diag_D must be positive. optional, default : 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: Raises: matrix.errors.MatrixNotSquareError
– If A is not a square matrix.Notes
The algorithm is introduced in [1]. Is is also described in [2]. This discription has been used for this implementation. The implementation has been extended to allow restrictions on the diagonal values.
References
- [1] Schnabel, R. & Eskow, E.,
- A New Modified Cholesky Factorization, SIAM Journal on Scientific and Statistical Computing, 1990, 11, 1136-1158
- [2] Fang, H.-r. & O’Leary, D. P.,
- Modified Cholesky algorithms: a catalog with new approaches, Mathematical Programming, 2008, 115, 319-349
-
matrix.approximation.positive_semidefinite.
SE_99
(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, overwrite_A=False)[source]¶ Computes a positive definite approximation of A.
Returns A if A is positive definite and meets the constrains and otherwise a positive definite approximation of A.
Parameters: - A (numpy.ndarray) – The matrix that should be approximated. A must be symmetric.
- 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^T\) decomposition of the returned matrix is forced to be greater or equal to min_diag_D. min_diag_D must be positive. optional, default : 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: Raises: matrix.errors.MatrixNotSquareError
– If A is not a square matrix.Notes
The algorithm is introduced in [1]. Is is also described in [2]. This discription has been used for this implementation. The algorithm is based on [3]. The implementation has been extended to allow restrictions on the diagonal values.
References
- [1] Schnabel, R. & Eskow, E.,
- A Revised Modified Cholesky Factorization Algorithm, SIAM Journal on Optimization, 1999, 9, 1135-1148
- [2] Fang, H.-r. & O’Leary, D. P.,
- Modified Cholesky algorithms: a catalog with new approaches, Mathematical Programming, 2008, 115, 319-349
- [3] Schnabel, R. & Eskow, E.,
- A New Modified Cholesky Factorization, SIAM Journal on Scientific and Statistical Computing, 1990, 11, 1136-1158
-
matrix.approximation.positive_semidefinite.
SE_T1
(A, min_diag_B=None, max_diag_B=None, min_diag_D=None, overwrite_A=False)[source]¶ Computes a positive definite approximation of A.
Returns A if A is positive definite and meets the constrains and otherwise a positive definite approximation of A.
Parameters: - A (numpy.ndarray) – The matrix that should be approximated. A must be symmetric.
- 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^T\) decomposition of the returned matrix is forced to be greater or equal to min_diag_D. min_diag_D must be positive. optional, default : 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: Raises: matrix.errors.MatrixNotSquareError
– If A is not a square matrix.Notes
The algorithm is introduced in [1]. This discription has been used for this implementation. The algorithm is based on [2]. The implementation has been extended to allow restrictions on the diagonal values.
References
- [1] Fang, H.-r. & O’Leary, D. P.,
- Modified Cholesky algorithms: a catalog with new approaches, Mathematical Programming, 2008, 115, 319-349
- [2] Schnabel, R. & Eskow, E.,
- A Revised Modified Cholesky Factorization Algorithm, SIAM Journal on Optimization, 1999, 9, 1135-1148
- [3] Schnabel, R. & Eskow, E.,
- A New Modified Cholesky Factorization, SIAM Journal on Scientific and Statistical Computing, 1990, 11, 1136-1158
Nearest matrix with specific properties¶
This module provides functions to compute matrices with minimal difference to an input matrix and specific properties.
-
matrix.nearest.
correlation_matrix
(A, max_iterations=1000)[source]¶ Computes a correlation matrix closest to A in the Frobenius norm. A correlation matrix is a positive semidefinite matrix with ones on the diagonal.
Parameters: - A (numpy.ndarray) – A must be Hermitian.
- max_iterations (int) – The maximal number of iterations used for the calculation.
Returns: B – A correlation matrix closest to A in the Frobenius norm.
Return type: Raises: TooManyIterationsError
– If the computation needs more iterations than the maximal number of iterations.Notes
The method is presented in [1]. For the computation some code of Michael Croucher is used. See this source code for the license.
References
- [1] Higham, N. J.
- Computing the Nearest Correlation Matrix—A Problem from Finance IMA J. Numer. Anal., 2002, 22, 329-343
-
matrix.nearest.
positive_semidefinite_matrix
(A, symmetric=False)[source]¶ Computes a symmetric positive semidefinite matrix with minimal difference to A in the Frobenius norm.
Parameters: - A (numpy.ndarray) – A must be Hermitian.
- symmetric (bool) – Whether A can be assumed to be symmetric or not. optional, default: False
Returns: B – A symmetric positive semidefinite Hermitian matrix with minimal difference to A in the Frobenius norm.
Return type: Notes
The method is presented in [1].
References
- [1] Higham, N. J.
- Computing a nearest symmetric positive semidefinite matrix Linear Algebra and its Applications, 1988, 103, 103-118
-
matrix.nearest.
skew_symmetric_matrix
(A)[source]¶ Computes a skew-symmetric matrix with minimal difference to A for any unitarily invariant norm.
Parameters: A (numpy.ndarray) – A must be a square matrix. Returns: B – A skew-symmetric matrix with minimal difference to A for any unitarily invariant norm. Return type: numpy.ndarray
-
matrix.nearest.
symmetric_matrix
(A)[source]¶ Computes a symmetric matrix with minimal difference to A for any unitarily invariant norm.
Parameters: A (numpy.ndarray) – A must be a square matrix. Returns: B – A symmetric matrix with minimal difference to A for any unitarily invariant norm. Return type: numpy.ndarray Notes
The optimality is proven in [1].
References
- [1] Fan, K., & Hoffman, A. (1955).
- Some Metric Inequalities in the Space of Matrices. Proceedings of the American Mathematical Society, 6(1), 111-116. doi:10.2307/2032662
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 inmatrix.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: Raises: matrix.errors.NoDecompositionPossibleError
– If the decomposition of A is not possible.matrix.errors.MatrixNotSquareError
– If A is not a square matrix.matrix.errors.MatrixNotFiniteError
– If A is not a finite matrix and check_finite is True.
-
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.
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: 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: 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: 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: Raises: matrix.errors.MatrixNotSquareError
– If A is not a square matrix.matrix.errors.MatrixNotFiniteError
– If A is not a finite matrix and check_finite is True.matrix.errors.MatrixSingularError
– If A is singular.