Coverage for src/cvxcla/operators/builders.py: 100%

57 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-17 13:36 +0000

1"""Builders that assemble cvx-linalg symmetric operators from CLA / LASSO inputs. 

2 

3These replace the former operator *classes*. The numerics -- matrix-vector and 

4block products, free-block solves (Cholesky, Woodbury, maintained inverse), and 

5the reciprocal-condition check -- now live in :mod:`cvx.linalg`. Here we only 

6build the right operator from the domain inputs: a covariance matrix, a 

7returns / data matrix, or a factor model. The backward-compatible names 

8``DenseCovariance`` / ``IncrementalDenseCovariance`` / ``GramCovariance`` / 

9``FactorCovariance`` are kept as aliases of these builders. 

10""" 

11 

12from __future__ import annotations 

13 

14import numpy as np 

15from cvx.linalg import DenseOperator, FactorOperator, GramOperator, IncrementalDenseOperator 

16from numpy.typing import NDArray 

17 

18 

19def _symmetric_matrix(matrix: NDArray[np.float64]) -> NDArray[np.float64]: 

20 """Return *matrix* as a float array after checking it is square and symmetric. 

21 

22 Raises: 

23 ValueError: If *matrix* is not square, not finite, or not symmetric to tolerance. 

24 """ 

25 matrix = np.asarray(matrix, dtype=np.float64) 

26 if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]: 

27 msg = f"Covariance must be a square matrix, got shape {matrix.shape}" 

28 raise ValueError(msg) 

29 if not np.all(np.isfinite(matrix)): 

30 msg = "Covariance must be finite (no NaN or infinite entries)" 

31 raise ValueError(msg) 

32 if not np.allclose(matrix, matrix.T): 

33 msg = "Covariance must be symmetric" 

34 raise ValueError(msg) 

35 return matrix 

36 

37 

38def dense_covariance(matrix: NDArray[np.float64]) -> DenseOperator: 

39 """Build a :class:`~cvx.linalg.DenseOperator` from an explicit symmetric covariance. 

40 

41 Args: 

42 matrix: A symmetric ``(n, n)`` covariance matrix. 

43 

44 Returns: 

45 A dense symmetric operator wrapping *matrix*. 

46 

47 Examples: 

48 >>> import numpy as np 

49 >>> from cvxcla import DenseCovariance 

50 >>> sigma = np.array([[4.0, 1.0], [1.0, 9.0]]) 

51 >>> op = DenseCovariance(sigma) 

52 >>> op.n 

53 2 

54 >>> op.matvec(np.array([1.0, 0.0])) 

55 array([4., 1.]) 

56 

57 A non-square or non-symmetric input is rejected rather than silently 

58 symmetrised, so a transposed or half-filled matrix fails at construction 

59 instead of producing a wrong frontier: 

60 

61 >>> DenseCovariance(np.array([[1.0, 2.0], [0.0, 1.0]])) 

62 Traceback (most recent call last): 

63 ... 

64 ValueError: Covariance must be symmetric 

65 """ 

66 return DenseOperator(_symmetric_matrix(matrix)) 

67 

68 

69def incremental_dense_covariance(matrix: NDArray[np.float64]) -> IncrementalDenseOperator: 

70 """Build an :class:`~cvx.linalg.IncrementalDenseOperator` (maintained free-block inverse). 

71 

72 A drop-in alternative to :func:`dense_covariance` for a loop that changes its 

73 free set one index at a time; see the operator's own caveats on numerics. 

74 

75 Args: 

76 matrix: A symmetric ``(n, n)`` covariance matrix. 

77 

78 Returns: 

79 A dense symmetric operator that maintains the free-block inverse. 

80 

81 Examples: 

82 >>> import numpy as np 

83 >>> from cvxcla import CLA, DenseCovariance, IncrementalDenseCovariance 

84 >>> sigma = np.array([[4.0, 1.0], [1.0, 9.0]]) 

85 >>> x = np.array([1.0, 2.0]) 

86 >>> incremental = IncrementalDenseCovariance(sigma) 

87 >>> bool(np.allclose(incremental.matvec(x), DenseCovariance(sigma).matvec(x))) 

88 True 

89 

90 It is a drop-in swap: the two agree on the same problem, and only the 

91 cost profile of the free-block solves differs. 

92 

93 >>> cla = CLA.problem(np.array([0.1, 0.2]), incremental).long_only().budget().trace() 

94 >>> len(cla) > 0 

95 True 

96 """ 

97 return IncrementalDenseOperator(_symmetric_matrix(matrix)) 

