powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/backtest/metrics.py

@@ -0,0 +1,194 @@
+from typing import TypedDict
+
+"""Backtest Metrics - 纯 Decimal 指标计算（T7）
+
+口径 SSOT：T7 Task Confirmed Decisions（2026-09-05 用户确认）。全部函数
+只消费公开的 EquityCurve / BacktestConfig 标量，不读取 Runtime / Portfolio
+私有状态，不复制 Portfolio 记账逻辑。
+
+Decimal 处理：
+- 全程 Decimal（含幂与开方：``Decimal ** Decimal`` / ``Decimal.sqrt()``，
+  按当前 decimal context 精度求正确舍入结果）；
+- 不把 float 引入领域结果，不调用 ``quantize``。
+
+公式（与 T7 Task 逐字对应）：
+- daily_risk_free_return = (1 + annual_risk_free_rate) ** (1/tdpy) - 1
+  （几何无风险转换，与 annualized_return 的幂口径一致）
+- total_return = ending_equity / initial_cash - 1
+- max_drawdown = max((peak - v) / peak)；无回撤为 0
+- annualized_return = (ending/initial) ** (tdpy / n_days) - 1；n_days < 2 → None
+- sharpe_ratio = mean(daily_returns - daily_rf) / sample_stddev(daily_returns)
+  * sqrt(tdpy)；日收益 < 2 个或样本标准差为 0 → None
+- gross_turnover_rate = Σ abs(fill.price × fill.quantity) / 平均日末组合净值；
+  空曲线或平均日末净值为 0 → None，费用不进入成交金额
+"""
+
+from decimal import Decimal
+
+from quant_core.app.backtest.schema import BacktestMetrics, EquityCurve, EquityPoint
+from quant_core.app.order_execution.domain.order_event import Fill
+from quant_core.app.portfolio.ledger_schema import ClosedTrade
+
+_ONE = Decimal("1")
+
+
+def daily_equity_points(curve: EquityCurve) -> tuple[EquityPoint, ...]:
+    """日频采样：每个交易日期取最后一个 Equity Curve 点（时间严格递增）"""
+    last_by_day: dict[str, EquityPoint] = {}
+    for point in curve.points:
+        last_by_day[point.time.date().isoformat()] = point  # 时间递增 → 后写即当日最后
+    return tuple(sorted(last_by_day.values(), key=lambda p: p.time))
+
+
+def daily_risk_free_return(
+    annual_risk_free_rate: Decimal, trading_days_per_year: Decimal
+) -> Decimal:
+    """年化无风险收益率的几何日频转换（明确公式，测试覆盖）"""
+    return (_ONE + annual_risk_free_rate) ** (_ONE / trading_days_per_year) - _ONE
+
+
+def daily_returns(curve: EquityCurve, initial_cash: Decimal) -> tuple[Decimal | None, ...]:
+    """日频收益序列：首日相对 initial_cash，其后为相邻交易日收盘权益之比减一
+
+    前一日权益为 0 时相邻比无定义 → 该日收益为 None（禁止 epsilon /
+    伪造收益率；首日相对 initial_cash > 0 恒可定义，权益归零即 -1）。
+    """
+    points = daily_equity_points(curve)
+    returns: list[Decimal | None] = []
+    previous = initial_cash
+    for point in points:
+        if previous == 0:
+            returns.append(None)
+        else:
+            returns.append(point.total_value / previous - _ONE)
+        previous = point.total_value
+    return tuple(returns)
+
+
+def _sample_stddev(values: tuple[Decimal, ...]) -> Decimal:
+    """样本标准差（n - 1 分母；调用方保证 n >= 2）"""
+    n = Decimal(len(values))
+    mean = sum(values, Decimal("0")) / n
+    variance = sum(((v - mean) ** 2 for v in values), Decimal("0")) / (n - _ONE)
+    return variance.sqrt()
+
+
+def compute_max_drawdown(curve: EquityCurve) -> Decimal:
+    """相对历史峰值的最大跌幅（非负；无回撤为 0）"""
+    max_dd = Decimal("0")
+    peak: Decimal | None = None
+    for point in curve.points:
+        value = point.total_value
+        if peak is None or value > peak:
+            peak = value
+        elif peak > 0:
+            drawdown = (peak - value) / peak
+            if drawdown > max_dd:
+                max_dd = drawdown
+    return max_dd
+
+
+def compute_gross_turnover_rate(curve: EquityCurve, fills: tuple[Fill, ...]) -> Decimal | None:
+    """成交绝对金额合计除以平均日末组合净值。
+
+    成交金额不含费用；分钟曲线先按交易日取最后一点，避免因 Bar 数量不同
+    改变分母权重。空曲线或平均日末净值为零时不可计算。
+    """
+    day_points = daily_equity_points(curve)
+    if not day_points:
+        return None
+    average_value = sum((point.total_value for point in day_points), Decimal("0")) / Decimal(
+        len(day_points)
+    )
+    if average_value == 0:
+        return None
+    gross_notional = sum((fill.price * Decimal(fill.quantity) for fill in fills), Decimal("0"))
+    return gross_notional / average_value
+
+
+def compute_metrics(
+    curve: EquityCurve,
+    initial_cash: Decimal,
+    fill_count: int,
+    trading_days_per_year: Decimal,
+    annual_risk_free_rate: Decimal,
+    closed_trades: tuple[ClosedTrade, ...] | None = None,
+    fills: tuple[Fill, ...] = (),
+) -> BacktestMetrics:
+    """由已成功提交的权益曲线计算基础指标（口径见模块 docstring）"""
+    ending = curve.last_value
+    total_return = None if ending is None else ending / initial_cash - _ONE
+
+    day_points = daily_equity_points(curve)
+    n_days = len(day_points)
+    annualized_return: Decimal | None = None
+    sharpe_ratio: Decimal | None = None
+    if ending is not None and n_days >= 2:
+        annualized_return = (ending / initial_cash) ** (
+            trading_days_per_year / Decimal(n_days)
+        ) - _ONE
+
+        returns = daily_returns(curve, initial_cash)
+        defined = [r for r in returns if r is not None]
+        # 存在无定义日收益（前一日权益为 0）→ Sharpe 不可计算，返回 None
+        if len(returns) >= 2 and len(defined) == len(returns):
+            stddev = _sample_stddev(tuple(defined))
+            if stddev != 0:
+                daily_rf = daily_risk_free_return(annual_risk_free_rate, trading_days_per_year)
+                excess_mean = sum((r - daily_rf for r in defined), Decimal("0")) / Decimal(
+                    len(defined)
+                )
+                sharpe_ratio = excess_mean / stddev * trading_days_per_year.sqrt()
+
+    trade_metrics = _compute_trade_metrics(closed_trades)
+    return BacktestMetrics(
+        total_return=total_return,
+        annualized_return=annualized_return,
+        max_drawdown=compute_max_drawdown(curve),
+        sharpe_ratio=sharpe_ratio,
+        fill_count=fill_count,
+        gross_turnover_rate=compute_gross_turnover_rate(curve, fills),
+        **trade_metrics,
+    )
+
+
+class _TradeMetrics(TypedDict):
+    trade_count: int | None
+    win_rate: Decimal | None
+    profit_loss_ratio: Decimal | None
+    average_holding_days: Decimal | None
+
+
+def _compute_trade_metrics(closed_trades: tuple[ClosedTrade, ...] | None) -> _TradeMetrics:
+    if closed_trades is None:
+        return {
+            "trade_count": None,
+            "win_rate": None,
+            "profit_loss_ratio": None,
+            "average_holding_days": None,
+        }
+    count = len(closed_trades)
+    if count == 0:
+        return {
+            "trade_count": 0,
+            "win_rate": None,
+            "profit_loss_ratio": None,
+            "average_holding_days": None,
+        }
+    wins = tuple(trade.realized_pnl for trade in closed_trades if trade.realized_pnl > 0)
+    losses = tuple(-trade.realized_pnl for trade in closed_trades if trade.realized_pnl < 0)
+    average_win = sum(wins, Decimal("0")) / Decimal(len(wins)) if wins else None
+    average_loss = sum(losses, Decimal("0")) / Decimal(len(losses)) if losses else None
+    return {
+        "trade_count": count,
+        "win_rate": Decimal(len(wins)) / Decimal(count),
+        "profit_loss_ratio": (
+            average_win / average_loss
+            if average_win is not None and average_loss not in (None, Decimal("0"))
+            else None
+        ),
+        "average_holding_days": sum(
+            (Decimal(trade.holding_days) for trade in closed_trades), Decimal("0")
+        )
+        / Decimal(count),
+    }

