walkforward 3.4.0__py3-none-win_amd64.whl

walkforward/__init__.py

@@ -0,0 +1,86 @@
+"""Volatility forecasts, position sizing and purged walk-forward splits.
+
+A thin, checked layer over the mlrisk C library. The organising idea is that
+nothing at index ``t`` may see period ``t``:
+
+* :func:`ewma_vol` and the GARCH filters are predictive. The value at ``t`` is
+  built from observations before ``t``, so a position sized from it can be
+  scored against ``returns[t]``.
+* :func:`rolling_mean`, :func:`rolling_std`, :func:`parkinson_vol` and
+  :func:`garman_klass_vol` are contemporaneous by construction, and say so.
+  Pass them through :func:`lag` before sizing.
+* :class:`PurgedWalkForward` keeps training labels out of the test window,
+  which ordinary time-series splitting does not.
+
+A worked loop::
+
+    import numpy as np
+    import walkforward as wf
+
+    train = returns[:1000] - returns[:1000].mean()   # training mean only
+    model = wf.garch_fit(train)
+
+    sigma = model.filter_from(returns[1000:])        # continues the fit state
+    position = wf.vol_target_position(
+        sigma, target_vol=0.01, equity=100_000.0,
+        price=close[999:-1], max_leverage=2.0,       # entry price is the prior close
+    )
+    pnl = position * close[999:-1] * returns[1000:]
+
+This is research tooling, not investment advice, and not a backtester: it
+knows nothing about costs, borrow, calendars or corporate actions.
+"""
+
+from __future__ import annotations
+
+from ._core import DomainError, c_version
+from .linear import Ridge
+from .rolling import lag, rolling_mean, rolling_std
+from .sizing import drawdown_scale, kelly_fraction, vol_target_position
+from .split import PurgedWalkForward, WalkForwardSplit, walk_forward_splits
+from .volatility import (
+    GARCH_MAX_PERSISTENCE,
+    GARCH_MIN_SAMPLE,
+    GarchModel,
+    ewma_vol,
+    garch_fit,
+    garman_klass_vol,
+    parkinson_vol,
+)
+
+__all__ = [
+    "DomainError",
+    "GARCH_MAX_PERSISTENCE",
+    "GARCH_MIN_SAMPLE",
+    "GarchModel",
+    "PurgedWalkForward",
+    "Ridge",
+    "WalkForwardSplit",
+    "__version__",
+    "c_version",
+    "drawdown_scale",
+    "ewma_vol",
+    "garch_fit",
+    "garman_klass_vol",
+    "kelly_fraction",
+    "lag",
+    "parkinson_vol",
+    "rolling_mean",
+    "rolling_std",
+    "vol_target_position",
+    "walk_forward_splits",
+]
+
+
+def _version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("walkforward")
+    except Exception:  # pragma: no cover - source checkouts without metadata
+        return c_version()
+
+
+#: Version of the installed package. :func:`c_version` reports the version the
+#: loaded shared library was built from; the two agree in a correct install.
+__version__: str = _version()

walkforward/_core.py