98 

99 

100def gram_covariance(returns: NDArray[np.float64], ridge: float = 0.0) -> GramOperator: 

101 """Build a :class:`~cvx.linalg.GramOperator` for the sample covariance of *returns*. 

102 

103 The sample covariance ``X_c.T X_c / (T - 1)`` (``X_c`` the column-centered 

104 ``(T, n)`` data) is realised by absorbing the scale into the factor: 

105 ``M = sqrt(1 / (T - 1)) * X_c``, so the operator represents 

106 ``M.T M + ridge * I`` and never forms the ``n x n`` covariance. 

107 

108 Args: 

109 returns: The ``(T, n)`` matrix of observations (``T >= 2``). 

110 ridge: A non-negative diagonal loading added to the covariance. 

111 

112 Returns: 

113 A matrix-free Gram operator for the (ridged) sample covariance. 

114 

115 Raises: 

116 ValueError: If *returns* is not a ``(T, n)`` matrix with ``T >= 2``. 

117 

118 Examples: 

119 >>> import numpy as np 

120 >>> from cvxcla import GramCovariance 

121 >>> returns = np.array([[1.0, 2.0], [3.0, 5.0], [5.0, 4.0]]) 

122 >>> op = GramCovariance(returns) 

123 

124 The operator represents exactly the sample covariance ``np.cov`` would 

125 form -- without ever building the ``(n, n)`` matrix: 

126 

127 >>> sample = np.cov(returns, rowvar=False) 

128 >>> bool(np.allclose(op.matvec(np.array([1.0, 2.0])), sample @ np.array([1.0, 2.0]))) 

129 True 

130 >>> bool(np.allclose(op.diag, sample.diagonal())) 

131 True 

132 

133 ``ridge`` adds a diagonal loading, which is how a short sample (fewer 

134 observations than assets) is made positive definite: 

135 

136 >>> float(np.round(GramCovariance(returns, ridge=0.5).diag[0] - op.diag[0], 12)) 

137 0.5 

138 

139 A single observation cannot define a covariance and is refused: 

140 

141 >>> GramCovariance(np.array([[1.0, 2.0]])) 

142 Traceback (most recent call last): 

143 ... 

144 ValueError: returns must be a (T, n) matrix with T >= 2 observations, got shape (1, 2) 

145 """ 

146 returns = np.asarray(returns, dtype=np.float64) 

147 if returns.ndim != 2 or returns.shape[0] < 2: 

148 msg = f"returns must be a (T, n) matrix with T >= 2 observations, got shape {returns.shape}" 

149 raise ValueError(msg) 

150 t = returns.shape[0] 

151 centered = returns - returns.mean(axis=0, keepdims=True) 

152 factor = centered / np.sqrt(t - 1.0) 

153 return GramOperator(factor, ridge=ridge) 

154 

155 

156def factor_covariance( 

157 d: NDArray[np.float64], 

158 u: NDArray[np.float64], 

159 delta: NDArray[np.float64], 

160) -> FactorOperator: 