quant_core/app/backtest/performance_report.py

@@ -0,0 +1,61 @@
+"""已完成回测的日末净值报告；不重新执行策略或改写权威结果。"""
+
+from decimal import Decimal
+
+from quant_core.app.backtest.metrics import daily_equity_points, daily_returns
+from quant_core.app.backtest.report_schema import (
+    BenchmarkSeries,
+    DailyPerformance,
+    PerformanceReport,
+    ReturnDistribution,
+)
+from quant_core.app.backtest.schema import BacktestResult
+
+
+class PerformanceReportService:
+    def build(
+        self, result: BacktestResult, benchmark: BenchmarkSeries | None = None
+    ) -> PerformanceReport:
+        """按既有指标的交易日日末采样计算；相对收益为净值之比，不混用研究标签。"""
+        points = daily_equity_points(result.equity_curve)
+        closes = {point.time.date(): point.total_value for point in points}
+        rates = daily_returns(result.equity_curve, result.config.initial_cash)
+        prices = dict(benchmark.values) if benchmark is not None else {}
+        if benchmark is not None and prices.keys() != closes.keys():
+            raise ValueError("基准与回测日末日期必须完整一致，禁止前填或截短")
+        peak = points[0].total_value if points else Decimal(0)
+        daily: list[DailyPerformance] = []
+        returns: list[Decimal] = []
+        for (day, value), rate in zip(sorted(closes.items()), rates, strict=True):
+            if rate is not None:
+                returns.append(rate)
+            peak = max(peak, value)
+            nav = value / result.config.initial_cash
+            benchmark_nav = prices[day] / benchmark.initial_value if benchmark is not None else None
+            daily.append(
+                DailyPerformance(
+                    day=day,
+                    nav=nav,
+                    return_rate=rate,
+                    drawdown=(peak - value) / peak if peak > 0 else Decimal(0),
+                    benchmark_nav=benchmark_nav,
+                    relative_nav=nav / benchmark_nav if benchmark_nav is not None else None,
+                )
+            )
+        relative = daily[-1].relative_nav if daily else None
+        return PerformanceReport(
+            daily=tuple(daily),
+            fees=sum((fill.fees.total for fill in result.fills), Decimal(0)),
+            distribution=ReturnDistribution(
+                count=len(returns),
+                negative=sum(rate < 0 for rate in returns),
+                zero=sum(rate == 0 for rate in returns),
+                positive=sum(rate > 0 for rate in returns),
+                minimum=min(returns) if returns else None,
+                maximum=max(returns) if returns else None,
+                mean=sum(returns, Decimal(0)) / len(returns) if returns else None,
+            ),
+            benchmark_name=benchmark.name if benchmark else None,
+            benchmark_revision=benchmark.revision if benchmark else None,
+            relative_total_return=relative - 1 if relative is not None else None,
+        )

