allocation 0.0.1__py3-none-any.whl

allocation/__init__.py

@@ -0,0 +1,30 @@
+"""allocation -- online (streaming) portfolio construction.
+
+A home for online/streaming portfolio estimators that follow scikit-learn /
+skfolio conventions (``fit`` / ``partial_fit`` / ``weights_`` / ``predict``) on
+top of a keyed dynamic-universe layer, so they survive reconstituting universes.
+
+Estimators:
+    from allocation import ThurstonePortfolio
+    w = ThurstonePortfolio(calib="market", phi=1.0).fit(returns).weights_
+"""
+
+from .base import BaseOnlinePortfolio
+from .keyed import KeyedEwmaCovariance, StreamingSchur, StreamingThurstone
+from .moments import EwmaCovariance
+from .schur import SchurComplementary
+from .thurstone import ThurstonePortfolio
+
+__version__ = "0.0.1"
+
+__all__ = [
+    # batch / skfolio-style
+    "BaseOnlinePortfolio",
+    "ThurstonePortfolio",
+    "SchurComplementary",
+    "EwmaCovariance",
+    # streaming / river-style (changing universe)
+    "StreamingThurstone",
+    "StreamingSchur",
+    "KeyedEwmaCovariance",
+]

allocation/_schur/coupling.py

