fast-minimum-variance 0.2.0__py3-none-any.whl

fast_minimum_variance/__init__.py

@@ -0,0 +1 @@
+"""fast_minimum_variance."""

fast_minimum_variance/cvx.py

@@ -0,0 +1,37 @@
+"""Convex optimization solver for the minimum variance portfolio."""
+
+import cvxpy as cp
+
+
+def minvar_cvxpy(R):  # noqa: N803
+    """Solve the minimum variance portfolio via CVXPY.
+
+    Solves the long-only minimum variance problem::
+
+        min  ||R w||_2^2
+        s.t. sum(w) = 1,  w >= 0
+
+    using CVXPY with its default solver.
+
+    Args:
+        R: Return matrix of shape (T, N).
+
+    Returns:
+        Weight vector of shape (N,) summing to 1 with all non-negative entries.
+
+    Examples:
+        >>> import numpy as np
+        >>> from fast_minimum_variance.random import make_returns
+        >>> R = make_returns(100, 5, seed=0)
+        >>> w = minvar_cvxpy(R)
+        >>> w.shape
+        (5,)
+        >>> float(round(w.sum(), 6))
+        1.0
+        >>> bool((w >= -1e-6).all())
+        True
+    """
+    n = R.shape[1]
+    w = cp.Variable(n)
+    cp.Problem(cp.Minimize(cp.sum_squares(R @ w)), [cp.sum(w) == 1, w >= 0]).solve()
+    return w.value

fast_minimum_variance/kkt.py

@@ -0,0 +1,81 @@
+"""KKT system construction for the minimum variance portfolio."""
+
+import numpy as np
+
+
+def build_kkt(R):  # noqa: N803
+    """Build the KKT system matrix and RHS for the minimum variance problem.
+
+    Constructs the (N+1) x (N+1) indefinite KKT system for::
+
+        min  w^T (R^T R) w
+        s.t. sum(w) = 1
+
+    The system has the form::
+
+        [ 2 R^T R   1 ] [ w ]   [ 0 ]
+        [ 1^T       0 ] [ λ ] = [ 1 ]
+
+    Args:
+        R: Return matrix of shape (T, N).
+
+    Returns:
+        Tuple (A, b) where A is the (N+1) x (N+1) KKT matrix and b is the
+        (N+1,) right-hand side vector.
+
+    Examples:
+        >>> import numpy as np
+        >>> R = np.eye(3)
+        >>> A, b = build_kkt(R)
+        >>> A.shape
+        (4, 4)
+        >>> b
+        array([0., 0., 0., 1.])
+    """
+    n_a = R.shape[1]
+    A = np.zeros((n_a + 1, n_a + 1))  # noqa: N806
+    A[:n_a, :n_a] = 2 * R.T @ R
+    A[:n_a, n_a] = 1
+    A[n_a, :n_a] = 1
+    b = np.zeros(n_a + 1)
+    b[n_a] = 1
+    return A, b
+
+
+def minvar_kkt(R):  # noqa: N803
+    """Solve the minimum variance portfolio via the KKT system with active-set method.
+
+    Iteratively drops assets with negative weights until all remaining weights
+    are non-negative, solving the KKT system exactly at each iteration via
+    ``numpy.linalg.solve``.
+
+    Args:
+        R: Return matrix of shape (T, N).
+
+    Returns:
+        Weight vector of shape (N,) summing to 1 with all non-negative entries.
+
+    Examples:
+        >>> import numpy as np
+        >>> from fast_minimum_variance.random import make_returns
+        >>> R = make_returns(100, 5, seed=0)
+        >>> w = minvar_kkt(R)
+        >>> w.shape
+        (5,)
+        >>> float(round(w.sum(), 10))
+        1.0
+        >>> bool((w >= 0).all())
+        True
+    """
+    n = R.shape[1]
+    active = np.ones(n, dtype=bool)
+    while True:
+        A, b = build_kkt(R[:, active])  # noqa: N806
+        sol = np.linalg.solve(A, b)
+        w_a = sol[: active.sum()]
+        if np.all(w_a >= -1e-10):
+            break
+        active[np.where(active)[0][w_a < 0]] = False
+    w = np.zeros(n)
+    w[active] = np.maximum(w_a, 0)
+    return w

