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
« 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.
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"""
12from __future__ import annotations
14import numpy as np
15from cvx.linalg import DenseOperator, FactorOperator, GramOperator, IncrementalDenseOperator
16from numpy.typing import NDArray
19def _symmetric_matrix(matrix: NDArray[np.float64]) -> NDArray[np.float64]:
20 """Return *matrix* as a float array after checking it is square and symmetric.
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
38def dense_covariance(matrix: NDArray[np.float64]) -> DenseOperator:
39 """Build a :class:`~cvx.linalg.DenseOperator` from an explicit symmetric covariance.
41 Args:
42 matrix: A symmetric ``(n, n)`` covariance matrix.
44 Returns:
45 A dense symmetric operator wrapping *matrix*.
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.])
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:
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))
69def incremental_dense_covariance(matrix: NDArray[np.float64]) -> IncrementalDenseOperator:
70 """Build an :class:`~cvx.linalg.IncrementalDenseOperator` (maintained free-block inverse).
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.
75 Args:
76 matrix: A symmetric ``(n, n)`` covariance matrix.
78 Returns:
79 A dense symmetric operator that maintains the free-block inverse.
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
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.
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))
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*.
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.
108 Args:
109 returns: The ``(T, n)`` matrix of observations (``T >= 2``).
110 ridge: A non-negative diagonal loading added to the covariance.
112 Returns:
113 A matrix-free Gram operator for the (ridged) sample covariance.
115 Raises:
116 ValueError: If *returns* is not a ``(T, n)`` matrix with ``T >= 2``.
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)
124 The operator represents exactly the sample covariance ``np.cov`` would
125 form -- without ever building the ``(n, n)`` matrix:
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
133 ``ridge`` adds a diagonal loading, which is how a short sample (fewer
134 observations than assets) is made positive definite:
136 >>> float(np.round(GramCovariance(returns, ridge=0.5).diag[0] - op.diag[0], 12))
137 0.5
139 A single observation cannot define a covariance and is refused:
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)
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``.
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)``.
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.
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).
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.
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)
202 The operator matches its dense materialisation while storing only
203 ``d`` and ``u`` -- the point of the diagonal-plus-low-rank form:
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
210 ``delta`` may equally be a full ``(k, k)`` factor covariance:
212 >>> bool(np.allclose(FactorCovariance(d=d, u=u, delta=np.diag(delta)).matvec(x), dense @ x))
213 True
215 A singular factor covariance is folded away: two perfectly correlated
216 factors are one factor.
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
225 Anything else is refused, as is a factor covariance with a negative
226 eigenvalue:
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]))
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