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 SupportsMatvec: Structural protocol for a matrix-free operator (exposes n and matvec) 

58 

59Exceptions: 

60 DimensionMismatchError: Raised when operand dimensions are incompatible 

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

62 NegativeWarmupError: Raised when an EWM warmup period is negative 

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

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

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

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

67 

68Warnings: 

69 IllConditionedMatrixWarning: Emitted when a matrix is ill-conditioned 

70 

71Constants: 

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

73 

74""" 

75 

76from importlib.metadata import PackageNotFoundError, version 

77 

78from .core import DEFAULT_COND_THRESHOLD as DEFAULT_COND_THRESHOLD 

79from .core import DimensionMismatchError as DimensionMismatchError 

80from .core import IllConditionedMatrixWarning as IllConditionedMatrixWarning 

81from .core import InvalidComponentsError as InvalidComponentsError 

82from .core import Matrix as Matrix 

83from .core import NegativeWarmupError as NegativeWarmupError 

84from .core import NonIntegerWarmupError as NonIntegerWarmupError 

85from .core import NonSquareMatrixError as NonSquareMatrixError 

86from .core import NotAMatrixError as NotAMatrixError 

87from .core import SingularMatrixError as SingularMatrixError 

88from .core import SupportsMatvec as SupportsMatvec 

89from .core import Vector as Vector 

90from .core import check_and_warn_condition as check_and_warn_condition 

91from .core import cond as cond 

92from .core import valid as valid 

93from .core import warn_ill_conditioned as warn_ill_conditioned 

94from .covariance import cov_to_corr as cov_to_corr 

95from .covariance import pca as pca 

96from .covariance import rand_cov as rand_cov 

97from .decomposition import cholesky as cholesky 

98from .decomposition import cholesky_solve as cholesky_solve 

99from .decomposition import eigh as eigh 

100from .decomposition import eigvals as eigvals 

101from .decomposition import eigvalsh as eigvalsh 

102from .decomposition import is_positive_definite as is_positive_definite 

103from .decomposition import power_iteration as power_iteration 

104from .decomposition import qr as qr 

105from .decomposition import svd as svd 

106from .decomposition import svd_k as svd_k 

107from .kkt import AffineProjection as AffineProjection 

108from .kkt import bordered_solve as bordered_solve 

109from .norm import a_norm as a_norm 

110from .norm import inv_a_norm as inv_a_norm 

111from .norm import norm as norm 

112from .operators import DenseOperator as DenseOperator 

113from .operators import FactorOperator as FactorOperator 

114from .operators import GramOperator as GramOperator 

115from .operators import IncrementalDenseOperator as IncrementalDenseOperator 

116from .operators import SumOperator as SumOperator 

117from .operators import SymmetricOperator as SymmetricOperator 

118from .solve import det as det 

119from .solve import inv as inv 

120from .solve import lstsq as lstsq 

121from .solve import solve as solve 

122 

123__all__ = [ 

124 "DEFAULT_COND_THRESHOLD", 

125 "AffineProjection", 

126 "DenseOperator", 

127 "DimensionMismatchError", 

128 "FactorOperator", 

129 "GramOperator", 

130 "IllConditionedMatrixWarning", 

131 "IncrementalDenseOperator", 

132 "InvalidComponentsError", 

133 "Matrix", 

134 "NegativeWarmupError", 

135 "NonIntegerWarmupError", 

136 "NonSquareMatrixError", 

137 "NotAMatrixError", 

138 "SingularMatrixError", 

139 "SumOperator", 

140 "SupportsMatvec", 

141 "SymmetricOperator", 

142 "Vector", 

143 "a_norm", 

144 "bordered_solve", 

145 "check_and_warn_condition", 

146 "cholesky", 

147 "cholesky_solve", 

148 "cond", 

149 "cov_to_corr", 

150 "det", 

151 "eigh", 

152 "eigvals", 

153 "eigvalsh", 

154 "inv", 

155 "inv_a_norm", 

156 "is_positive_definite", 

157 "lstsq", 

158 "norm", 

159 "pca", 

160 "power_iteration", 

161 "qr", 

162 "rand_cov", 

163 "solve", 

164 "svd", 

165 "svd_k", 

166 "valid", 

167 "warn_ill_conditioned", 

168] 

169 

170try: 

171 __version__ = version("cvx-linalg") 

172except PackageNotFoundError: # pragma: no cover 

173 __version__ = "0.0.0"