quant_core/app/backtest/report_schema.py

@@ -0,0 +1,64 @@
+"""回测派生报告与显式基准的不可变数据契约。"""
+
+from datetime import date
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class BenchmarkSeries(BaseModel):
+    """明确起始基准及版本的日末价格序列，日期必须完整对齐。"""
+
+    model_config = ConfigDict(frozen=True)
+    name: str
+    revision: str = Field(min_length=1)
+    initial_value: Decimal = Field(gt=0)
+    values: tuple[tuple[date, Decimal], ...]
+
+    @model_validator(mode="after")
+    def validate_prices(self) -> "BenchmarkSeries":
+        days = [day for day, _ in self.values]
+        if days != sorted(set(days)) or any(
+            not value.is_finite() or value <= 0 for _, value in self.values
+        ):
+            raise ValueError("基准日期必须递增无重复，价格必须为有限正值")
+        return self
+
+
+class DailyPerformance(BaseModel):
+    """与既有日末采样口径一致的净值单点。"""
+
+    model_config = ConfigDict(frozen=True)
+    day: date
+    nav: Decimal
+    return_rate: Decimal | None
+    drawdown: Decimal
+    benchmark_nav: Decimal | None = None
+    relative_nav: Decimal | None = None
+
+
+class ReturnDistribution(BaseModel):
+    """实际账户日收益分布，缺失收益不计入样本。"""
+
+    model_config = ConfigDict(frozen=True)
+    count: int
+    negative: int
+    zero: int
+    positive: int
+    minimum: Decimal | None
+    maximum: Decimal | None
+    mean: Decimal | None
+
+
+class PerformanceReport(BaseModel):
+    """只从已完成结果派生的报告，不修改交易事实。"""
+
+    model_config = ConfigDict(frozen=True)
+    daily: tuple[DailyPerformance, ...]
+    distribution: ReturnDistribution
+    fees: Decimal
+    benchmark_name: str | None = None
+    benchmark_revision: str | None = None
+    relative_total_return: Decimal | None = None
+    return_basis: str = "actual_account_after_fees"
+    drawdown_basis: str = "daily_close_peak_excluding_initial_cash"