161 """Build a :class:`~cvx.linalg.FactorOperator` for ``Sigma = diag(d) + U Delta U.T``. 

162 

163 ``Delta`` is folded into the loadings before the operator is built: with 

164 ``Delta = V Lambda V.T`` the operator stores ``U' = U V_+ Lambda_+^{1/2}`` (the 

165 directions of positive variance) and an identity inner matrix, which is the same 

166 ``Sigma``. The Woodbury solve then never inverts ``Delta``, so a singular factor 

167 covariance -- a factor with zero variance, or more factors than the covariance 

168 spans -- is admissible, and an ill-conditioned one costs no accuracy. ``d > 0`` 

169 is required (and checked by the operator): it makes every principal block of 

170 ``Sigma`` positive definite, which is what lets the Woodbury capacitance matrix 

171 ``I + U_F'.T D_F^{-1} U_F'`` be factorised by Cholesky and ``rcond_free`` be 

172 bounded from ``min(d_F)``. 

173 

174 Args: 

175 d: Positive idiosyncratic variances of shape ``(n,)``. 

176 u: Factor loadings of shape ``(n, k)``. 

177 delta: Factor covariance, either ``(k,)`` non-negative variances (a diagonal 

178 ``Delta``) or a symmetric positive-semidefinite ``(k, k)`` matrix. 

179 

180 Returns: 

181 A diagonal-plus-low-rank operator with Woodbury free-block solves, whose 

182 rank ``k`` is the number of positive-variance factor directions (at least 1). 

183 

184 Raises: 

185 ValueError: If *delta* is neither a ``(k,)`` vector nor a ``(k, k)`` 

186 matrix, is not symmetric, or has a negative eigenvalue. A signed 

187 low-rank term can still give a positive-definite ``Sigma``, but then 

188 the capacitance matrix is indefinite and positive definiteness of 

189 ``Sigma`` would need a separate check; pass such a covariance as a 

190 dense matrix. 

191 

192 Examples: 

193 >>> import numpy as np 

194 >>> from cvxcla import FactorCovariance 

195 >>> d = np.array([0.5, 0.5, 0.5]) 

196 >>> u = np.array([[1.0], [1.0], [-1.0]]) 

197 >>> delta = np.array([2.0]) 

198 >>> op = FactorCovariance(d=d, u=u, delta=delta) 

199 >>> op.n, op.k 

200 (3, 1) 

201 

202 The operator matches its dense materialisation while storing only 

203 ``d`` and ``u`` -- the point of the diagonal-plus-low-rank form: 

204 

205 >>> dense = np.diag(d) + u @ np.diag(delta) @ u.T 

206 >>> x = np.array([1.0, 0.0, 0.0]) 

207 >>> bool(np.allclose(op.matvec(x), dense @ x)) 

208 True 

209 

210 ``delta`` may equally be a full ``(k, k)`` factor covariance: 

211 

212 >>> bool(np.allclose(FactorCovariance(d=d, u=u, delta=np.diag(delta)).matvec(x), dense @ x)) 

213 True 

214 

215 A singular factor covariance is folded away: two perfectly correlated 

216 factors are one factor. 

217 

218 >>> two = np.column_stack([u, 2 * u]) 

219 >>> op2 = FactorCovariance(d=d, u=two, delta=np.ones((2, 2))) 

220 >>> op2.k 

221 1 

222 >>> bool(np.allclose(op2.matvec(x), (np.diag(d) + two @ np.ones((2, 2)) @ two.T) @ x)) 

223 True 

224 

225 Anything else is refused, as is a factor covariance with a negative 

226 eigenvalue: 

227 

228 >>> FactorCovariance(d=d, u=u, delta=np.zeros((1, 1, 1))) 

229 Traceback (most recent call last): 

230 ... 

231 ValueError: delta must be a (k,) vector or (k, k) matrix, got ndim 3 

232 >>> FactorCovariance(d=d, u=u, delta=np.array([-1.0])) 

233 Traceback (most recent call last): 

234 ... 

235 ValueError: delta must be positive semidefinite (smallest eigenvalue -1); pass such a Sigma densely 

236 """ 

237 d = np.asarray(d, dtype=np.float64) 

238 u = np.asarray(u, dtype=np.float64) 

239 delta = np.asarray(delta, dtype=np.float64) 

240 if delta.ndim == 1: 

241 inner = np.diag(delta) 

242 elif delta.ndim == 2: 

243 inner = delta 

244 else: 

245 msg = f"delta must be a (k,) vector or (k, k) matrix, got ndim {delta.ndim}" 

246 raise ValueError(msg) 

247 if not np.allclose(inner, inner.T): 

248 msg = "delta must be symmetric" 

249 raise ValueError(msg) 

250 variances, directions = np.linalg.eigh(inner) if inner.size else (np.ones(0), inner) 

251 # Eigenvalues within round-off of zero are zero; below that, Delta is indefinite. 

252 floor = max(inner.shape[0], 1) * np.finfo(np.float64).eps * float(np.max(np.abs(variances), initial=0.0)) 

253 smallest = float(variances[0]) if variances.size else 0.0 

254 if smallest < -floor: 

255 msg = f"delta must be positive semidefinite (smallest eigenvalue {smallest:.3g}); pass such a Sigma densely" 

256 raise ValueError(msg) 

257 keep = variances > floor 

258 folded = (u @ directions[:, keep]) * np.sqrt(variances[keep]) 

259 if folded.shape[1] == 0: # Delta = 0: Sigma = diag(d), kept as one zero factor 

260 folded = np.zeros((u.shape[0], 1)) 

261 return FactorOperator(d, folded, np.eye(folded.shape[1])) 

262 

263 

264# Backward-compatible names: the operator *classes* are gone, but the familiar 

265# constructor-style names remain as builders returning cvx-linalg operators. 

266DenseCovariance = dense_covariance 

267IncrementalDenseCovariance = incremental_dense_covariance 

268GramCovariance = gram_covariance 

269FactorCovariance = factor_covariance