tensorquantlib 0.3.0__py3-none-any.whl

tensorquantlib/backtest/engine.py

@@ -0,0 +1,240 @@
+"""Backtesting engine with realistic execution cost models."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from tensorquantlib.backtest.strategy import Strategy, Trade
+
+
+# ------------------------------------------------------------------ #
+# Execution cost models
+# ------------------------------------------------------------------ #
+
+@dataclass
+class SlippageModel:
+    """Market-impact and bid-ask spread model.
+
+    Total slippage = half-spread cost + square-root market-impact cost.
+
+    Parameters
+    ----------
+    fixed_spread : float
+        One-way half-spread as a fraction of price.
+        E.g. ``0.0005`` = 5 bps one-way (10 bps round-trip).
+    market_impact : float
+        Square-root market-impact coefficient.
+        Cost per unit = ``price × market_impact × sqrt(|qty| / adv)``.
+        Set to 0 to disable market impact.
+    adv : float
+        Average daily volume (units). Used for impact scaling only.
+    """
+
+    fixed_spread: float = 0.0
+    market_impact: float = 0.0
+    adv: float = 1_000_000.0
+
+    def cost(self, price: float, quantity: float) -> float:
+        """Compute slippage cost for one trade (always non-negative)."""
+        spread_cost = abs(quantity) * price * self.fixed_spread
+        if self.market_impact > 0.0 and self.adv > 0.0:
+            impact_cost = (abs(quantity) * price * self.market_impact
+                           * np.sqrt(abs(quantity) / self.adv))
+        else:
+            impact_cost = 0.0
+        return float(spread_cost + impact_cost)
+
+
+@dataclass
+class CommissionModel:
+    """Commission / brokerage fee model.
+
+    Total commission = max(per_trade + per_unit×|qty| + percentage×notional,
+    minimum).
+
+    Parameters
+    ----------
+    per_trade : float
+        Fixed fee per order (e.g. ``1.0`` = $1 per trade).
+    per_unit : float
+        Fee per unit traded (e.g. ``0.005`` = half a cent per share).
+    percentage : float
+        Fraction of notional (e.g. ``0.001`` = 10 bps of notional).
+    minimum : float
+        Minimum commission per trade.
+    """
+
+    per_trade: float = 0.0
+    per_unit: float = 0.0
+    percentage: float = 0.0
+    minimum: float = 0.0
+
+    def cost(self, price: float, quantity: float) -> float:
+        """Compute commission for one trade (always non-negative)."""
+        notional = abs(quantity) * price
+        c = (self.per_trade
+             + abs(quantity) * self.per_unit
+             + notional * self.percentage)
+        return float(max(c, self.minimum))
+
+
+# Pre-built convenience presets
+#: Zero-cost model (default when no model is supplied).
+ZERO_COST = CommissionModel()
+#: Interactive Brokers-style equity commission ($0.005/share, $1 min).
+EQUITY_COMM = CommissionModel(per_unit=0.005, minimum=1.0)
+#: Typical institutional FX desk (0.2 bps of notional).
+FX_COMM = CommissionModel(percentage=0.00002)
+#: Liquid-equity half-spread slippage (5 bps one-way).
+EQUITY_SLIP = SlippageModel(fixed_spread=0.0005)
+#: Illiquid name: 20 bps spread + square-root market impact.
+ILLIQUID_SLIP = SlippageModel(fixed_spread=0.002, market_impact=0.1, adv=50_000)
+
+
+# ------------------------------------------------------------------ #
+# Backtest result
+# ------------------------------------------------------------------ #
+
+@dataclass
+class BacktestResult:
+    """Container for backtest output."""
+
+    equity_curve: np.ndarray
+    """Equity value at each step."""
+
+    trades: list[Trade]
+    """List of all executed trades."""
+
+    returns: np.ndarray
+    """Per-step returns of the equity curve."""
+
+    final_equity: float
+    """Final portfolio value."""
+
+    total_commission: float = 0.0
+    """Total commissions paid during the backtest."""
+
+    total_slippage: float = 0.0
+    """Total slippage cost paid during the backtest."""
+
+    total_turnover: float = 0.0
+    """Total gross notional traded (sum of |qty| * price)."""
+
+    n_trades: int = 0
+    """Number of trades executed."""
+
+    greeks_history: dict = field(default_factory=dict)
+    """Per-step Greeks recorded by the strategy (if any)."""
+
+
+# ------------------------------------------------------------------ #
+# Engine
+# ------------------------------------------------------------------ #
+
+class BacktestEngine:
+    """Run a :class:`Strategy` over a price series with realistic execution.
+
+    Parameters
+    ----------
+    strategy : Strategy
+        Strategy instance to run.
+    prices : array-like
+        1-D array of asset prices (one per time step).
+    initial_capital : float
+        Starting cash.
+    slippage : SlippageModel, optional
+        Slippage model.  Defaults to ``SlippageModel()`` (zero slippage).
+        Use :data:`EQUITY_SLIP` for a realistic liquid-equity preset.
+    commission : CommissionModel, optional
+        Commission model.  Defaults to ``CommissionModel()`` (zero fees).
+        Use :data:`EQUITY_COMM` for an Interactive Brokers-style preset.
+
+    Examples
+    --------
+    Zero-cost (default)::
+
+        engine = BacktestEngine(strategy, prices)
+
+    With realistic costs::
+
+        from tensorquantlib.backtest.engine import EQUITY_SLIP, EQUITY_COMM
+        engine = BacktestEngine(
+            strategy, prices,
+            slippage=EQUITY_SLIP,
+            commission=EQUITY_COMM,
+        )
+    """
+
+    def __init__(
+        self,
+        strategy: Strategy,
+        prices,
+        initial_capital: float = 1_000_000.0,
+        slippage: SlippageModel | None = None,
+        commission: CommissionModel | None = None,
+    ):
+        self.strategy = strategy
+        self.prices = np.asarray(prices, dtype=float)
+        self.initial_capital = initial_capital
+        self.slippage = slippage if slippage is not None else SlippageModel()
+        self.commission = commission if commission is not None else CommissionModel()
+
+    def run(self) -> BacktestResult:
+        """Execute the backtest and return a :class:`BacktestResult`."""
+        strat = self.strategy
+        prices = self.prices
+        n = len(prices)
+
+        strat.cash = self.initial_capital
+        strat.position = 0.0
+        strat.trades = []
+
+        equity = np.zeros(n)
+        total_commission = 0.0
+        total_slippage = 0.0
+        total_turnover = 0.0
+
+        for i in range(n):
+            desired = strat.on_data(i, prices[i])
+            delta_pos = desired - strat.position
+
+            if abs(delta_pos) > 1e-12:
+                slip = self.slippage.cost(prices[i], delta_pos)
+                comm = self.commission.cost(prices[i], delta_pos)
+                notional = abs(delta_pos) * prices[i]
+
+                total_slippage += slip
+                total_commission += comm
+                total_turnover += notional
+
+                # Cash: pay for shares + execution costs
+                strat.cash -= delta_pos * prices[i] + slip + comm
+                strat.position = desired
+
+                trade = Trade(
+                    step=i,
+                    quantity=delta_pos,
+                    price=prices[i],
+                    slippage=slip,
+                    commission=comm,
+                )
+                strat.trades.append(trade)
+                strat.on_fill(trade)
+
+            equity[i] = strat.cash + strat.position * prices[i]
+
+        returns = np.diff(equity) / np.where(
+            np.abs(equity[:-1]) > 1e-12, equity[:-1], 1.0
+        )
+        return BacktestResult(
+            equity_curve=equity,
+            trades=strat.trades,
+            returns=returns,
+            final_equity=float(equity[-1]),
+            total_commission=total_commission,
+            total_slippage=total_slippage,
+            total_turnover=total_turnover,
+            n_trades=len(strat.trades),
+            greeks_history=dict(getattr(strat, "_greeks_history", {})),
+        )

tensorquantlib/backtest/metrics.py

@@ -0,0 +1,320 @@
+"""Performance metrics for backtesting."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from tensorquantlib.backtest.strategy import Trade
+
+
+def sharpe_ratio(returns: np.ndarray, rf: float = 0.0,
+                 periods_per_year: int = 252) -> float:
+    """Annualised Sharpe ratio.
+
+    Parameters
+    ----------
+    returns : array-like
+        Period returns (e.g. daily).
+    rf : float
+        Risk-free rate per period.
+    periods_per_year : int
+        Annualisation factor (252 for daily).
+
+    Returns
+    -------
+    float
+        Annualised Sharpe ratio.
+    """
+    r = np.asarray(returns, dtype=float)
+    excess = r - rf
+    std = np.std(excess, ddof=1)
+    if std < 1e-15:
+        return 0.0
+    return float(np.mean(excess) / std * np.sqrt(periods_per_year))
+
+
+def max_drawdown(equity: np.ndarray) -> float:
+    """Maximum drawdown from peak.
+
+    Parameters
+    ----------
+    equity : array-like
+        Equity curve (absolute values).
+
+    Returns
+    -------
+    float
+        Maximum drawdown as a positive fraction (e.g. 0.15 = 15%).
+    """
+    eq = np.asarray(equity, dtype=float)
+    peak = np.maximum.accumulate(eq)
+    dd = (peak - eq) / np.where(peak > 0, peak, 1.0)
+    return float(np.max(dd))
+
+
+def sortino_ratio(returns: np.ndarray, rf: float = 0.0,
+                  periods_per_year: int = 252) -> float:
+    """Annualised Sortino ratio (downside deviation only).
+
+    Parameters
+    ----------
+    returns : array-like
+        Period returns.
+    rf : float
+        Risk-free rate per period.
+    periods_per_year : int
+        Annualisation factor.
+
+    Returns
+    -------
+    float
+        Annualised Sortino ratio.
+    """
+    r = np.asarray(returns, dtype=float)
+    excess = r - rf
+    downside = excess[excess < 0]
+    if len(downside) == 0:
+        return float("inf") if np.mean(excess) > 0 else 0.0
+    down_std = np.sqrt(np.mean(downside**2))
+    if down_std < 1e-15:
+        return 0.0
+    return float(np.mean(excess) / down_std * np.sqrt(periods_per_year))
+
+
+def win_rate(trades: np.ndarray) -> float:
+    """Fraction of profitable trades.
+
+    Parameters
+    ----------
+    trades : array-like
+        P&L per trade (positive = profit).
+
+    Returns
+    -------
+    float
+        Win rate in [0, 1].
+    """
+    t = np.asarray(trades, dtype=float)
+    if len(t) == 0:
+        return 0.0
+    return float(np.sum(t > 0) / len(t))
+
+
+def profit_factor(trades: np.ndarray) -> float:
+    """Profit factor = gross profits / gross losses.
+
+    Parameters
+    ----------
+    trades : array-like
+        P&L per trade.
+
+    Returns
+    -------
+    float
+        Profit factor. Returns inf if no losses.
+    """
+    t = np.asarray(trades, dtype=float)
+    gross_profit = float(np.sum(t[t > 0]))
+    gross_loss = float(np.abs(np.sum(t[t < 0])))
+    if gross_loss < 1e-15:
+        return float("inf") if gross_profit > 0 else 0.0
+    return gross_profit / gross_loss
+
+
+# ------------------------------------------------------------------ #
+# Additional metrics
+# ------------------------------------------------------------------ #
+
+def annualized_return(equity: np.ndarray, periods_per_year: int = 252) -> float:
+    """Compound annualized growth rate (CAGR) from an equity curve.
+
+    Parameters
+    ----------
+    equity : array-like
+        Equity value at each step (must start > 0).
+    periods_per_year : int
+        Annualisation factor (252 for daily).
+
+    Returns
+    -------
+    float
+        Annualized return, e.g. 0.12 = 12 %.
+    """
+    eq = np.asarray(equity, dtype=float)
+    if len(eq) < 2 or eq[0] <= 0:
+        return 0.0
+    total_periods = len(eq) - 1
+    years = total_periods / periods_per_year
+    if years <= 0:
+        return 0.0
+    return float((eq[-1] / eq[0]) ** (1.0 / years) - 1.0)
+
+
+def calmar_ratio(equity: np.ndarray, periods_per_year: int = 252) -> float:
+    """Calmar ratio = annualized return / maximum drawdown.
+
+    Parameters
+    ----------
+    equity : array-like
+        Equity curve.
+    periods_per_year : int
+        Annualisation factor.
+
+    Returns
+    -------
+    float
+        Calmar ratio.  Returns ``inf`` if max drawdown is zero.
+    """
+    ann_ret = annualized_return(equity, periods_per_year)
+    mdd = max_drawdown(equity)
+    if mdd < 1e-15:
+        return float("inf") if ann_ret > 0 else 0.0
+    return float(ann_ret / mdd)
+
+
+def information_ratio(
+    strategy_returns: np.ndarray,
+    benchmark_returns: np.ndarray,
+    periods_per_year: int = 252,
+) -> float:
+    """Annualised information ratio (IR).
+
+    IR = E[active_return] / std(active_return) * sqrt(periods_per_year)
+
+    Parameters
+    ----------
+    strategy_returns : array-like
+        Period returns of the strategy.
+    benchmark_returns : array-like
+        Period returns of the benchmark.
+    periods_per_year : int
+        Annualisation factor.
+
+    Returns
+    -------
+    float
+        Annualised information ratio.
+    """
+    active = np.asarray(strategy_returns, dtype=float) - np.asarray(benchmark_returns, dtype=float)
+    std = np.std(active, ddof=1)
+    if std < 1e-15:
+        return 0.0
+    return float(np.mean(active) / std * np.sqrt(periods_per_year))
+
+
+def turnover(trades: list, initial_capital: float = 1_000_000.0) -> float:
+    """Annualized one-way turnover as a fraction of initial capital.
+
+    turnover = total_notional_traded / initial_capital
+
+    Parameters
+    ----------
+    trades : list of Trade
+        Executed trades (each must have ``.quantity`` and ``.price``).
+    initial_capital : float
+        Starting capital used as the denominator.
+
+    Returns
+    -------
+    float
+        Turnover (e.g. 2.5 = 250 % of capital traded).
+    """
+    if not trades:
+        return 0.0
+    total_notional = sum(abs(t.quantity) * t.price for t in trades)
+    return float(total_notional / initial_capital)
+
+
+def hedge_pnl_attribution(
+    equity_curve: np.ndarray,
+    deltas: list,
+    gammas: list,
+    prices: np.ndarray,
+) -> dict[str, np.ndarray]:
+    """Decompose per-step portfolio P&L into Delta, Gamma, and residual.
+
+    For a continuously delta-hedged portfolio, the per-step P&L can be
+    approximated as:
+
+    .. math::
+
+        \\text{Total P\\&L} \\approx
+        \\underbrace{\\Delta \\cdot \\Delta S}_{\\text{delta P\\&L}}
+        + \\underbrace{\\tfrac{1}{2}\\Gamma (\\Delta S)^2}_{\\text{gamma P\\&L}}
+        + \\text{residual}
+
+    The residual captures higher-order terms (Theta decay, vanna, etc.) and
+    hedging error from discrete rebalancing.
+
+    Parameters
+    ----------
+    equity_curve : array-like
+        Portfolio equity at each step (length N).
+    deltas : list of float
+        Per-step delta of the overall position (length N).
+    gammas : list of float
+        Per-step gamma (length N).
+    prices : array-like
+        Underlying asset price at each step (length N).
+
+    Returns
+    -------
+    dict
+        Keys ``'delta_pnl'``, ``'gamma_pnl'``, ``'residual_pnl'``.
+        Each is an array of length N-1.
+    """
+    equity = np.asarray(equity_curve, dtype=float)
+    prices_arr = np.asarray(prices, dtype=float)
+    delta_arr = np.asarray(deltas, dtype=float)
+    gamma_arr = np.asarray(gammas, dtype=float)
+
+    n = len(equity) - 1
+    total_pnl = np.diff(equity)
+    dS = np.diff(prices_arr[:n + 1])
+
+    delta_pnl = delta_arr[:n] * dS
+    gamma_pnl = 0.5 * gamma_arr[:n] * dS ** 2
+    residual_pnl = total_pnl - delta_pnl - gamma_pnl
+
+    return {
+        "delta_pnl": delta_pnl,
+        "gamma_pnl": gamma_pnl,
+        "residual_pnl": residual_pnl,
+    }
+
+
+def hedge_efficiency(
+    hedged_equity: np.ndarray,
+    unhedged_equity: np.ndarray,
+) -> float:
+    """Variance reduction achieved by a hedge.
+
+    .. math::
+
+        \\text{efficiency} = 1 - \\frac{\\operatorname{Var}(\\text{hedged P\\&L})}{
+        \\operatorname{Var}(\\text{unhedged P\\&L})}
+
+    Returns 1.0 for a perfect hedge, 0.0 if the hedge adds no value,
+    and a negative number if the hedge increases variance.
+
+    Parameters
+    ----------
+    hedged_equity : array-like
+        Equity curve of the hedged portfolio.
+    unhedged_equity : array-like
+        Equity curve of the same portfolio *without* hedging.
+
+    Returns
+    -------
+    float
+        Hedge efficiency in (-inf, 1].
+    """
+    hedged_ret = np.diff(np.asarray(hedged_equity, dtype=float))
+    unhedged_ret = np.diff(np.asarray(unhedged_equity, dtype=float))
+    var_unhedged = float(np.var(unhedged_ret, ddof=1))
+    if var_unhedged < 1e-15:
+        return 0.0
+    var_hedged = float(np.var(hedged_ret, ddof=1))
+    return float(1.0 - var_hedged / var_unhedged)