quantbt-engine 1.0.7__py3-none-any.whl

quantbt/reporting/portfolio_audit.py

@@ -0,0 +1,206 @@
+"""
+Portfolio domain audit helpers.
+
+These functions validate accounting and exposure invariants on completed
+multi-symbol portfolio results.  They are report-level checks only; they do not
+change execution semantics.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+import numpy as np
+import pandas as pd
+
+
+def build_portfolio_domain_audit(
+    result,
+    *,
+    tolerance: float = 1e-9,
+    raise_on_fail: bool = False,
+) -> Dict:
+    """
+    Return a compact audit summary for a multi-symbol portfolio result.
+
+    The audit checks that accepted-position attribution reconciles to the equity
+    curve, fees reconcile to the per-bar fee series, accepted notionals match
+    units times closes times contract size, and exposure-report identities hold.
+    Rebalance rows are informational: a non-empty report means the requested
+    target matrix differed from accepted positions, usually because a
+    portfolio/margin gate rejected a rebalance.
+    """
+    metadata = getattr(result, "metadata", {}) or {}
+    missing = [
+        name
+        for name in (
+            "target_units_report",
+            "accepted_units_report",
+            "accepted_notional_report",
+            "exposure_report",
+            "symbol_pnl_report",
+        )
+        if not isinstance(metadata.get(name), pd.DataFrame)
+    ]
+
+    accepted_units = _frame(metadata.get("accepted_units_report"))
+    accepted_notional = _frame(metadata.get("accepted_notional_report"))
+    exposure_report = _frame(metadata.get("exposure_report"))
+    symbol_pnl_report = _frame(metadata.get("symbol_pnl_report"))
+    rebalance_report = _frame(metadata.get("rebalance_report"))
+    fee_series = _series(metadata.get("fee_series"))
+
+    equity_residual = np.nan
+    if not symbol_pnl_report.empty:
+        pnl_sum = (
+            symbol_pnl_report.assign(
+                timestamp=pd.to_datetime(symbol_pnl_report["timestamp"], utc=True),
+                total_pnl=pd.to_numeric(symbol_pnl_report["total_pnl"], errors="coerce").fillna(0.0),
+            )
+            .groupby("timestamp", sort=False)["total_pnl"]
+            .sum()
+        )
+        equity_delta = result.equity.diff().fillna(0.0)
+        if getattr(result, "liquidated", False):
+            liq_idx = int(getattr(result, "liquidation_bar", -1))
+            if liq_idx >= 0:
+                equity_delta = equity_delta.iloc[:liq_idx]
+                pnl_sum = pnl_sum.reindex(equity_delta.index, fill_value=0.0)
+        else:
+            pnl_sum = pnl_sum.reindex(equity_delta.index, fill_value=0.0)
+        equity_residual = _max_abs((pnl_sum - equity_delta).to_numpy(dtype=float))
+
+    fee_residual = np.nan
+    if not symbol_pnl_report.empty and "fee" in symbol_pnl_report:
+        pnl_fee = float(pd.to_numeric(symbol_pnl_report["fee"], errors="coerce").fillna(0.0).sum())
+        metadata_fee = float(metadata.get("fee_total", fee_series.sum() if not fee_series.empty else 0.0))
+        fee_residual = abs(pnl_fee - metadata_fee)
+
+    notional_residual = _accepted_notional_residual(result, accepted_units, accepted_notional)
+    exposure_residual = _exposure_identity_residual(exposure_report)
+
+    rebalance_abs_notional = 0.0
+    if not rebalance_report.empty and "notional_diff" in rebalance_report:
+        rebalance_abs_notional = float(
+            pd.to_numeric(rebalance_report["notional_diff"], errors="coerce").fillna(0.0).abs().sum()
+        )
+
+    checks = {
+        "has_required_reports": not missing,
+        "pnl_reconciles_to_equity": _ok(equity_residual, tolerance),
+        "fees_reconcile": _ok(fee_residual, tolerance),
+        "accepted_notional_reconciles": _ok(notional_residual, tolerance),
+        "exposure_identities_reconcile": _ok(exposure_residual, tolerance),
+    }
+    passed = all(checks.values())
+    audit = {
+        "status": "pass" if passed else "fail",
+        "passed": passed,
+        "tolerance": float(tolerance),
+        "engine": metadata.get("engine"),
+        "backend": metadata.get("backend"),
+        "mode": metadata.get("mode"),
+        "asset_type": metadata.get("asset_type"),
+        "hedge_type": metadata.get("hedge_type"),
+        "missing_reports": missing,
+        "checks": checks,
+        "max_abs_pnl_equity_residual": _float_or_none(equity_residual),
+        "max_abs_fee_residual": _float_or_none(fee_residual),
+        "max_abs_accepted_notional_residual": _float_or_none(notional_residual),
+        "max_abs_exposure_identity_residual": _float_or_none(exposure_residual),
+        "rebalance_count": int(len(rebalance_report)),
+        "rebalance_abs_notional": float(rebalance_abs_notional),
+        "liquidated": bool(getattr(result, "liquidated", False)),
+        "liquidation_bar": int(getattr(result, "liquidation_bar", -1)),
+        "symbols": list(map(str, getattr(result, "symbols", ()))),
+    }
+    if raise_on_fail and not passed:
+        raise AssertionError(f"portfolio domain audit failed: {audit}")
+    return audit
+
+
+def _accepted_notional_residual(result, accepted_units: pd.DataFrame, accepted_notional: pd.DataFrame) -> float:
+    if accepted_units.empty or accepted_notional.empty:
+        return np.nan
+    closes = getattr(result, "closes", pd.DataFrame()).copy()
+    if closes.empty:
+        return np.nan
+    closes = closes.rename(columns={col: str(col).replace("Close_", "", 1) for col in closes.columns})
+    closes = closes.reindex(columns=accepted_units.columns)
+    contract_sizes = _contract_sizes_from_metadata(result, accepted_units.columns)
+    expected = accepted_units.mul(closes, axis=0).mul(contract_sizes, axis=1)
+    expected = expected.reindex_like(accepted_notional)
+    return _max_abs((expected - accepted_notional).to_numpy(dtype=float))
+
+
+def _contract_sizes_from_metadata(result, columns) -> pd.Series:
+    metadata = getattr(result, "metadata", {}) or {}
+    target = _frame(metadata.get("accepted_notional_report"))
+    units = _frame(metadata.get("accepted_units_report"))
+    closes = getattr(result, "closes", pd.DataFrame()).copy()
+    closes = closes.rename(columns={col: str(col).replace("Close_", "", 1) for col in closes.columns})
+    values = {}
+    for symbol in columns:
+        values[symbol] = 1.0
+        if target.empty or units.empty or closes.empty or symbol not in target or symbol not in units or symbol not in closes:
+            continue
+        denom = units[symbol] * closes[symbol]
+        mask = denom.abs() > 1e-12
+        if mask.any():
+            inferred = (target.loc[mask, symbol] / denom.loc[mask]).replace([np.inf, -np.inf], np.nan).dropna()
+            if not inferred.empty:
+                values[symbol] = float(inferred.iloc[0])
+    return pd.Series(values)
+
+
+def _exposure_identity_residual(exposure_report: pd.DataFrame) -> float:
+    if exposure_report.empty:
+        return np.nan
+    required = {"long_notional", "short_notional", "gross_notional", "net_notional"}
+    if not required.issubset(exposure_report.columns):
+        return np.nan
+    long_notional = pd.to_numeric(exposure_report["long_notional"], errors="coerce").fillna(0.0)
+    short_notional = pd.to_numeric(exposure_report["short_notional"], errors="coerce").fillna(0.0)
+    gross_notional = pd.to_numeric(exposure_report["gross_notional"], errors="coerce").fillna(0.0)
+    net_notional = pd.to_numeric(exposure_report["net_notional"], errors="coerce").fillna(0.0)
+    gross_residual = _max_abs((long_notional + short_notional - gross_notional).to_numpy(dtype=float))
+    net_residual = _max_abs((long_notional - short_notional - net_notional).to_numpy(dtype=float))
+    return max(gross_residual, net_residual)
+
+
+def _frame(value) -> pd.DataFrame:
+    return value if isinstance(value, pd.DataFrame) else pd.DataFrame()
+
+
+def _series(value) -> pd.Series:
+    return value if isinstance(value, pd.Series) else pd.Series(dtype=float)
+
+
+def _max_abs(value) -> float:
+    if value is None:
+        return np.nan
+    arr = np.asarray(value, dtype=np.float64)
+    arr = arr[np.isfinite(arr)]
+    if arr.size == 0:
+        return np.nan
+    return float(np.max(np.abs(arr)))
+
+
+def _ok(value: Optional[float], tolerance: float) -> bool:
+    if value is None:
+        return False
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError):
+        return False
+    return bool(np.isfinite(numeric) and numeric <= float(tolerance))
+
+
+def _float_or_none(value):
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError):
+        return None
+    if not np.isfinite(numeric):
+        return None
+    return numeric

quantbt/reporting/portfolio_nautilus.py

@@ -0,0 +1,140 @@
+"""Portfolio native-vs-Nautilus validation helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+import numpy as np
+import pandas as pd
+
+from ..core.results import BacktestResultV2
+
+
+def build_portfolio_nautilus_position_report(
+    native_result: BacktestResultV2,
+    nautilus_result: BacktestResultV2,
+) -> pd.DataFrame:
+    """Return timestamp/symbol position differences between native and Nautilus."""
+    native_pos = _position_frame(native_result)
+    nautilus_pos = _position_frame(nautilus_result)
+    symbols = sorted(set(native_pos.columns) | set(nautilus_pos.columns))
+    idx = native_result.equity.index.union(nautilus_result.equity.index).sort_values()
+    native_pos = native_pos.reindex(idx).ffill().fillna(0.0).reindex(columns=symbols, fill_value=0.0)
+    nautilus_pos = nautilus_pos.reindex(idx).ffill().fillna(0.0).reindex(columns=symbols, fill_value=0.0)
+
+    rows: List[Dict[str, Any]] = []
+    for timestamp in idx:
+        for symbol in symbols:
+            native_value = float(native_pos.loc[timestamp, symbol])
+            nautilus_value = float(nautilus_pos.loc[timestamp, symbol])
+            rows.append(
+                {
+                    "timestamp": timestamp,
+                    "symbol": symbol,
+                    "native_position": native_value,
+                    "nautilus_position": nautilus_value,
+                    "position_diff": native_value - nautilus_value,
+                }
+            )
+    return pd.DataFrame(rows)
+
+
+def build_portfolio_nautilus_validation_report(
+    native_result: BacktestResultV2,
+    nautilus_result: BacktestResultV2,
+    *,
+    target_tolerance: float = 1e-9,
+    position_tolerance: float = 1e-6,
+    equity_tolerance: float = 1e-6,
+) -> Dict[str, Any]:
+    """
+    Summarize portfolio package validation between native and Nautilus results.
+
+    This is an institutional audit summary, not a claim that Nautilus is the
+    optimizer path. It checks that the submitted Nautilus package matches the
+    native target-unit matrix and, when reports are available, compares
+    positions and equity.
+    """
+    native_target = _frame((native_result.metadata or {}).get("target_units_report"))
+    nautilus_target = _frame((nautilus_result.metadata or {}).get("portfolio_target_units"))
+    package_order_map = _frame((nautilus_result.metadata or {}).get("package_order_map"))
+    orders_report = _frame((nautilus_result.metadata or {}).get("orders_report", (nautilus_result.metadata or {}).get("order_report")))
+    fills_report = _frame((nautilus_result.metadata or {}).get("fills_report"))
+
+    expected_orders = _expected_order_count(native_target)
+    nautilus_orders = int((nautilus_result.metadata or {}).get("orders_count", len(orders_report)))
+    if nautilus_orders == 0:
+        nautilus_orders = int((nautilus_result.metadata or {}).get("order_count_input", len(package_order_map)))
+    nautilus_fills = int((nautilus_result.metadata or {}).get("fills_count", len(fills_report)))
+    if nautilus_fills == 0 and nautilus_orders > 0 and len(fills_report) == 0:
+        nautilus_fills = int((nautilus_result.metadata or {}).get("order_count_input", 0))
+
+    target_diff = _target_units_diff(native_target, nautilus_target)
+    position_report = build_portfolio_nautilus_position_report(native_result, nautilus_result)
+    max_position_diff = _max_abs(position_report, "position_diff")
+    final_equity_diff = float(native_result.equity.iloc[-1] - nautilus_result.equity.iloc[-1])
+
+    checks = {
+        "input_mode_is_portfolio_matrix": (nautilus_result.metadata or {}).get("input_mode") == "portfolio_matrix",
+        "target_units_match": target_diff <= float(target_tolerance),
+        "order_count_matches_target_transitions": nautilus_orders == expected_orders,
+        "fills_do_not_exceed_orders": nautilus_fills <= nautilus_orders,
+        "positions_within_tolerance": max_position_diff <= float(position_tolerance),
+        "final_equity_within_tolerance": abs(final_equity_diff) <= float(equity_tolerance),
+    }
+    passed = all(bool(value) for value in checks.values())
+    return {
+        "status": "pass" if passed else "diff",
+        "passed": bool(passed),
+        "checks": checks,
+        "expected_order_count": int(expected_orders),
+        "nautilus_orders": int(nautilus_orders),
+        "nautilus_fills": int(nautilus_fills),
+        "max_abs_target_units_diff": float(target_diff),
+        "max_abs_position_diff": float(max_position_diff),
+        "final_equity_diff": float(final_equity_diff),
+        "target_tolerance": float(target_tolerance),
+        "position_tolerance": float(position_tolerance),
+        "equity_tolerance": float(equity_tolerance),
+        "native_backend": (native_result.metadata or {}).get("backend"),
+        "nautilus_backend": (nautilus_result.metadata or {}).get("backend"),
+        "engine": (nautilus_result.metadata or {}).get("engine"),
+    }
+
+
+def _expected_order_count(target_units: pd.DataFrame) -> int:
+    if target_units.empty:
+        return 0
+    prev = target_units.shift(1).fillna(0.0)
+    delta = (target_units - prev).abs()
+    return int((delta > 1e-12).sum().sum())
+
+
+def _target_units_diff(native_target: pd.DataFrame, nautilus_target: pd.DataFrame) -> float:
+    if native_target.empty or nautilus_target.empty:
+        return np.inf
+    common_cols = sorted(set(native_target.columns) & set(nautilus_target.columns))
+    if not common_cols:
+        return np.inf
+    idx = native_target.index.union(nautilus_target.index).sort_values()
+    left = native_target.reindex(idx).ffill().fillna(0.0).reindex(columns=common_cols)
+    right = nautilus_target.reindex(idx).ffill().fillna(0.0).reindex(columns=common_cols)
+    arr = (left - right).to_numpy(dtype=float)
+    return float(np.nanmax(np.abs(arr))) if arr.size else 0.0
+
+
+def _position_frame(result: BacktestResultV2) -> pd.DataFrame:
+    frame = result.positions.copy()
+    frame = frame.rename(columns={col: str(col).replace("Position_", "", 1) for col in frame.columns})
+    return frame
+
+
+def _frame(value) -> pd.DataFrame:
+    return value if isinstance(value, pd.DataFrame) else pd.DataFrame()
+
+
+def _max_abs(frame: pd.DataFrame, column: str) -> float:
+    if frame.empty or column not in frame:
+        return np.inf
+    values = pd.to_numeric(frame[column], errors="coerce").replace([np.inf, -np.inf], np.nan).dropna().abs()
+    return float(values.max()) if not values.empty else 0.0