@@ -0,0 +1,255 @@
+"""ctypes binding to the mlrisk C library.
+
+Everything public in this package goes through here. Two rules keep the C
+contracts unbreakable from Python:
+
+* Output buffers are always allocated on this side and never taken from the
+  caller, so the ``restrict`` non-aliasing contract on every C output
+  parameter cannot be violated by a numpy view.
+* Inputs are converted to C-contiguous float64 before the pointer is taken,
+  so a strided view, a Python list or a pandas Series is never read as if it
+  were a packed array.
+
+Per-call overhead is a few microseconds against work that is linear in the
+input, so ctypes costs nothing measurable here.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import pathlib
+from typing import Any
+
+import numpy as np
+
+try:  # pandas is optional; it is only used to hand a Series back a Series
+    import pandas as _pd
+except ImportError:  # pragma: no cover - exercised by environments without pandas
+    _pd = None
+
+__all__ = [
+    "DomainError",
+    "Garch",
+    "LinModel",
+    "Split",
+    "c_version",
+    "check",
+    "lib",
+]
+
+# --------------------------------------------------------------------------
+# Exceptions
+# --------------------------------------------------------------------------
+
+
+class DomainError(ValueError):
+    """The arguments were well formed but the computation has no answer.
+
+    Raised for a singular design matrix, a sample with zero or unrepresentable
+    variance, and recursions that overflow. Mirrors ``MLR_EDOMAIN``.
+    """
+
+
+_OK, _EINVAL, _ENOMEM, _EBOUNDS, _EDOMAIN = range(5)
+
+_MESSAGES = {
+    _EINVAL: "invalid argument",
+    _ENOMEM: "allocation failed",
+    _EBOUNDS: "output capacity too small",
+    _EDOMAIN: "domain error",
+}
+
+
+def check(status: int, what: str, detail: str = "") -> None:
+    """Turn an ``mlr_status`` into the matching Python exception."""
+    if status == _OK:
+        return
+    message = f"{what}: {_MESSAGES.get(status, f'unknown status {status}')}"
+    if detail:
+        message = f"{message} ({detail})"
+    if status == _ENOMEM:
+        raise MemoryError(message)
+    if status == _EDOMAIN:
+        raise DomainError(message)
+    if status == _EINVAL:
+        raise ValueError(message)
+    raise RuntimeError(message)  # EBOUNDS never escapes: we size every buffer
+
+
+# --------------------------------------------------------------------------
+# Structures, mirroring include/mlrisk/*.h field for field
+# --------------------------------------------------------------------------
+
+
+class Garch(ctypes.Structure):
+    _fields_ = [
+        ("omega", ctypes.c_double),
+        ("alpha", ctypes.c_double),
+        ("beta", ctypes.c_double),
+        ("sigma2_next", ctypes.c_double),
+        ("loglik", ctypes.c_double),
+        ("converged", ctypes.c_int),
+        ("backcast", ctypes.c_double),
+    ]
+
+
+class Split(ctypes.Structure):
+    _fields_ = [
+        ("train_start", ctypes.c_size_t),
+        ("train_end", ctypes.c_size_t),
+        ("test_start", ctypes.c_size_t),
+        ("test_end", ctypes.c_size_t),
+        ("train_post_start", ctypes.c_size_t),
+        ("train_post_end", ctypes.c_size_t),
+    ]
+
+
+class LinModel(ctypes.Structure):
+    _fields_ = [
+        ("d", ctypes.c_size_t),
+        ("w", ctypes.POINTER(ctypes.c_double)),
+        ("b", ctypes.c_double),
+        ("ridge", ctypes.c_double),
+        ("fitted", ctypes.c_int),
+    ]
+
+
+_D = ctypes.POINTER(ctypes.c_double)
+_SIZE = ctypes.c_size_t
+
+_SIGNATURES: dict[str, tuple[list[Any], Any]] = {
+    # rolling.h
+    "mlr_rolling_mean": ([_D, _SIZE, _SIZE, _D], ctypes.c_int),
+    "mlr_rolling_std": ([_D, _SIZE, _SIZE, _D], ctypes.c_int),
+    "mlr_ewma_vol": ([_D, _SIZE, ctypes.c_double, _D], ctypes.c_int),
+    # vol.h
+    "mlr_garch_fit": ([_D, _SIZE, ctypes.POINTER(Garch)], ctypes.c_int),
+    "mlr_garch_filter": ([ctypes.POINTER(Garch), _D, _SIZE, _D], ctypes.c_int),
+    "mlr_garch_filter_from": (
+        [ctypes.POINTER(Garch), ctypes.c_double, _D, _SIZE, _D],
+        ctypes.c_int,
+    ),
+    "mlr_garch_forecast": ([ctypes.POINTER(Garch), _SIZE, _D], ctypes.c_int),
+    "mlr_parkinson_vol": ([_D, _D, _SIZE, _D], ctypes.c_int),
+    "mlr_garman_klass_vol": ([_D, _D, _D, _D, _SIZE, _D], ctypes.c_int),
+    # sizing.h
+    "mlr_vol_target_position": (
+        [_D, ctypes.c_double, ctypes.c_double, _D, ctypes.c_double, _SIZE, _D],
+        ctypes.c_int,
+    ),
+    "mlr_kelly_fraction": ([_D, _SIZE, ctypes.c_double, _D], ctypes.c_int),
+    "mlr_drawdown_scale": ([_D, _SIZE, ctypes.c_double, _D], ctypes.c_int),
+    # split.h
+    "mlr_walk_forward_splits": (
+        [_SIZE] * 6 + [ctypes.c_int, ctypes.POINTER(Split), _SIZE, ctypes.POINTER(_SIZE)],
+        ctypes.c_int,
+    ),
+    # linreg.h
+    "mlr_lin_model_init": ([ctypes.POINTER(LinModel), _SIZE], ctypes.c_int),
+    "mlr_lin_model_free": ([ctypes.POINTER(LinModel)], None),
+    "mlr_linreg_fit": (
+        [_D, _D, _SIZE, _SIZE, ctypes.c_double, ctypes.POINTER(LinModel)],
+        ctypes.c_int,
+    ),
+    "mlr_linreg_predict": (
+        [_D, _SIZE, _SIZE, ctypes.POINTER(LinModel), _D],
+        ctypes.c_int,
+    ),
+    # version.h
+    "mlr_version": ([], ctypes.c_char_p),
+    "mlr_version_number": ([], ctypes.c_int),
+}
+
+
+def _load() -> ctypes.CDLL:
+    """Load the shared library that ships inside this package."""
+    here = pathlib.Path(__file__).resolve().parent
+    matches = sorted(
+        path
+        for pattern in ("walkforward_native.*", "libwalkforward_native.*")
+        for path in here.glob(pattern)
+        if path.suffix in {".so", ".dylib", ".dll", ".pyd"}
+    )
+    if not matches:
+        raise ImportError(
+            f"the walkforward native library is missing from {here}. "
+            "Reinstall the package, or build it in place with "
+            "`pip install -e python/`."
+        )
+    library = ctypes.CDLL(str(matches[0]))
+    for name, (argtypes, restype) in _SIGNATURES.items():
+        function = getattr(library, name)
+        function.argtypes = argtypes
+        function.restype = restype
+    return library
+
+
+lib = _load()
+
+
+def c_version() -> str:
+    """Version reported by the loaded shared library itself."""
+    return lib.mlr_version().decode()
+
+
+# --------------------------------------------------------------------------
+# Array plumbing
+# --------------------------------------------------------------------------
+
+
+def as_input(values: Any, name: str, *, ndim: int = 1) -> np.ndarray:
+    """Return `values` as a C-contiguous float64 array of the given rank."""
+    array = np.ascontiguousarray(values, dtype=np.float64)
+    if array.ndim != ndim:
+        raise ValueError(f"{name} must be {ndim}-dimensional, got {array.ndim} dimensions")
+    if array.size == 0:
+        raise ValueError(f"{name} is empty; every estimator needs at least one observation")
+    return array
+
+
+def ptr(array: np.ndarray) -> Any:
+    """Pointer to the first element. The array must already be contiguous."""
+    return array.ctypes.data_as(_D)
+
+
+def out_like(n: int) -> np.ndarray:
+    """A fresh writable output buffer, never shared with any input."""
+    return np.empty(n, dtype=np.float64)
+
+
+def same_length(name_a: str, a: np.ndarray, name_b: str, b: np.ndarray) -> None:
+    if a.shape[0] != b.shape[0]:
+        raise ValueError(
+            f"{name_a} and {name_b} must be the same length, "
+            f"got {a.shape[0]} and {b.shape[0]}"
+        )
+
+
+def like(values: np.ndarray, template: Any) -> Any:
+    """Give a pandas input its index back.
+
+    Realigning a bare array by hand is how lookahead creeps into a pandas
+    workflow, so a Series in means a Series out, on the same index.
+    """
+    if _pd is not None and isinstance(template, _pd.Series):
+        return _pd.Series(values, index=template.index, name=template.name)
+    return values
+
+
+def as_count(value: Any, name: str, *, minimum: int = 0) -> int:
+    """Validate a count before it becomes a ``size_t``.
+
+    Python integers are unbounded and negative values wrap when converted, so
+    the range check has to happen here rather than in C.
+    """
+    try:
+        count = int(value)
+    except (TypeError, ValueError):
+        raise TypeError(f"{name} must be an integer, got {value!r}") from None
+    if count != value:
+        raise TypeError(f"{name} must be a whole number, got {value!r}")
+    if count < minimum:
+        raise ValueError(f"{name} must be at least {minimum}, got {count}")
+    if count > 2**63 - 1:
+        raise ValueError(f"{name} is too large: {count}")
+    return count

walkforward/linear.py

@@ -0,0 +1,120 @@
+"""Ridge regression.
+
+The fit runs in C as a Householder QR on the centered design with
+``sqrt(ridge) I`` appended, so accuracy is about the condition number times
+epsilon rather than its square, and columns are shifted by their first row
+before centering so a feature at a large level (a price near 1e9 with unit
+variation) keeps its slope precision.
+
+Prediction is a dot product, so it stays in numpy: the coefficients are
+copied out and the C model is released as soon as the fit returns, which
+means there is no native pointer to outlive its owner.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Any
+
+import numpy as np
+
+from ._core import LinModel, as_input, check, lib, ptr
+
+try:  # sklearn is optional
+    from sklearn.base import BaseEstimator as _BaseEstimator
+    from sklearn.base import RegressorMixin as _RegressorMixin
+except ImportError:  # pragma: no cover - exercised where sklearn is absent
+
+    class _BaseEstimator:  # type: ignore[no-redef]
+        pass
+
+    class _RegressorMixin:  # type: ignore[no-redef]
+        pass
+
+
+__all__ = ["Ridge"]
+
+
+class Ridge(_RegressorMixin, _BaseEstimator):
+    """Ridge regression with an unpenalised intercept.
+
+    Minimises ``||Xc w - yc||^2 + ridge * ||w||^2`` on centered data, so the
+    intercept is recovered afterwards rather than shrunk.
+
+    Parameters
+    ----------
+    ridge
+        Penalty on the squared coefficients. ``0`` is ordinary least squares
+        and then the design must be full rank, which needs more rows than
+        columns and linearly independent ones.
+
+    Attributes
+    ----------
+    coef_ : ndarray of shape (n_features,)
+        Fitted weights, available after :meth:`fit`.
+    intercept_ : float
+        Fitted intercept.
+
+    Raises
+    ------
+    DomainError
+        The design is singular, or its arithmetic overflows. A rank-deficient
+        design is refused rather than silently pseudo-inverted; add a ridge if
+        that is what you want.
+
+    Notes
+    -----
+    Intended for tens of features, not thousands: the solve is dense and
+    unpivoted. Rank deficiency is detected on the diagonal of ``R``, which
+    catches exact and near-exact dependence but is not a guarantee for every
+    pathological design.
+    """
+
+    def __init__(self, ridge: float = 0.0) -> None:
+        self.ridge = ridge
+
+    def fit(self, X: Any, y: Any) -> Ridge:
+        """Fit the model. Leaves the estimator untouched if the fit fails."""
+        design = as_input(X, "X", ndim=2)
+        target = as_input(y, "y")
+        n, d = design.shape
+        if target.shape[0] != n:
+            raise ValueError(
+                f"X has {n} rows but y has {target.shape[0]}; they must match"
+            )
+        if self.ridge == 0.0 and n <= d:
+            raise ValueError(
+                f"X is {n} by {d}: with ridge=0 the fit needs more rows than "
+                "columns, because centering costs one rank. Pass a positive "
+                "ridge to fit anyway."
+            )
+
+        model = LinModel()
+        check(lib.mlr_lin_model_init(ctypes.byref(model), d), "Ridge.fit")
+        try:
+            check(
+                lib.mlr_linreg_fit(
+                    ptr(design), ptr(target), n, d, float(self.ridge), ctypes.byref(model)
+                ),
+                "Ridge.fit",
+                f"ridge={self.ridge!r} must be finite and non-negative, "
+                "and X and y must be finite",
+            )
+            # Copy out and release: no native pointer survives this call
+            self.coef_ = np.array([model.w[j] for j in range(d)], dtype=np.float64)
+            self.intercept_ = float(model.b)
+        finally:
+            lib.mlr_lin_model_free(ctypes.byref(model))
+        return self
+
+    def predict(self, X: Any) -> np.ndarray:
+        """Predict ``X @ coef_ + intercept_``."""
+        if not hasattr(self, "coef_"):
+            raise ValueError("this Ridge is not fitted yet; call fit first")
+        design = as_input(X, "X", ndim=2)
+        if design.shape[1] != self.coef_.shape[0]:
+            raise ValueError(
+                f"X has {design.shape[1]} features but the model was fitted on "
+                f"{self.coef_.shape[0]}"
+            )
+        return design @ self.coef_ + self.intercept_

