Coverage for src/cvx/linalg/__init__.py: 100%

1"""Linear algebra utilities for risk models. 

2 

3This subpackage provides linear algebra utilities commonly used in risk modeling, 

4including Cholesky decomposition, Principal Component Analysis, matrix norms, 

5linear-system solving, and matrix validation. 

6 

7Example: 

8 >>> import numpy as np 

9 >>> from cvx.linalg import a_norm, cholesky, eigh, inv_a_norm, pca, qr, rand_cov, solve, svd, valid 

10 >>> # Cholesky decomposition 

11 >>> cov = np.array([[4.0, 2.0], [2.0, 5.0]]) 

12 >>> R = cholesky(cov) 

13 >>> np.allclose(R.T @ R, cov) 

14 True 

15 

16Functions: 

17 a_norm: Compute the matrix norm of a vector 

18 check_and_warn_condition: Compute the condition number and warn if ill-conditioned 

19 cholesky: Compute upper triangular Cholesky decomposition 

20 cholesky_solve: Solve a linear system via Cholesky with LU fallback 

21 cond: Return the condition number of a matrix (NaN-aware) 

22 cov_to_corr: Convert a covariance matrix to a correlation matrix 

23 det: Compute the determinant of a square matrix 

24 eigvals: Compute eigenvalues of a general square matrix 

25 eigh: Compute eigenvalues and eigenvectors of a symmetric/Hermitian matrix 

26 eigvalsh: Compute eigenvalues of a symmetric/Hermitian matrix 

27 inv: Invert a matrix with NaN-aware matrix filtering and condition-number guarding 

28 inv_a_norm: Compute the inverse matrix norm of a vector 

29 is_positive_definite: Test whether a matrix is positive definite 

30 lstsq: Solve least-squares problems with NaN-aware row filtering 

31 norm: Compute the norm of a vector or matrix, ignoring non-finite entries 

32 pca: Compute principal components of return data 

33 power_iteration: Estimate the dominant eigenpair of a symmetric matrix 

34 qr: Compute reduced QR decomposition of a matrix 

35 rand_cov: Generate a random positive semi-definite covariance matrix 

36 solve: Solve linear systems with NaN-aware matrix filtering 

37 svd: Compute compact singular value decomposition 

38 svd_k: Compute the truncated rank-k singular value decomposition 

39 valid: Extract valid submatrix from a matrix with NaN values 

40 warn_ill_conditioned: Emit an IllConditionedMatrixWarning for a condition number 

41 

42Operators: 

43 SymmetricOperator: Protocol exposing a symmetric matrix through block products and a free-block solve 

44 DenseOperator: SymmetricOperator backed by an explicit dense matrix 

45 GramOperator: SymmetricOperator A = M.T @ M represented by its factor M (matrix-free) 

46 FactorOperator: Diagonal-plus-low-rank SymmetricOperator with Woodbury free-block solves 

47 IncrementalDenseOperator: DenseOperator maintaining the free-block inverse across single-index flips 

48 SumOperator: Weighted sum of symmetric operators (forward-only; feed apply_free to a Krylov solver) 

49 

50Constrained solves: 

51 bordered_solve: Range-space (Schur complement) solve of a bordered KKT system over a SymmetricOperator 

52 AffineProjection: Euclidean projection onto the affine set {x : C x = d}, caching the Gram matrix 

53 

54Types: 

55 Matrix: Type alias for a 2-D NumPy array 

56 Vector: Type alias for a 1-D NumPy array 

57 

58Exceptions: 

59 DimensionMismatchError: Raised when operand dimensions are incompatible 

60 InvalidComponentsError: Raised when the requested number of components is invalid 

61 NegativeWarmupError: Raised when an EWM warmup period is negative 

62 NonIntegerWarmupError: Raised when an EWM warmup period is not an integer 

63 NonSquareMatrixError: Raised when a square matrix is required but not given 

64 NotAMatrixError: Raised when an input is not a 2-D matrix 

65 SingularMatrixError: Raised when a matrix is singular and cannot be inverted/solved 

66 

67Warnings: 

68 IllConditionedMatrixWarning: Emitted when a matrix is ill-conditioned 

69 

70Constants: 

71 DEFAULT_COND_THRESHOLD: Default condition-number threshold for ill-conditioning checks 

72 

73""" 