quantbt/sizing/__init__.py

@@ -0,0 +1,3 @@
+from .modes import compute_target_units
+
+__all__ = ["compute_target_units"]

quantbt/sizing/fast.py

@@ -0,0 +1,67 @@
+"""
+Fast ndarray sizing helpers.
+
+These helpers are internal optimization paths. They must match the public
+Series-based sizing functions in `quantbt.sizing.modes`.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numba import njit
+
+
+@njit(cache=True)
+def _signal_notional_matrix_numba(
+    signals: np.ndarray,
+    closes: np.ndarray,
+    allocs: np.ndarray,
+    use_pyramiding: bool,
+) -> np.ndarray:
+    n_bars, n_syms = signals.shape
+    out = np.zeros((n_bars, n_syms), dtype=np.float64)
+    for j in range(n_syms):
+        current_scale = 0.0
+        prev_sig = 0.0
+        for i in range(n_bars):
+            sig = signals[i, j]
+            if not use_pyramiding:
+                if sig > 0.0:
+                    sig = 1.0
+                elif sig < 0.0:
+                    sig = -1.0
+                else:
+                    sig = 0.0
+            if i == 0 or sig != prev_sig:
+                if sig != 0.0:
+                    current_scale = allocs[j] / closes[i, j]
+                else:
+                    current_scale = 0.0
+            out[i, j] = sig * current_scale
+            prev_sig = sig
+    return out
+
+
+def scale_signal_notional_matrix(
+    signals: np.ndarray,
+    closes: np.ndarray,
+    allocs: np.ndarray,
+    use_pyramiding: bool = True,
+) -> np.ndarray:
+    """
+    Return target-unit matrix for signal_notional sizing.
+
+    The behavior is intentionally identical to `scale_signal_notional` applied
+    per symbol: anchor units on signal transition and keep them frozen between
+    transitions.
+    """
+    sig = np.ascontiguousarray(signals, dtype=np.float64)
+    cls = np.ascontiguousarray(closes, dtype=np.float64)
+    alc = np.ascontiguousarray(allocs, dtype=np.float64)
+    if sig.shape != cls.shape:
+        raise ValueError("signals and closes must have the same shape")
+    if sig.ndim != 2:
+        raise ValueError("signals and closes must be 2D arrays")
+    if len(alc) != sig.shape[1]:
+        raise ValueError("allocs length must match number of symbols")
+    return _signal_notional_matrix_numba(sig, cls, alc, bool(use_pyramiding))

quantbt/sizing/modes.py

@@ -0,0 +1,162 @@
+"""
+quantbt.sizing.modes
+--------------------
+Position scaling: converts raw signal weights into target *units* (contracts)
+that the numba engine can consume directly.
+
+Five modes
+~~~~~~~~~~
+notional
+    target_units[i] = signal[i] × (alloc / close[i])
+    Units recomputed every bar → constant notional exposure.
+    Generates a trade whenever signal OR price changes.  High turnover on
+    intraday data; intended for EOD / multi-day bars.
+
+unit
+    target_units[i] = signal[i] × (alloc / close[0])
+    Scale fixed at the *first* bar's price.  Units stable as price moves;
+    notional drifts with the market.
+
+signal_notional  ← recommended for systematic strategies
+    Units are re-anchored to current price ONLY when the signal weight
+    changes.  Between signal changes the unit count is frozen → no
+    spurious micro-trades due to price drift.
+    target_units[i] = signal[i] × (alloc / close[change_bar])
+
+pct_equity
+    Raw weight is passed straight through to the %_equity numba kernel,
+    which sizes units from live equity at execution time.
+    Returns the raw signal unchanged; no pre-scaling needed.
+
+dca_ladder
+    Raw signed structural level is passed straight through to the DCA ladder
+    execution kernel.  The kernel turns High/Low limit touches into actual
+    filled units at each grid trigger price.
+
+Parameters
+----------
+signal : pd.Series       raw weight (float), e.g. 1.0 / -0.5 / 0.3
+close  : pd.Series       closing price, same index as signal
+alloc  : float           notional allocation per full signal unit (USD)
+use_pyramiding : bool    if False, signal is clipped to {-1, 0, 1}
+
+Returns
+-------
+pd.Series  target units (float), same index as signal
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def scale_notional(
+    signal: pd.Series,
+    close: pd.Series,
+    alloc: float,
+    use_pyramiding: bool = True,
+) -> pd.Series:
+    sig = signal if use_pyramiding else np.sign(signal)
+    return sig * (alloc / close)
+
+
+def scale_unit(
+    signal: pd.Series,
+    close: pd.Series,
+    alloc: float,
+    use_pyramiding: bool = True,
+) -> pd.Series:
+    sig   = signal if use_pyramiding else np.sign(signal)
+    scale = alloc / close.iloc[0]
+    return sig * scale
+
+
+def scale_signal_notional(
+    signal: pd.Series,
+    close: pd.Series,
+    alloc: float,
+    use_pyramiding: bool = True,
+) -> pd.Series:
+    """
+    Anchor-on-change scaling.
+
+    Units are computed once per signal transition using the prevailing price
+    at that bar, then held constant until the next transition.  This is the
+    standard approach in institutional systematic desks to avoid phantom
+    rebalancing trades.
+    """
+    sig_vals = signal.values if use_pyramiding else np.sign(signal.values)
+    pr_vals  = close.values
+    n        = len(sig_vals)
+    target   = np.zeros(n, dtype=np.float64)
+
+    current_scale = 0.0
+    for i in range(n):
+        if i == 0 or sig_vals[i] != sig_vals[i - 1]:
+            current_scale = (alloc / pr_vals[i]) if sig_vals[i] != 0 else 0.0
+        target[i] = sig_vals[i] * current_scale
+
+    return pd.Series(target, index=signal.index)
+
+
+def scale_pct_equity(
+    signal: pd.Series,
+    use_pyramiding: bool = True,
+) -> pd.Series:
+    """
+    No pre-scaling.  Pass raw weight directly; the numba kernel sizes from
+    live equity at execution time.
+    """
+    return signal if use_pyramiding else np.sign(signal).astype(float)
+
+
+def scale_dca_ladder(signal: pd.Series) -> pd.Series:
+    """
+    No pre-scaling.  Pass signed structural levels directly:
+    +1..+N for long ladders, -1..-N for short ladders, 0 for flat.
+    """
+    return signal.astype(float)
+
+
+# ── dispatcher ──────────────────────────────────────────────────────────────
+
+def compute_target_units(
+    hedge_type:     str,
+    signal:         pd.Series,
+    close:          pd.Series,
+    alloc:          float,
+    use_pyramiding: bool = True,
+) -> pd.Series:
+    """
+    Central dispatcher.  Returns target-unit series for any supported mode.
+
+    Parameters
+    ----------
+    hedge_type : {'notional', 'unit', 'signal_notional', '%_equity', 'dca_ladder'}
+    signal     : raw weight series
+    close      : close price series
+    alloc      : notional per full unit of signal
+    use_pyramiding : allow fractional weights; if False snaps to {-1,0,1}
+    """
+    ht = hedge_type.lower().strip()
+
+    if ht == "notional":
+        return scale_notional(signal, close, alloc, use_pyramiding)
+
+    if ht == "unit":
+        return scale_unit(signal, close, alloc, use_pyramiding)
+
+    if ht in ("signal_notional", "signal"):
+        return scale_signal_notional(signal, close, alloc, use_pyramiding)
+
+    if ht in ("%_equity", "pct_equity"):
+        return scale_pct_equity(signal, use_pyramiding)
+
+    if ht in ("dca_ladder", "dca"):
+        return scale_dca_ladder(signal)
+
+    raise ValueError(
+        f"Unknown hedge_type '{hedge_type}'. "
+        "Choose from: 'notional', 'unit', 'signal_notional', '%_equity', 'dca_ladder'."
+    )

quantbt/viz/__init__.py

@@ -0,0 +1,4 @@
+from .plots  import quick_plot, tearsheet
+from .themes import apply_theme, PALETTE
+
+__all__ = ["quick_plot", "tearsheet", "apply_theme", "PALETTE"]