walkforward/rolling.py

@@ -0,0 +1,74 @@
+"""Rolling window statistics.
+
+Trailing windows: ``out[i]`` is computed from ``x[i-window+1 : i+1]``, which
+*includes* ``x[i]``. A rolling statistic at index ``t`` therefore knows period
+``t`` and must be lagged one period before it sizes a position held over
+``t``; :func:`lag` does that. Indices without a full window are ``NaN``, and
+so is any window holding a non-finite value or whose arithmetic overflows.
+
+Accuracy does not degrade at index levels. The accumulators are shifted by an
+offset taken from inside the current window and rebuilt periodically, so a
+price series near 1e9, a long trend, and a bad tick that has since left the
+window all keep full precision.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ._core import as_count, as_input, check, lib, like, out_like, ptr
+
+__all__ = ["lag", "rolling_mean", "rolling_std"]
+
+
+def _rolling(function: Any, name: str, x: Any, window: int) -> Any:
+    array = as_input(x, "x")
+    size = as_count(window, "window", minimum=1)
+    out = out_like(array.shape[0])
+    check(function(ptr(array), array.shape[0], size, ptr(out)), name)
+    return like(out, x)
+
+
+def rolling_mean(x: Any, window: int) -> Any:
+    """Trailing mean over ``window`` observations, O(n).
+
+    Contemporaneous: ``out[t]`` includes ``x[t]``. See :func:`lag`.
+    """
+    return _rolling(lib.mlr_rolling_mean, "rolling_mean", x, window)
+
+
+def rolling_std(x: Any, window: int) -> Any:
+    """Trailing standard deviation over ``window`` observations, O(n).
+
+    Population convention, dividing by ``window``. Note that pandas
+    ``rolling().std()`` defaults to the sample convention and divides by
+    ``window - 1``, so the two differ by ``sqrt(window / (window - 1))``.
+
+    Contemporaneous: ``out[t]`` includes ``x[t]``. See :func:`lag`.
+    """
+    return _rolling(lib.mlr_rolling_std, "rolling_std", x, window)
+
+
+def lag(x: Any, periods: int = 1) -> Any:
+    """Shift a series forward, filling the start with ``NaN``.
+
+    The blessed way to turn a contemporaneous estimator into something safe to
+    size with: ``lag(rolling_std(returns, 20))`` at index ``t`` holds the value
+    computed through ``t-1``, so it is known when the position for ``t`` is
+    entered.
+
+    Parameters
+    ----------
+    x
+        The series to shift. A pandas Series keeps its index.
+    periods
+        How many periods to shift forward. Must be non-negative.
+    """
+    array = as_input(x, "x")
+    shift = as_count(periods, "periods", minimum=0)
+    out = np.full(array.shape[0], np.nan, dtype=np.float64)
+    if shift < array.shape[0]:
+        out[shift:] = array[: array.shape[0] - shift]
+    return like(out, x)

walkforward/sizing.py

@@ -0,0 +1,162 @@
+"""Turning a volatility forecast into a position.
+
+Timing contract, which the whole package is built around:
+
+* ``sigma[t]`` must be a forecast for period ``t`` made from information
+  available at the close of ``t-1``. :func:`~walkforward.ewma_vol` and the
+  GARCH filters already are; rolling statistics and range estimators are not
+  and must be lagged first.
+* ``position[t]`` is then the position, in units, entered at the close of
+  ``t-1`` at ``price[t-1]`` and held over period ``t``.
+* Its profit is ``position[t] * price[t-1] * returns[t]``. The price factor is
+  easy to drop and doing so silently rescales every result.
+
+So the price passed for index ``t`` is the *previous* close:
+``vol_target_position(sigma[1:], ..., price=close[:-1], ...)``, or equivalently
+``lag(close)`` aligned to the same index.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Any
+
+from ._core import as_input, check, lib, like, out_like, ptr, same_length
+
+__all__ = ["drawdown_scale", "kelly_fraction", "vol_target_position"]
+
+
+def vol_target_position(
+    sigma: Any,
+    target_vol: float,
+    equity: float,
+    price: Any,
+    max_leverage: float,
+) -> Any:
+    """Size a position so its volatility matches a target.
+
+    ``position = (target_vol / sigma) * (equity / price)``, capped so that
+    ``position * price <= max_leverage * equity``.
+
+    Read ``target_vol`` as a risk cap instead and the same formula caps risk
+    per position: both are "the fraction of equity you are willing to see move
+    in one period".
+
+    Parameters
+    ----------
+    sigma
+        Per-period volatility forecast for each period. Must be known before
+        the period starts; see the module docstring.
+    target_vol
+        Target per-period volatility as a fraction of equity. Annualised
+        targets convert as ``annual / sqrt(periods_per_year)``: 10% a year on
+        daily data is ``0.10 / sqrt(252)``, about 0.0063.
+    equity
+        Account equity. Finite and positive.
+    price
+        Entry price for each period, that is the previous close.
+    max_leverage
+        Cap on notional over equity. ``max_leverage * equity`` must be finite.
+
+    Returns
+    -------
+    Positions in units. A period whose sigma or price is non-finite,
+    non-positive, or extreme enough to make the position unrepresentable gets
+    a position of zero rather than a bad number.
+    """
+    sigma_array = as_input(sigma, "sigma")
+    price_array = as_input(price, "price")
+    same_length("sigma", sigma_array, "price", price_array)
+    out = out_like(sigma_array.shape[0])
+    check(
+        lib.mlr_vol_target_position(
+            ptr(sigma_array),
+            float(target_vol),
+            float(equity),
+            ptr(price_array),
+            float(max_leverage),
+            sigma_array.shape[0],
+            ptr(out),
+        ),
+        "vol_target_position",
+        f"target_vol={target_vol!r}, equity={equity!r} and max_leverage={max_leverage!r} "
+        "must be finite and positive, and max_leverage * equity must be finite",
+    )
+    return like(out, sigma)
+
+
+def kelly_fraction(returns: Any, fraction: float = 1.0) -> float:
+    """Mean-variance Kelly fraction of equity.
+
+    ``fraction * mean(returns) / var(returns)`` with the sample variance
+    (``n - 1`` denominator). Negative when the sample edge is negative, which
+    the caller should read as "no position".
+
+    This is a sizing utility, not an allocation model. It uses the raw
+    historical mean rather than the excess over a funding rate, and it knows
+    nothing about estimation error, fat tails, drawdown tolerance or the rest
+    of the book. Mean over variance from a short sample is a strongly
+    upward-biased estimate of the true edge, so treat the result as an upper
+    bound and pass a ``fraction`` well below 1. Half Kelly (0.5) gives up a
+    quarter of the growth rate for half the volatility, which is why it is the
+    usual starting point.
+
+    Parameters
+    ----------
+    returns
+        At least two finite per-period returns.
+    fraction
+        Fractional Kelly multiplier: 1.0 is full Kelly, 0.5 is half.
+
+    Raises
+    ------
+    DomainError
+        The sample has zero variance, or its variance or the estimate cannot
+        be represented.
+    """
+    array = as_input(returns, "returns")
+    if array.shape[0] < 2:
+        raise ValueError(f"kelly_fraction needs at least 2 returns, got {array.shape[0]}")
+    out = ctypes.c_double()
+    check(
+        lib.mlr_kelly_fraction(
+            ptr(array), array.shape[0], float(fraction), ctypes.byref(out)
+        ),
+        "kelly_fraction",
+        f"fraction={fraction!r} must be finite and positive, and every return finite",
+    )
+    return out.value
+
+
+def drawdown_scale(equity: Any, max_dd: float) -> Any:
+    """Exposure multiplier that tapers to zero as drawdown deepens.
+
+    With running peak ``P[i] = max(equity[:i+1])`` and drawdown
+    ``dd[i] = 1 - equity[i] / P[i]``, the result is
+    ``clip(1 - dd / max_dd, 0, 1)``: full exposure at a new high, nothing at
+    ``max_dd``.
+
+    Contemporaneous, and easy to misuse because it looks like a multiplier you
+    apply in place. ``scale[t]`` comes from ``equity[t]``, the close at the
+    *end* of period ``t``, so it is not known when the position for ``t`` is
+    entered. Scale ``position[t]`` by ``scale[t-1]``: use
+    :func:`~walkforward.lag`. Applying ``scale[t]`` to ``position[t]``
+    de-levers on the bar of a loss using that bar's own close, which flatters
+    a backtest.
+
+    Parameters
+    ----------
+    equity
+        Cumulative equity path, every value finite and positive.
+    max_dd
+        Drawdown at which exposure reaches zero, in ``(0, 1]``.
+    """
+    array = as_input(equity, "equity")
+    out = out_like(array.shape[0])
+    check(
+        lib.mlr_drawdown_scale(ptr(array), array.shape[0], float(max_dd), ptr(out)),
+        "drawdown_scale",
+        f"max_dd={max_dd!r} must be finite and in (0, 1], "
+        "and every equity value finite and positive",
+    )
+    return like(out, equity)