allocation 0.0.1__tar.gz

allocation-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Cotton
+
+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.

allocation-0.0.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: allocation
+Version: 0.0.1
+Summary: Online (streaming) portfolio construction: scikit-learn / skfolio-compatible estimators over a keyed dynamic universe
+Author-email: Peter Cotton <peter.cotton@microprediction.com>
+License: MIT
+Project-URL: Homepage, https://github.com/microprediction/allocation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: thurstone>=0.1.0
+Provides-Extra: scale
+Requires-Dist: scipy>=1.10; extra == "scale"
+Provides-Extra: skfolio
+Requires-Dist: skfolio>=0.5; extra == "skfolio"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: scipy>=1.10; extra == "test"
+Dynamic: license-file
+
+# allocation
+
+**Online (streaming) portfolio construction.** A home for portfolio methods as
+scikit-learn / [skfolio](https://skfolio.org)-compatible estimators
+(`fit` / `partial_fit` / `predict` / `weights_`), on top of a keyed
+dynamic-universe layer so they survive reconstituting universes.
+
+```python
+from allocation import ThurstonePortfolio
+
+est = ThurstonePortfolio(calib="market", phi=1.0)
+est.fit(returns)            # returns: (n_obs, n_assets)
+est.weights_                # long-only weights on the simplex
+
+for batch in stream:        # streaming / rebalancing
+    est.partial_fit(batch)  # transports a fixed seed ensemble -> low turnover
+    w = est.weights_
+```
+
+`score(X)` returns the portfolio's Sharpe ratio (skfolio's scoring convention),
+and `to_portfolio(X)` wraps the fitted weights as a skfolio `Portfolio`
+(`pip install allocation[skfolio]`) so the output drops into skfolio's metrics,
+`Population`, and cross-validation.
+
+## Why a separate package
+
+skfolio is the scikit-learn-native portfolio library, but it is *batch*: a
+changing universe is handled by NaN/incomplete-data mechanics, not by carrying
+per-asset state across streaming updates. `allocation` is the **online**
+complement — estimators with `partial_fit`, a keyed dynamic universe (in the
+spirit of [`precise`](https://github.com/microprediction/precise)), and turnover
+control by construction — while staying API-compatible so each estimator can also
+be contributed upstream to skfolio.
+
+## Methods
+
+| Estimator | Status | Notes |
+|-----------|--------|-------|
+| `ThurstonePortfolio` | working | Ability tilt: weights are winning probabilities of a correlated race; calibrate to a benchmark under a reference correlation, tilt under the estimate; smooth common-seed transport for `partial_fit`. Built on [`thurstone`](https://github.com/microprediction/thurstone). |
+| `SchurComplementary` | planned | Online version of the Schur-complementary construction (the batch version is in skfolio). |
+| baselines | planned | Online equal / cap / minimum-variance / risk-parity for benchmarking. |
+
+## Design
+
+```
+allocation/
+  base.py        # BaseOnlinePortfolio: fit / partial_fit / predict / weights_
+  moments.py     # EwmaCovariance (default); any partial_fit/covariance_ estimator plugs in
+  universe.py    # keyed dynamic-universe state (planned)
+  thurstone.py   # ThurstonePortfolio
+  _thurstone/    # calibration + transport engine
+```
+
+Covariance is pluggable: the default is a light EWMA, but any online estimator
+exposing `partial_fit` and `covariance_` (e.g. a `precise` skater) can be passed
+via `covariance=`.
+
+## Status
+
+Early. The Thurstone estimator and the streaming transport work and are tested;
+the keyed dynamic-universe layer and the Schur estimator are next. The theory
+behind the Thurstone method (feasibility, redundancy consistency, the implied
+regularized objective, smoothness/turnover) is written up in the accompanying
+paper.
+
+## License
+
+MIT © Peter Cotton

allocation-0.0.1/README.md

@@ -0,0 +1,68 @@
+# allocation
+
+**Online (streaming) portfolio construction.** A home for portfolio methods as
+scikit-learn / [skfolio](https://skfolio.org)-compatible estimators
+(`fit` / `partial_fit` / `predict` / `weights_`), on top of a keyed
+dynamic-universe layer so they survive reconstituting universes.
+
+```python
+from allocation import ThurstonePortfolio
+
+est = ThurstonePortfolio(calib="market", phi=1.0)
+est.fit(returns)            # returns: (n_obs, n_assets)
+est.weights_                # long-only weights on the simplex
+
+for batch in stream:        # streaming / rebalancing
+    est.partial_fit(batch)  # transports a fixed seed ensemble -> low turnover
+    w = est.weights_
+```
+
+`score(X)` returns the portfolio's Sharpe ratio (skfolio's scoring convention),
+and `to_portfolio(X)` wraps the fitted weights as a skfolio `Portfolio`
+(`pip install allocation[skfolio]`) so the output drops into skfolio's metrics,
+`Population`, and cross-validation.
+
+## Why a separate package
+
+skfolio is the scikit-learn-native portfolio library, but it is *batch*: a
+changing universe is handled by NaN/incomplete-data mechanics, not by carrying
+per-asset state across streaming updates. `allocation` is the **online**
+complement — estimators with `partial_fit`, a keyed dynamic universe (in the
+spirit of [`precise`](https://github.com/microprediction/precise)), and turnover
+control by construction — while staying API-compatible so each estimator can also
+be contributed upstream to skfolio.
+
+## Methods
+
+| Estimator | Status | Notes |
+|-----------|--------|-------|
+| `ThurstonePortfolio` | working | Ability tilt: weights are winning probabilities of a correlated race; calibrate to a benchmark under a reference correlation, tilt under the estimate; smooth common-seed transport for `partial_fit`. Built on [`thurstone`](https://github.com/microprediction/thurstone). |
+| `SchurComplementary` | planned | Online version of the Schur-complementary construction (the batch version is in skfolio). |
+| baselines | planned | Online equal / cap / minimum-variance / risk-parity for benchmarking. |
+
+## Design
+
+```
+allocation/
+  base.py        # BaseOnlinePortfolio: fit / partial_fit / predict / weights_
+  moments.py     # EwmaCovariance (default); any partial_fit/covariance_ estimator plugs in
+  universe.py    # keyed dynamic-universe state (planned)
+  thurstone.py   # ThurstonePortfolio
+  _thurstone/    # calibration + transport engine
+```
+
+Covariance is pluggable: the default is a light EWMA, but any online estimator
+exposing `partial_fit` and `covariance_` (e.g. a `precise` skater) can be passed
+via `covariance=`.
+
+## Status
+
+Early. The Thurstone estimator and the streaming transport work and are tested;
+the keyed dynamic-universe layer and the Schur estimator are next. The theory
+behind the Thurstone method (feasibility, redundancy consistency, the implied
+regularized objective, smoothness/turnover) is written up in the accompanying
+paper.
+
+## License
+
+MIT © Peter Cotton

allocation-0.0.1/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-0.0.1/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-0.0.1/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-0.0.1/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