@@ -0,0 +1,199 @@
+"""Schur-complementary allocation: the gamma cross-block coupling + recursive bisection.
+
+Faithful port of the Schur Complementary algorithm (Peter Cotton, 2022; in skfolio
+as ``SchurComplementary``, BSD-3, derived from ``precise``). Given a seriation
+(asset order) and a covariance, recursive median bisection allocates between halves
+in inverse proportion to each half's variance -- but each half's covariance is first
+*augmented* by the Schur complement of the other half, scaled by ``gamma``:
+``gamma = 0`` ignores the cross-block (Hierarchical Risk Parity); ``gamma -> 1`` tends
+to the minimum-variance portfolio.
+
+Only the *order* comes from clustering; everything here is a continuous function of
+the covariance, so a smooth order (Fiedler seriation) yields smooth weights.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+__all__ = ["compute_weights", "compute_monotonic_weights", "schur_augmentation"]
+
+
+def _inverse_multiply(a: np.ndarray, b: np.ndarray) -> np.ndarray:
+    """a^-1 @ b via a solve (more accurate than forming the inverse)."""
+    return np.linalg.solve(a, b)
+
+
+def _multiply_by_inverse(a: np.ndarray, b: np.ndarray) -> np.ndarray:
+    """a @ b^-1."""
+    return np.linalg.solve(b.T, a.T).T
+
+
+def _symmetrize(m: np.ndarray) -> np.ndarray:
+    return 0.5 * (m + m.T)
+
+
+def _is_spd(a: np.ndarray) -> bool:
+    try:
+        np.linalg.cholesky(a)
+        return True
+    except np.linalg.LinAlgError:
+        return False
+
+
+def _nearest_spd(a: np.ndarray) -> np.ndarray:
+    a = _symmetrize(a)
+    vals, vecs = np.linalg.eigh(a)
+    vals = np.clip(vals, 1e-10, None)
+    return _symmetrize((vecs * vals) @ vecs.T)
+
+
+def _symmetric_step_up_matrix(n1: int, n2: int) -> np.ndarray:
+    """M with ``M @ ones(n2) == ones(n1)`` (|n1 - n2| <= 1)."""
+    if n1 == n2:
+        return np.eye(n1)
+    if n1 < n2:
+        return _symmetric_step_up_matrix(n2, n1).T * n1 / n2
+    m = np.zeros((n1, n2))
+    j_row = np.ones((1, n2)) / n2
+    e = np.eye(n2)
+    for j in range(n1):
+        mj = np.concatenate([e[:j], j_row, e[j:]], axis=0)
+        m += mj / n1
+    return m
+
+
+def schur_augmentation(a: np.ndarray, b: np.ndarray, d: np.ndarray, gamma: float) -> np.ndarray:
+    """Augment block ``a`` with the gamma-scaled Schur complement of ``d``."""
+    n_a, n_d = a.shape[0], d.shape[0]
+    if gamma == 0 or n_a == 1 or n_d == 1:
+        return a
+    a_aug = a - gamma * b @ _inverse_multiply(d, b.T)
+    m = _symmetric_step_up_matrix(n1=n_a, n2=n_d)
+    r = np.eye(n_a) - gamma * _multiply_by_inverse(b, d) @ m.T
+    return _symmetrize(_inverse_multiply(r, a_aug))
+
+
+def _bisection(items):
+    for e in items:
+        n = len(e)
+        if n > 1:
+            mid = n // 2
+            yield e[:mid], e[mid:]
+
+
+def _naive_portfolio_variance(cov: np.ndarray) -> float:
+    w = 1.0 / np.diag(cov)
+    w = w / w.sum()
+    return float(w @ cov @ w.T)
+
+
+def compute_weights(
+    order: np.ndarray, covariance: np.ndarray, gamma: float, force_spd: bool = True
+) -> np.ndarray:
+    """Schur-complementary weights for a given seriation ``order`` and covariance.
+
+    Weights are returned in the original asset order (not the seriation order),
+    are long-only, and sum to one.
+    """
+    cov = np.array(covariance, dtype=float, copy=True)
+    n = len(cov)
+    weights = np.ones(n)
+    items = [np.asarray(order, dtype=int)]
+    while items:
+        new_items = []
+        for left, right in _bisection(items):
+            new_items += [left, right]
+            a = cov[np.ix_(left, left)]
+            d = cov[np.ix_(right, right)]
+            if len(left) <= 1 or len(right) <= 1:
+                a_aug, d_aug = a, d
+            else:
+                b = cov[np.ix_(left, right)]
+                a_aug = schur_augmentation(a, b, d, gamma=gamma)
+                d_aug = schur_augmentation(d, b.T, a, gamma=gamma)
+                if force_spd:
+                    if not _is_spd(a_aug):
+                        a_aug = _nearest_spd(a_aug)
+                    if not _is_spd(d_aug):
+                        d_aug = _nearest_spd(d_aug)
+                elif not _is_spd(a_aug) or not _is_spd(d_aug):
+                    return None  # signal infeasible gamma to the monotonic sweep
+                cov[np.ix_(left, left)] = a_aug
+                cov[np.ix_(right, right)] = d_aug
+            lv = _naive_portfolio_variance(a_aug)
+            rv = _naive_portfolio_variance(d_aug)
+            alpha = 1.0 - lv / (lv + rv)
+            weights[left] *= alpha
+            weights[right] *= 1.0 - alpha
+        items = new_items
+    s = weights.sum()
+    return weights / s if s > 0 else np.full(n, 1.0 / n)
+
+
+def _binary_search(objective, low_gamma, high_gamma, low_variance, tol=1e-4):
+    """Locate the gamma turning point where portfolio variance stops decreasing."""
+    max_iter = math.ceil(math.log2(max(high_gamma - low_gamma, tol) / tol) * 2 + 1)
+    is_decreasing = False
+    best = None
+    for _ in range(max_iter):
+        mid = 0.5 * (low_gamma + high_gamma)
+        variance, weights = objective(mid)
+        variance_h = objective(mid - tol)[0]
+        if variance <= low_variance and variance <= variance_h:
+            is_decreasing = True
+            low_gamma, low_variance, best = mid, variance, weights
+        else:
+            high_gamma = mid
+        if is_decreasing and best is not None and (high_gamma - low_gamma) <= tol:
+            return best, low_gamma
+    raise RuntimeError("no permissible gamma with monotonically decreasing variance")
+
+
+def compute_monotonic_weights(
+    order: np.ndarray,
+    covariance: np.ndarray,
+    max_gamma: float,
+    step: float = 0.1,
+    tol: float = 1e-4,
+) -> tuple[np.ndarray, float]:
+    """Weights at the largest gamma (<= ``max_gamma``) for which variance still falls.
+
+    Caps gamma at the turning point ``effective_gamma`` so that
+    ``variance(Schur) <= variance(HRP)`` even for ill-conditioned covariances
+    (skfolio's ``keep_monotonic=True`` behaviour). Returns ``(weights, effective_gamma)``.
+    """
+    if max_gamma == 0:
+        return compute_weights(order, covariance, 0.0, force_spd=True), 0.0
+    cov = np.asarray(covariance, dtype=float)
+
+    def objective(x):
+        w = compute_weights(order, cov, x, force_spd=False)
+        risk = np.inf if w is None else float(w @ cov @ w.T)
+        return risk, w
+
+    n = int(np.ceil(max_gamma / step)) + 1
+    gammas = np.linspace(0.0, max_gamma, n)
+    variances = np.full(n, np.nan)
+    variance, weights_0 = objective(gammas[0])
+    variances[0] = variance
+    weights = weights_0
+    for i in range(1, n):
+        variance, weights = objective(gammas[i])
+        variances[i] = variance
+        if variance >= variances[i - 1]:
+            lo = gammas[0] if i == 1 else gammas[i - 2]
+            lo_var = variances[0] if i == 1 else variances[i - 2]
+            try:
+                return _binary_search(objective, lo, gammas[i], lo_var, tol)
+            except RuntimeError:
+                return weights_0, 0.0
+    # monotonically decreasing up to max_gamma
+    if variance <= objective(max_gamma - tol)[0]:
+        return weights, max_gamma
+    try:
+        return _binary_search(objective, gammas[-2], max_gamma, variances[-2], tol)
+    except RuntimeError:
+        return weights, max_gamma

allocation/_schur/seriation.py

@@ -0,0 +1,127 @@
+"""Fiedler (spectral) seriation -- a smooth ordering of assets.
+
+Standard HRP/Schur take the asset order from agglomerative clustering, whose
+dendrogram reorders discontinuously as the covariance drifts -- the source of
+turnover. We replace it with the Fiedler vector (the eigenvector of the second
+smallest Laplacian eigenvalue of the similarity graph): it varies *continuously*
+with the covariance, so the order changes only when two assets' Fiedler
+coordinates cross. Feeding this order into the Schur recursion makes the whole
+allocation a smooth function of the covariance.
+
+Scale: the similarity graph can be sparsified to k nearest neighbours so the
+Fiedler vector is a single eigenpair of a sparse Laplacian (the dense ``eigh``
+here is fine to a few thousand assets; an iterative, warm-started solver is the
+drop-in for larger universes). The graph is a blend of realized correlation and
+an optional prior (sectors / fundamentals / an LLM similarity) -- the seam that
+lets a prior place cold-start names the realized correlation cannot.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .._thurstone.covariance import cov_to_corr
+
+__all__ = ["affinity", "fiedler_vector", "seriate"]
+
+
+def affinity(
+    cov: np.ndarray,
+    knn: int | None = None,
+    prior: np.ndarray | None = None,
+    prior_weight: float = 0.0,
+) -> np.ndarray:
+    """Similarity (affinity) graph in [0, 1], optionally kNN-sparsified.
+
+    Realized similarity is ``(corr + 1) / 2``; blended with an optional ``prior``
+    similarity by ``prior_weight``. With ``knn`` set, each row keeps only its k
+    largest off-diagonal affinities (symmetrized).
+    """
+    A = 0.5 * (cov_to_corr(cov) + 1.0)
+    if prior is not None and prior_weight > 0.0:
+        A = (1.0 - prior_weight) * A + prior_weight * np.asarray(prior, dtype=float)
+    np.fill_diagonal(A, 0.0)
+    if knn is not None and knn < A.shape[0] - 1:
+        n = A.shape[0]
+        mask = np.zeros_like(A, dtype=bool)
+        keep = np.argsort(-A, axis=1)[:, :knn]
+        rows = np.repeat(np.arange(n), knn)
+        mask[rows, keep.ravel()] = True
+        mask |= mask.T  # symmetric kNN graph
+        A = np.where(mask, A, 0.0)
+    return A
+
+
+def _fiedler_dense(A: np.ndarray) -> np.ndarray:
+    L = np.diag(A.sum(axis=1)) - A
+    _, vecs = np.linalg.eigh(L)
+    return vecs[:, 1]  # 2nd-smallest eigenvalue -> Fiedler vector
+
+
+def _fiedler_sparse(A: np.ndarray, previous: np.ndarray | None) -> np.ndarray:
+    """Fiedler vector via LOBPCG on a sparse Laplacian (only one eigenpair).
+
+    We deflate the constant null vector (`Y = 1`, the eigenvalue-0 eigenvector of a
+    connected Laplacian) and ask for the smallest remaining eigenpair -- the
+    Fiedler vector. Warm-started from ``previous``. This is what scales: an
+    `O(nnz)` matvec on a kNN-sparsified graph rather than a dense `O(n^3)` eigh.
+    """
+    import scipy.sparse as sp
+    import scipy.sparse.linalg as spla
+
+    n = A.shape[0]
+    Asp = sp.csr_matrix(A)
+    deg = np.asarray(Asp.sum(axis=1)).ravel()
+    L = sp.diags(deg) - Asp
+    if previous is not None and len(previous) == n:
+        X = previous.reshape(n, 1).copy()
+    else:
+        rng = np.random.default_rng(0)
+        X = rng.standard_normal((n, 1))
+    Y = np.ones((n, 1))  # deflate the constant (lambda=0) eigenvector
+    _, vecs = spla.lobpcg(L, X, Y=Y, largest=False, maxiter=200, tol=1e-7)
+    return np.asarray(vecs)[:, 0]
+
+
+def fiedler_vector(
+    A: np.ndarray, previous: np.ndarray | None = None, sparse: bool = False
+) -> np.ndarray:
+    """Fiedler vector of the graph Laplacian ``L = D - A``.
+
+    With ``sparse=True`` an iterative single-eigenpair LOBPCG solve is used
+    (scales to large kNN graphs); otherwise a dense ``eigh``. The sign is fixed by
+    alignment with ``previous`` -- the Fiedler vector is defined up to sign, and
+    without this the order would flip arbitrarily between streaming updates.
+    """
+    if sparse and A.shape[0] > 3:
+        try:
+            v = _fiedler_sparse(A, previous)
+        except Exception:
+            v = _fiedler_dense(A)
+    else:
+        v = _fiedler_dense(A)
+    if previous is not None and len(previous) == len(v) and float(v @ previous) < 0.0:
+        v = -v
+    return v
+
+
+def seriate(
+    cov: np.ndarray,
+    previous: np.ndarray | None = None,
+    knn: int | None = None,
+    prior: np.ndarray | None = None,
+    prior_weight: float = 0.0,
+    sparse: bool | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Return ``(order, fiedler)``: the seriation order and its Fiedler vector.
+
+    ``previous`` is last period's Fiedler vector, used to keep the sign (and hence
+    the order) stable across streaming updates. ``sparse`` selects the iterative
+    LOBPCG solver; if ``None`` it defaults to sparse whenever ``knn`` is set.
+    """
+    A = affinity(cov, knn=knn, prior=prior, prior_weight=prior_weight)
+    if sparse is None:
+        sparse = knn is not None
+    v = fiedler_vector(A, previous=previous, sparse=sparse)
+    order = np.argsort(v)
+    return order, v

allocation/_thurstone/ability.py

@@ -0,0 +1,45 @@
+"""Bridge to the :mod:`thurstone` calibration maps.
+
+These thin wrappers turn portfolio weights (treated as state prices / winning
+probabilities) into latent Thurstone abilities and back, using the lattice
+machinery in the ``thurstone`` package. Smaller ability == stronger competitor,
+because the winner is the *minimum* performance.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from thurstone import AbilityCalibrator, Density, UniformLattice
+from thurstone.conventions import STD_L, STD_SCALE, STD_UNIT
+
+__all__ = [
+    "base_density",
+    "state_price_implied_ability",
+    "ability_implied_state_prices",
+]
+
+
+def base_density(L: int = STD_L, unit: float = STD_UNIT, scale: float = STD_SCALE) -> Density:
+    """Standard symmetric performance density on the default lattice."""
+    lat = UniformLattice(L, unit)
+    return Density.skew_normal(lat, loc=0.0, scale=scale, a=0.0)
+
+
+def state_price_implied_ability(
+    weights, *, base: Density | None = None, n_iter: int = 4
+) -> np.ndarray:
+    """Invert weights (as winning probabilities) to abilities, up to a constant."""
+    base = base if base is not None else base_density()
+    cal = AbilityCalibrator(base=base, n_iter=n_iter)
+    a = cal.solve_from_prices([float(w) for w in weights])
+    return np.asarray(a, dtype=float)
+
+
+def ability_implied_state_prices(ability, *, base: Density | None = None) -> np.ndarray:
+    """Forward map: abilities to winning probabilities (the field's state prices)."""
+    base = base if base is not None else base_density()
+    cal = AbilityCalibrator(base=base)
+    p = cal.state_prices_from_ability([float(a) for a in ability])
+    p = np.asarray(p, dtype=float)
+    s = p.sum()
+    return p / s if s > 0 else p

allocation/_thurstone/calibrate.py

@@ -0,0 +1,105 @@
+"""Calibration: back out Thurstone abilities that reproduce target weights.
+
+Two engines, selected by the structure of the reference correlation ``C_calib``:
+
+* **diagonal** (independent field) -- the exact lattice inverse from
+  :mod:`thurstone`. Cheap; this is flavour (i).
+* **one-factor** -- a single common factor with per-asset loadings ``betas``.
+  Conditional on the factor the assets are independent, so the race is evaluated
+  by Gauss--Hermite quadrature over the factor (``winprobs_one_factor``); the
+  inverse is a damped fixed-point on that forward map. This is flavour (ii), and
+  the quadrature is exactly the calibration tool.
+
+Convention throughout: the *minimum* performance wins, so a **smaller** ability
+means a **stronger** competitor (higher winning probability).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from thurstone import Density, Race
+
+from .ability import base_density, state_price_implied_ability
+
+__all__ = [
+    "winprobs_one_factor",
+    "calibrate_diagonal",
+    "calibrate_one_factor",
+]
+
+
+def _normalize(w: np.ndarray) -> np.ndarray:
+    w = np.asarray(w, dtype=float)
+    s = w.sum()
+    return w / s if s > 0 else np.full(len(w), 1.0 / len(w))
+
+
+def winprobs_one_factor(
+    ability, betas, *, base: Density | None = None, n_quad: int = 16
+) -> np.ndarray:
+    """Winning probabilities under a one-factor race, by quadrature.
+
+    Model: ``X_i = a_i + b_i Z + sqrt(1 - b_i^2) eps_i`` with ``Z ~ N(0,1)`` the
+    common factor and ``eps_i`` independent. Conditional on ``Z = z`` the field
+    is independent, so the exact lattice race applies; we integrate over ``z``
+    with Gauss--Hermite (probabilists') quadrature.
+    """
+    base = base if base is not None else base_density()
+    lat = base.lattice
+    a = np.asarray(ability, dtype=float)
+    b = np.clip(np.asarray(betas, dtype=float), -0.999, 0.999)
+    s = np.sqrt(np.clip(1.0 - b ** 2, 1e-6, 1.0))
+
+    nodes, qw = np.polynomial.hermite_e.hermegauss(n_quad)
+    qw = qw / np.sqrt(2.0 * np.pi)  # so weights sum to 1
+
+    n = len(a)
+    acc = np.zeros(n, dtype=float)
+    for z, w in zip(nodes, qw):
+        densities = [
+            Density.skew_normal(lat, loc=float(a[i] + b[i] * z), scale=float(s[i]), a=0.0)
+            for i in range(n)
+        ]
+        acc += w * np.asarray(Race(densities).state_prices(), dtype=float)
+    return _normalize(np.clip(acc, 0.0, None))
+
+
+def calibrate_diagonal(target, *, base: Density | None = None, n_iter: int = 4) -> np.ndarray:
+    """Abilities reproducing ``target`` under an independent field (flavour i).
+
+    Exact lattice inverse via the :mod:`thurstone` calibrator.
+    """
+    return state_price_implied_ability(_normalize(target), base=base, n_iter=n_iter)
+
+
+def calibrate_one_factor(
+    target,
+    betas,
+    *,
+    base: Density | None = None,
+    n_quad: int = 16,
+    n_iter: int = 60,
+    step: float = 0.5,
+    tol: float = 1e-4,
+) -> np.ndarray:
+    """Abilities reproducing ``target`` under a one-factor race (flavour ii).
+
+    Damped fixed-point on the quadrature forward map. Because winning
+    probability is monotone *decreasing* in ability (min wins), we nudge
+    ``a_i`` up when the model over-prices asset ``i`` and down when it
+    under-prices it, on a log scale, re-centering each step (abilities are only
+    identified up to a constant).
+    """
+    target = _normalize(target)
+    base = base if base is not None else base_density()
+    log_t = np.log(np.clip(target, 1e-12, None))
+
+    a = calibrate_diagonal(target, base=base)  # warm start (independent inverse)
+    for _ in range(n_iter):
+        p = winprobs_one_factor(a, betas, base=base, n_quad=n_quad)
+        if np.max(np.abs(p - target)) < tol:
+            break
+        log_p = np.log(np.clip(p, 1e-12, None))
+        a = a + step * (log_p - log_t)  # p decreasing in a -> this is a descent step
+        a = a - np.median(a)
+    return a

allocation/_thurstone/covariance.py

@@ -0,0 +1,91 @@
+"""Covariance / correlation utilities for the ability tilt.
+
+Nothing here knows about Thurstone; these are the matrix-hygiene helpers the
+calibration and tilt steps need: turn a covariance estimate into a valid
+correlation matrix, scale correlation, extract one-factor (market) loadings, and
+reconstruct the implied one-factor correlation.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "cov_to_corr",
+    "scale_off_diagonal",
+    "nearest_correlation",
+    "market_betas",
+    "one_factor_corr",
+]
+
+
+def cov_to_corr(cov: np.ndarray) -> np.ndarray:
+    """Correlation matrix from a covariance matrix."""
+    cov = np.asarray(cov, dtype=float)
+    d = np.sqrt(np.clip(np.diag(cov), 1e-300, None))
+    corr = cov / np.outer(d, d)
+    np.fill_diagonal(corr, 1.0)
+    return np.clip(corr, -1.0, 1.0)
+
+
+def scale_off_diagonal(corr: np.ndarray, phi: float) -> np.ndarray:
+    """Scale every off-diagonal correlation by ``phi`` (0 -> identity)."""
+    c = np.array(corr, dtype=float, copy=True)
+    off = ~np.eye(c.shape[0], dtype=bool)
+    c[off] *= phi
+    return c
+
+
+def nearest_correlation(corr: np.ndarray, eps: float = 1e-8) -> np.ndarray:
+    """Project a symmetric matrix to the nearest valid correlation matrix.
+
+    Eigenvalue clipping plus diagonal renormalisation: guarantees
+    positive-definiteness and unit diagonal without requiring the input to be
+    well-conditioned. Used before sampling.
+    """
+    c = np.asarray(corr, dtype=float)
+    c = 0.5 * (c + c.T)
+    vals, vecs = np.linalg.eigh(c)
+    vals = np.clip(vals, eps, None)
+    c2 = (vecs * vals) @ vecs.T
+    d = np.sqrt(np.clip(np.diag(c2), 1e-300, None))
+    c2 = c2 / np.outer(d, d)
+    np.fill_diagonal(c2, 1.0)
+    return np.clip(c2, -1.0, 1.0)
+
+
+def market_betas(
+    cov: np.ndarray, weights: np.ndarray | None = None, b_max: float = 0.99
+) -> np.ndarray:
+    """One-factor loadings: each asset's correlation with the market portfolio.
+
+    The "market" is the ``weights``-weighted portfolio of the assets (the index
+    we calibrate to, by default). The loading ``b_i = corr(asset_i, market)`` is
+    the natural single-factor coefficient: under ``X_i = a_i + b_i Z + ...`` the
+    common factor ``Z`` is the (standardised) market. Returns values in
+    ``[-b_max, b_max]``.
+    """
+    cov = np.asarray(cov, dtype=float)
+    n = cov.shape[0]
+    w = np.full(n, 1.0 / n) if weights is None else np.asarray(weights, dtype=float)
+    w = w / w.sum()
+    sig = np.sqrt(np.clip(np.diag(cov), 1e-300, None))
+    cov_im = cov @ w  # covariance of each asset with the market portfolio
+    var_m = float(w @ cov @ w)
+    sig_m = np.sqrt(max(var_m, 1e-300))
+    b = cov_im / (sig * sig_m)
+    return np.clip(b, -b_max, b_max)
+
+
+def one_factor_corr(betas: np.ndarray) -> np.ndarray:
+    """Correlation implied by a single common factor with the given loadings.
+
+    ``C_ij = b_i b_j`` off-diagonal, ``1`` on the diagonal. This is the reference
+    correlation ``C_calib`` used by the one-factor calibration; the tilt then
+    re-races under the *actual* correlation, so the deviation from the target is
+    driven by how far the real correlation departs from this one-factor model.
+    """
+    b = np.asarray(betas, dtype=float)
+    c = np.outer(b, b)
+    np.fill_diagonal(c, 1.0)
+    return np.clip(c, -1.0, 1.0)

allocation/_thurstone/diagonal.py

@@ -0,0 +1,26 @@
+"""The baseline (variance-only) portfolio the ability tilt starts from."""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["diagonal_portfolio"]
+
+
+def diagonal_portfolio(cov: np.ndarray) -> np.ndarray:
+    """Long-only inverse-variance weights.
+
+    This is the minimum-variance portfolio when correlations are ignored: each
+    asset is weighted by the reciprocal of its variance, normalised to sum to
+    one. It is the starting point the tilt then ``polishes`` by reintroducing
+    correlation through a Thurstonian race.
+    """
+    cov = np.asarray(cov, dtype=float)
+    var = np.diag(cov).astype(float)
+    inv = np.where(var > 0, 1.0 / np.where(var > 0, var, 1.0), 0.0)
+    total = inv.sum()
+    if total <= 0:
+        # Degenerate covariance: fall back to equal weight.
+        n = cov.shape[0]
+        return np.full(n, 1.0 / n)
+    return inv / total

allocation/_thurstone/transport.py

@@ -0,0 +1,53 @@
+"""Common-seed transport: realize the correlated race with fixed seeds.
+
+The portfolio weights are the win frequencies of ``N(ability, C_tilt)``. We
+evaluate them by Monte Carlo with a *fixed* ensemble of standard-normal seeds and
+the symmetric square root of the correlation, so that as the correlation drifts
+the weights move smoothly (low turnover): see the smoothness theorem in the
+accompanying paper.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .covariance import cov_to_corr, nearest_correlation
+
+__all__ = ["symmetric_sqrt", "blend_correlation", "transport_weights"]
+
+
+def symmetric_sqrt(C: np.ndarray) -> np.ndarray:
+    """Symmetric (PCA) square root of a correlation matrix.
+
+    Smoother in ``C`` than a Cholesky factor (continuous except at eigenvalue
+    crossings), which is what keeps the recoloured paths -- and hence the
+    weights -- smooth as ``C`` drifts.
+    """
+    vals, vecs = np.linalg.eigh(C)
+    return (vecs * np.sqrt(np.clip(vals, 1e-12, None))) @ vecs.T
+
+
+def blend_correlation(C_calib: np.ndarray, cov: np.ndarray, phi: float) -> np.ndarray:
+    """Tilt correlation ``C_tilt = nearest_corr((1-phi) C_calib + phi corr(cov))``.
+
+    ``phi = 0`` recovers the reference (and so reproduces the target); ``phi = 1``
+    uses the full estimated correlation.
+    """
+    Ct = (1.0 - phi) * np.asarray(C_calib, dtype=float) + phi * cov_to_corr(cov)
+    return nearest_correlation(Ct)
+
+
+def transport_weights(ability: np.ndarray, C_tilt: np.ndarray, seeds: np.ndarray) -> np.ndarray:
+    """Win frequencies of ``N(ability, C_tilt)`` using the fixed ``seeds``.
+
+    ``seeds`` has shape ``(M, n)``; the same seeds across calls is what makes the
+    weights move smoothly with ``C_tilt`` (turnover tracks correlation change,
+    not sampling noise). The minimum performance wins.
+    """
+    a = np.asarray(ability, dtype=float)
+    S = symmetric_sqrt(C_tilt)
+    X = a + seeds @ S  # rows ~ N(a, C_tilt)
+    winners = np.argmin(X, axis=1)
+    counts = np.bincount(winners, minlength=len(a)).astype(float)
+    total = counts.sum()
+    return counts / total if total > 0 else np.full(len(a), 1.0 / len(a))