fast_minimum_variance/krylov.py

@@ -0,0 +1,183 @@
+"""Krylov subspace solvers for the minimum variance portfolio."""
+
+import numpy as np
+from scipy.sparse.linalg import LinearOperator, cg, minres
+
+
+def minvar_minres(R, c=1.0, gamma=0.0):  # noqa: N803
+    """Solve the minimum variance portfolio via MINRES with active-set method.
+
+    Applies the active-set method, dropping assets with negative weights, and
+    solves the KKT saddle-point system at each iteration using MINRES. The KKT
+    matrix is applied as a LinearOperator — no explicit matrix is ever formed.
+    The matvec for x = [v; mu] is::
+
+        out[:n_a] = 2 (c R^T(Rv) + gamma v) + mu * 1
+        out[n_a]  = 1^T v
+
+    With the defaults ``c=1, gamma=0`` this solves the standard sample-covariance
+    problem. To apply dimension-based Ledoit-Wolf shrinkage without materialising
+    a stacked return matrix, compute::
+
+        T, N   = R.shape
+        frob_sq = (R * R).sum()
+        alpha  = N / (N + T)          # shrinkage intensity
+        c      = 1.0 - alpha          # = T / (N + T)
+        gamma  = frob_sq / (N + T)    # diagonal regularisation  (= alpha * frob_sq / N)
+
+    and call ``minvar_minres(R, c=c, gamma=gamma)``.
+
+    Args:
+        R: Return matrix of shape (T, N).
+        c: Scaling factor for R^T R (default 1.0).
+        gamma: Diagonal regularisation added to the (1,1) block (default 0.0).
+
+    Returns:
+        Tuple (w, n_iters) where w is the weight vector of shape (N,) summing
+        to 1 with all non-negative entries and n_iters is the total number of
+        MINRES iterations across all active-set steps.
+
+    Examples:
+        >>> import numpy as np
+        >>> from fast_minimum_variance.random import make_returns
+        >>> R = make_returns(100, 5, seed=0)
+        >>> w, iters = minvar_minres(R)
+        >>> w.shape
+        (5,)
+        >>> float(round(w.sum(), 6))
+        1.0
+        >>> bool((w >= 0).all())
+        True
+        >>> iters > 0
+        True
+    """
+    n = R.shape[1]
+    active = np.ones(n, dtype=bool)
+    total_iters = 0
+    while True:
+        r_a = R[:, active]
+        n_a = r_a.shape[1]
+
+        def _matvec(x, ra=r_a, na=n_a, cc=c, gam=gamma):
+            """Apply KKT operator [[2(c R^TR + gamma I), 1],[1^T, 0]] to x."""
+            out = np.empty(na + 1)
+            out[:na] = 2.0 * (cc * (ra.T @ (ra @ x[:na])) + gam * x[:na]) + x[na]
+            out[na] = x[:na].sum()
+            return out
+
+        b = np.zeros(n_a + 1)
+        b[n_a] = 1.0
+        kkt = LinearOperator(shape=(n_a + 1, n_a + 1), matvec=_matvec)  # type: ignore[call-arg]
+        iters = [0]
+        sol, _ = minres(kkt, b, callback=lambda _x: iters.__setitem__(0, iters[0] + 1))  # noqa: B023
+        total_iters += iters[0]
+        w_a = sol[:n_a]
+        if np.all(w_a >= -1e-10):
+            break
+        active[np.where(active)[0][w_a < 0]] = False
+    w = np.zeros(n)
+    w[active] = np.maximum(w_a, 0)
+    w /= w.sum()
+    return w, total_iters
+
+
+def minvar_cg(R, c=1.0, gamma=0.0):  # noqa: N803
+    """Solve the minimum variance portfolio via CG in the constraint-reduced space.
+
+    Projects the problem onto the constraint-satisfying subspace using an
+    implicit Householder reflector as the null-space basis of the budget
+    constraint, then applies CG to the reduced positive-definite system
+    ``P^T (c R^T R + gamma I) P``. An active-set loop drops assets with
+    negative weights until feasibility is reached.
+
+    The Householder vector ``v = [1+sqrt(n_a), 1, ..., 1]`` with
+    ``beta = 1/(n_a + sqrt(n_a))`` defines the reflector H = I - beta*v*v^T.
+    Its last n_a-1 columns span the null space of 1^T and form the implicit
+    basis P. Applying P or P^T costs O(n_a) instead of O(n_a^2) for the
+    explicit QR matrix, and no O(n_a^2) matrix is ever formed. Because P has
+    orthonormal columns, ``P^T (gamma I) P = gamma I``, so the gamma term
+    adds only a scalar shift to each matvec.
+
+    With the defaults ``c=1, gamma=0`` this solves the standard sample-covariance
+    problem. See ``minvar_minres`` for the Ledoit-Wolf shrinkage recipe.
+
+    Args:
+        R: Return matrix of shape (T, N).
+        c: Scaling factor for R^T R (default 1.0).
+        gamma: Diagonal regularisation added to the objective (default 0.0).
+
+    Returns:
+        Tuple (w, n_iters) where w is the weight vector of shape (N,) summing
+        to 1 with all non-negative entries and n_iters is the total number of
+        CG iterations across all active-set steps.
+
+    Examples:
+        >>> import numpy as np
+        >>> from fast_minimum_variance.random import make_returns
+        >>> R = make_returns(100, 5, seed=0)
+        >>> w, iters = minvar_cg(R)
+        >>> w.shape
+        (5,)
+        >>> float(round(w.sum(), 6))
+        1.0
+        >>> bool((w >= 0).all())
+        True
+        >>> iters > 0
+        True
+    """
+    n = R.shape[1]
+    active = np.ones(n, dtype=bool)
+    total_iters = 0
+    while True:
+        r_a = R[:, active]
+        n_a = r_a.shape[1]
+
+        if n_a == 1:
+            w_a = np.array([1.0])
+            break
+
+        # Implicit Householder basis for null(1^T): v = [1+sqrt(n_a), 1,...,1]
+        sqrt_na = np.sqrt(float(n_a))
+        beta = 1.0 / (n_a + sqrt_na)
+        v0 = 1.0 + sqrt_na
+
+        def _p_apply(y, b=beta, vv=v0, na=n_a):
+            """Apply implicit P (n_a x n_a-1) to y: O(n_a)."""
+            s = y.sum()
+            out = np.empty(na)
+            out[0] = -b * vv * s
+            out[1:] = y - (b * s)
+            return out
+
+        def _pt_apply(u, b=beta, vv=v0):
+            """Apply implicit P^T (n_a-1 x n_a) to u: O(n_a)."""
+            s = vv * u[0] + u[1:].sum()
+            return u[1:] - (b * s)
+
+        w0 = np.ones(n_a) / n_a
+        r0 = r_a @ w0
+
+        def _matvec(y, ra=r_a, b=beta, vv=v0, na=n_a, cc=c, gam=gamma):
+            """Apply P^T (c R^T R + gamma I) P to y via implicit Householder."""
+            s = y.sum()
+            pv = np.empty(na)
+            pv[0] = -b * vv * s
+            pv[1:] = y - (b * s)
+            rpv = cc * (ra.T @ (ra @ pv)) + gam * pv
+            sv = vv * rpv[0] + rpv[1:].sum()
+            return rpv[1:] - (b * sv)
+
+        g0 = c * (r_a.T @ r0) + gamma * w0
+        rhs = -_pt_apply(g0)
+        op = LinearOperator(shape=(n_a - 1, n_a - 1), matvec=_matvec)  # type: ignore[call-arg]
+        iters = [0]
+        sol, _ = cg(op, rhs, callback=lambda _x: iters.__setitem__(0, iters[0] + 1))  # noqa: B023
+        total_iters += iters[0]
+        w_a = w0 + _p_apply(sol)
+        if np.all(w_a >= -1e-10):
+            break
+        active[np.where(active)[0][w_a < 0]] = False
+    w = np.zeros(n)
+    w[active] = np.maximum(w_a, 0)
+    w /= w.sum()
+    return w, total_iters