74 

75from importlib.metadata import PackageNotFoundError, version 

76 

77from .core import DEFAULT_COND_THRESHOLD as DEFAULT_COND_THRESHOLD 

78from .core import DimensionMismatchError as DimensionMismatchError 

79from .core import IllConditionedMatrixWarning as IllConditionedMatrixWarning 

80from .core import InvalidComponentsError as InvalidComponentsError 

81from .core import Matrix as Matrix 

82from .core import NegativeWarmupError as NegativeWarmupError 

83from .core import NonIntegerWarmupError as NonIntegerWarmupError 

84from .core import NonSquareMatrixError as NonSquareMatrixError 

85from .core import NotAMatrixError as NotAMatrixError 

86from .core import SingularMatrixError as SingularMatrixError 

87from .core import Vector as Vector 

88from .core import check_and_warn_condition as check_and_warn_condition 

89from .core import cond as cond 

90from .core import valid as valid 

91from .core import warn_ill_conditioned as warn_ill_conditioned 

92from .covariance import cov_to_corr as cov_to_corr 

93from .covariance import pca as pca 

94from .covariance import rand_cov as rand_cov 

95from .decomposition import cholesky as cholesky 

96from .decomposition import cholesky_solve as cholesky_solve 

97from .decomposition import eigh as eigh 

98from .decomposition import eigvals as eigvals 

99from .decomposition import eigvalsh as eigvalsh 

100from .decomposition import is_positive_definite as is_positive_definite 

101from .decomposition import power_iteration as power_iteration 

102from .decomposition import qr as qr 

103from .decomposition import svd as svd 

104from .decomposition import svd_k as svd_k 

105from .kkt import AffineProjection as AffineProjection 

106from .kkt import bordered_solve as bordered_solve 

107from .norm import a_norm as a_norm 

108from .norm import inv_a_norm as inv_a_norm 

109from .norm import norm as norm 

110from .operators import DenseOperator as DenseOperator 

111from .operators import FactorOperator as FactorOperator 

112from .operators import GramOperator as GramOperator 

113from .operators import IncrementalDenseOperator as IncrementalDenseOperator 

114from .operators import SumOperator as SumOperator 

115from .operators import SymmetricOperator as SymmetricOperator 

116from .solve import det as det 

117from .solve import inv as inv 

118from .solve import lstsq as lstsq 

119from .solve import solve as solve 

120 

121__all__ = [ 

122 "DEFAULT_COND_THRESHOLD", 

123 "AffineProjection", 

124 "DenseOperator", 

125 "DimensionMismatchError", 

126 "FactorOperator", 

127 "GramOperator", 

128 "IllConditionedMatrixWarning", 

129 "IncrementalDenseOperator", 

130 "InvalidComponentsError", 

131 "Matrix", 

132 "NegativeWarmupError", 

133 "NonIntegerWarmupError", 

134 "NonSquareMatrixError", 

135 "NotAMatrixError", 

136 "SingularMatrixError", 

137 "SumOperator", 

138 "SymmetricOperator", 

139 "Vector", 

140 "a_norm", 

141 "bordered_solve", 

142 "check_and_warn_condition", 

143 "cholesky", 

144 "cholesky_solve", 

145 "cond", 

146 "cov_to_corr", 

147 "det", 

148 "eigh", 

149 "eigvals", 

150 "eigvalsh", 

151 "inv", 

152 "inv_a_norm", 

153 "is_positive_definite", 

154 "lstsq", 

155 "norm", 

156 "pca", 

157 "power_iteration", 

158 "qr", 

159 "rand_cov", 

160 "solve", 

161 "svd", 

162 "svd_k", 

163 "valid", 

164 "warn_ill_conditioned", 

165] 

166 

167try: 

168 __version__ = version("cvx-linalg") 

169except PackageNotFoundError: # pragma: no cover 

170 __version__ = "0.0.0"