fast_minimum_variance/random.py

@@ -0,0 +1,26 @@
+"""Return matrix generation utilities."""
+
+import numpy as np
+
+
+def make_returns(T, N, seed=42):  # noqa: N803
+    """Generate a T x N matrix of standard normal returns.
+
+    Args:
+        T: Number of time steps (rows).
+        N: Number of assets (columns).
+        seed: Random seed for reproducibility.
+
+    Returns:
+        Array of shape (T, N) with i.i.d. standard normal entries.
+
+    Examples:
+        >>> R = make_returns(100, 5, seed=0)
+        >>> R.shape
+        (100, 5)
+        >>> import numpy as np
+        >>> np.allclose(R.mean(axis=0), np.zeros(5), atol=0.3)
+        True
+    """
+    rng = np.random.default_rng(seed)
+    return rng.standard_normal((T, N))

fast_minimum_variance-0.2.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: fast-minimum-variance
+Version: 0.2.0
+Summary: Add your description here
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cvxpy>=1.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: scipy>=1.0
+Description-Content-Type: text/markdown
+
+# [fast-minimum-variance](https://jebel-quant.github.io/fast_minimum_variance): Solving Minimum Variance Portfolios Fast
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/fast-minimum-variance/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Jebel-Quant/fast_minimum_variance/blob/main/LICENSE)
+[![Rhiza](https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2FJebel-Quant%2Ffast_minimum_variance%2Fmain%2F.rhiza%2Ftemplate.yml&query=%24.ref&label=rhiza)](https://github.com/jebel-quant/rhiza)
+
+## Overview
+
+**fast-minimum-variance** is a Python library for computing long-only minimum variance
+portfolios without ever forming the sample covariance matrix. By operating directly on
+the returns matrix $R \in \mathbb{R}^{T \times N}$, it exposes a clean hierarchy of
+solvers — from an exact direct KKT solve to matrix-free Krylov methods — that scale
+gracefully as $N$ grows.
+
+The core insight is that minimising portfolio variance is equivalent to minimising
+$\|Rw\|^2$, which can be evaluated using two matrix-vector products $w \mapsto R^\top(Rw)$
+without constructing $R^\top R$ explicitly. This reframing connects the portfolio
+optimisation literature directly to Krylov subspace methods.
+
+The long-only constraint $w \geq 0$ is handled throughout via an **active-set method**:
+solve the unconstrained problem on the current active set, drop assets with negative
+weights, and repeat. The process terminates in at most $N$ iterations.
+
+## Solvers
+
+| Solver | Module | Method | Notes |
+|---|---|---|---|
+| `minvar_kkt` | `kkt` | Direct KKT via `numpy.linalg.solve` | Exact; baseline for accuracy comparisons |
+| `minvar_minres` | `krylov` | MINRES on the indefinite KKT system | Matrix-free capable; handles indefiniteness correctly |
+| `minvar_cg` | `krylov` | CG in the constraint-reduced space | Positive-definite reduced system; no indefinite solver needed |
+| `minvar_cvxpy` | `cvx` | General-purpose convex solver via CVXPY | Reference implementation; slowest but most flexible |
+
+All solvers return a weight vector $w \in \mathbb{R}^N$ satisfying $\sum_i w_i = 1$ and $w_i \geq 0$.
+
+## Quick Start
+
+```python
+from fast_minimum_variance.random import make_returns
+from fast_minimum_variance.kkt import minvar_kkt
+from fast_minimum_variance.krylov import minvar_cg, minvar_minres
+from fast_minimum_variance.cvx import minvar_cvxpy
+
+# Generate a synthetic return matrix: 500 daily returns, 20 assets
+R = make_returns(T=500, N=20, seed=42)
+
+# Solve with any of the available solvers
+w_kkt    = minvar_kkt(R)      # exact KKT solve
+w_minres = minvar_minres(R)   # MINRES on the indefinite KKT system
+w_cg     = minvar_cg(R)       # CG in the constraint-reduced space
+w_cvxpy  = minvar_cvxpy(R)    # CVXPY reference
+
+# All solutions satisfy the portfolio constraints
+assert abs(w_kkt.sum() - 1.0) < 1e-8
+assert (w_kkt >= 0).all()
+```
+
+## The KKT System
+
+The equality-constrained minimum variance problem yields the $(N+1) \times (N+1)$ KKT system:
+
+$$\begin{pmatrix} 2R^\top R & \mathbf{1} \cr \mathbf{1}^\top & 0 \end{pmatrix} \begin{pmatrix} w \cr \lambda \end{pmatrix} = \begin{pmatrix} \mathbf{0} \cr 1 \end{pmatrix}$$
+
+This system is **symmetric but indefinite** — the zero in the bottom-right corner of the
+KKT matrix introduces a negative eigenvalue. This rules out standard CG on the full system,
+but it opens the door to MINRES. Alternatively, the CG solver eliminates the constraint
+entirely by parameterising $w = w_0 + Pv$ where $P$ spans the null space of
+$\mathbf{1}^\top$, yielding a positive-definite reduced system of size $(N-1) \times (N-1)$.
+
+## Installation
+
+```bash
+pip install fast-minimum-variance
+```
+
+For development:
+
+```bash
+git clone https://github.com/Jebel-Quant/fast_minimum_variance
+cd fast_minimum_variance
+make install
+```
+
+## Requirements
+
+- Python 3.11+
+- numpy
+- scipy
+- cvxpy
+
+## Citing
+
+If you use this library in academic work or research, please cite:
+
+```bibtex
+@software{fast_minimum_variance,
+  author  = {Schmelzer, Thomas},
+  title   = {fast-minimum-variance: Solving Minimum Variance Portfolios Fast},
+  url     = {https://github.com/Jebel-Quant/fast_minimum_variance},
+  year    = {2026},
+  license = {MIT}
+}
+```
+
+## License
+
+MIT License — see [LICENSE](https://github.com/Jebel-Quant/fast_minimum_variance/blob/main/LICENSE) for details.

fast_minimum_variance-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+fast_minimum_variance/__init__.py,sha256=TFCNorOmpOBZIzu8rVZgpAH9LPlw-4YDsQeDsV50BsU,29
+fast_minimum_variance/cvx.py,sha256=bXtYiJaJtGHdhcsv3MAj-c9Vg5fknGXxPSbMcgkA5sw,957
+fast_minimum_variance/kkt.py,sha256=BYjr4HkpV3_b2jJ0j5oX1l5_3XN7vFw6BHadOqYAWo8,2139
+fast_minimum_variance/krylov.py,sha256=lxmWNnhLwcG_QTTv5zEJt5xTwJ0CHtLAJyghZjxM5Pw,6665
+fast_minimum_variance/random.py,sha256=76M-13ExNggETggw44CuQ43JTARpOkCA8u-03-LzME0,677
+fast_minimum_variance-0.2.0.dist-info/METADATA,sha256=DRqIAS7_Y046DODPpYAF6qUEQgiIgB6_YuQry51oGeM,4672
+fast_minimum_variance-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+fast_minimum_variance-0.2.0.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
+fast_minimum_variance-0.2.0.dist-info/RECORD,,

fast_minimum_variance-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fast_minimum_variance-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jebel Quant Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.