quantbt-engine 1.0.7__py3-none-any.whl

quantbt/benchmarks/run_optimization_overhead.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Phase 32C optimization overhead and prepared-evaluator benchmark."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+import time
+
+import numpy as np
+import pandas as pd
+
+PACKAGE_DIR = Path(__file__).resolve().parents[1]
+PROJECT_DIR = PACKAGE_DIR.parent
+if str(PROJECT_DIR) not in sys.path:
+    sys.path.insert(0, str(PROJECT_DIR))
+
+from quantbt import (  # noqa: E402
+    GenericEndpointEvaluator,
+    IntrabarIntentTape,
+    ObjectiveResult,
+    OptimizationConfig,
+    OptunaOptimizer,
+    PreparedSignalEvaluator,
+    QuantBTEndpoint,
+    SamplerConfig,
+)
+
+
+def run_benchmark(rows: int = 360, trials: int = 24, loops: int = 24) -> dict:
+    df = _frame(rows)
+    optimizer_seconds = _optimizer_overhead(trials)
+    normal_seconds, prepared_seconds, signal_diff = _signal_replay_benchmark(df, loops)
+    first_intrabar, warm_intrabar, intrabar_diff = _intrabar_compile_benchmark(df)
+    status = "pass" if signal_diff <= 1e-9 and intrabar_diff <= 1e-9 else "fail"
+    return {
+        "status": status,
+        "rows": int(rows),
+        "trials": int(trials),
+        "loops": int(loops),
+        "optimizer_overhead_seconds": float(optimizer_seconds),
+        "optimizer_overhead_per_trial_seconds": float(optimizer_seconds / max(1, trials)),
+        "normal_signal_replay_seconds": float(normal_seconds),
+        "prepared_signal_replay_seconds": float(prepared_seconds),
+        "prepared_signal_speedup": float(normal_seconds / prepared_seconds) if prepared_seconds > 0 else 0.0,
+        "signal_final_equity_diff": float(signal_diff),
+        "intrabar_first_run_seconds": float(first_intrabar),
+        "intrabar_warm_run_seconds": float(warm_intrabar),
+        "intrabar_compile_to_warm_ratio": float(first_intrabar / warm_intrabar) if warm_intrabar > 0 else 0.0,
+        "intrabar_final_equity_diff": float(intrabar_diff),
+    }
+
+
+def make_markdown(report: dict) -> str:
+    return "\n".join(
+        [
+            "# Phase 32C Optimization Overhead Benchmark",
+            "",
+            f"Status: **{report['status']}**",
+            "",
+            "| Measurement | Value |",
+            "|---|---:|",
+            f"| Optimizer overhead | `{report['optimizer_overhead_seconds']:.6f}s` |",
+            f"| Optimizer overhead / trial | `{report['optimizer_overhead_per_trial_seconds']:.6f}s` |",
+            f"| Normal signal replays | `{report['normal_signal_replay_seconds']:.6f}s` |",
+            f"| Prepared signal replays | `{report['prepared_signal_replay_seconds']:.6f}s` |",
+            f"| Prepared signal speedup | `{report['prepared_signal_speedup']:.3f}x` |",
+            f"| Intrabar first run | `{report['intrabar_first_run_seconds']:.6f}s` |",
+            f"| Intrabar warm run | `{report['intrabar_warm_run_seconds']:.6f}s` |",
+            f"| Intrabar first/warm ratio | `{report['intrabar_compile_to_warm_ratio']:.3f}x` |",
+            "",
+            "Parity checks:",
+            "",
+            f"- Signal final equity diff: `{report['signal_final_equity_diff']}`",
+            f"- Intrabar final equity diff: `{report['intrabar_final_equity_diff']}`",
+            "",
+            "This benchmark measures facade/optimizer overhead, not strategy quality.",
+        ]
+    ) + "\n"
+
+
+def _optimizer_overhead(trials: int) -> float:
+    evaluator = GenericEndpointEvaluator(
+        build_run_inputs=lambda params: {"value": float(params["x"])},
+        run_func=lambda value: value,
+        objective_builder=lambda result, params: ObjectiveResult.scalar(float(result), metrics={"score": float(result)}),
+    )
+    optimizer = OptunaOptimizer(
+        evaluator=evaluator,
+        config=OptimizationConfig(
+            study_name=f"phase32c_overhead_{time.time_ns()}",
+            n_trials=int(trials),
+            seed=42,
+            show_progress_bar=False,
+            duplicate_policy="allow",
+        ),
+        sampler_config=SamplerConfig(name="random"),
+    )
+    start = time.perf_counter()
+    optimizer.optimize(param_ranges={"x": (0.0, 1.0)})
+    return time.perf_counter() - start
+
+
+def _signal_replay_benchmark(df: pd.DataFrame, loops: int):
+    endpoint = QuantBTEndpoint.signal_notional(
+        backend="native_vectorized",
+        initial_capital=20_000.0,
+        leverage=5.0,
+        alloc_per_trade=1_000.0,
+        fee_rate=0.0,
+        use_funding=False,
+    )
+    signal = pd.Series(np.where(df["close"].diff().fillna(0.0) > 0.0, 1.0, 0.0), index=df.index)
+    normal = endpoint.backtest(data=df, signal=signal, symbols=["BTC"])
+    prepared = endpoint.prepare_service_context(data=df, symbols=["BTC"])
+    prepared_result = prepared.backtest(signal=signal)
+    diff = abs(float(normal.equity.iloc[-1]) - float(prepared_result.equity.iloc[-1]))
+
+    start = time.perf_counter()
+    for _ in range(int(loops)):
+        endpoint.backtest(data=df, signal=signal, symbols=["BTC"])
+    normal_seconds = time.perf_counter() - start
+
+    evaluator = PreparedSignalEvaluator(
+        prepared_context=prepared,
+        strategy_func=lambda params: signal,
+        objective_builder=lambda result, params: ObjectiveResult.scalar(float(result.equity.iloc[-1])),
+    )
+    start = time.perf_counter()
+    for _ in range(int(loops)):
+        evaluator.evaluate({})
+    prepared_seconds = time.perf_counter() - start
+    return normal_seconds, prepared_seconds, diff
+
+
+def _intrabar_compile_benchmark(df: pd.DataFrame):
+    endpoint = QuantBTEndpoint.intrabar_bracket(
+        initial_capital=20_000.0,
+        leverage=5.0,
+        fee_rate=0.0,
+        slippage_bps=0.0,
+        use_funding=False,
+        report_level="minimal",
+    )
+    runner = endpoint.prepare_intrabar(data=df, symbols=["BTC"])
+    entry = np.zeros(len(df))
+    entry[0] = 1.0
+    intent = IntrabarIntentTape.from_arrays(entry_side=entry, entry_size=np.abs(entry))
+
+    start = time.perf_counter()
+    first = runner.run(intent, report_level="minimal")
+    first_seconds = time.perf_counter() - start
+    start = time.perf_counter()
+    warm = runner.run(intent, report_level="minimal")
+    warm_seconds = time.perf_counter() - start
+    diff = abs(float(first.equity.iloc[-1]) - float(warm.equity.iloc[-1]))
+    return first_seconds, warm_seconds, diff
+
+
+def _frame(rows: int) -> pd.DataFrame:
+    idx = pd.date_range("2024-01-01", periods=int(rows), freq="1h", tz="UTC")
+    x = np.linspace(0.0, 16.0, len(idx))
+    close = 100.0 + np.sin(x) * 2.0 + np.arange(len(idx)) * 0.01
+    return pd.DataFrame(
+        {
+            "open": close,
+            "high": close * 1.01,
+            "low": close * 0.99,
+            "close": close,
+            "volume": 1_000.0,
+        },
+        index=idx,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--rows", type=int, default=360)
+    parser.add_argument("--trials", type=int, default=24)
+    parser.add_argument("--loops", type=int, default=24)
+    parser.add_argument("--json", type=Path, default=PACKAGE_DIR / "benchmarks" / "results" / "optimization_overhead.json")
+    parser.add_argument("--markdown", type=Path, default=PACKAGE_DIR / "benchmarks" / "results" / "optimization_overhead.md")
+    args = parser.parse_args()
+    report = run_benchmark(rows=args.rows, trials=args.trials, loops=args.loops)
+    args.json.parent.mkdir(parents=True, exist_ok=True)
+    args.json.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n")
+    args.markdown.write_text(make_markdown(report))
+    print(json.dumps(report, indent=2, sort_keys=True))
+    return 0 if report["status"] == "pass" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

quantbt/benchmarks/run_options_engine.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""Phase 10 options-engine benchmark and parity guard."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+import tracemalloc
+from pathlib import Path
+from typing import Dict, Sequence
+
+import numpy as np
+import pandas as pd
+
+PACKAGE_DIR = Path(__file__).resolve().parents[1]
+PROJECT_DIR = PACKAGE_DIR.parent
+if str(PROJECT_DIR) not in sys.path:
+    sys.path.insert(0, str(PROJECT_DIR))
+
+from quantbt import (  # noqa: E402
+    ExerciseStyle,
+    NativeOptionBackend,
+    NativeOptionConfig,
+    OptionInstrumentRegistry,
+    OptionInstrumentSpec,
+    OptionKind,
+    OptionPackageIntent,
+    OptionPackageLeg,
+    OptionPreparedRunCache,
+    OrderSide,
+    PremiumConvention,
+    SettlementStyle,
+)
+
+
+def run_benchmark(*, snapshots: int, contracts: int, packages: int, repeats: int, seed: int) -> Dict:
+    rng = np.random.default_rng(seed)
+    registry = _registry(contracts)
+    chain = _chain(registry, snapshots=snapshots, rng=rng)
+    package_list = _packages(registry, chain, packages=packages)
+    config = NativeOptionConfig(initial_balances={"USD": 100_000.0}, reporting_currency="USD", random_seed=seed)
+    backend = NativeOptionBackend(config)
+
+    uncached = backend.run(chain=chain, instruments=registry, packages=package_list)
+    cache = OptionPreparedRunCache.from_chain(chain, registry)
+    cached = backend.run(chain=chain, instruments=registry, packages=package_list, prepared_cache=cache)
+    parity = _parity(uncached, cached)
+
+    uncached_seconds = _timeit(lambda: backend.run(chain=chain, instruments=registry, packages=package_list), repeats)
+    cached_seconds = _timeit(lambda: backend.run(chain=chain, instruments=registry, packages=package_list, prepared_cache=cache), repeats)
+    peak_mb = _peak_memory_mb(lambda: backend.run(chain=chain, instruments=registry, packages=package_list, prepared_cache=cache))
+    return {
+        "phase": "options_phase10",
+        "status": "pass" if parity["passed"] else "fail",
+        "seed": int(seed),
+        "snapshots": int(snapshots),
+        "contracts": int(contracts),
+        "quotes": int(len(chain)),
+        "packages": int(len(package_list)),
+        "fills": int(len(cached.fills_report)),
+        "hedges": 0,
+        "memory_peak_mb": float(peak_mb),
+        "uncached_seconds": float(uncached_seconds),
+        "cached_seconds": float(cached_seconds),
+        "cache_speedup": float(uncached_seconds / cached_seconds) if cached_seconds > 0.0 else 0.0,
+        "package_cache_size": int(cache.package_cache_size),
+        "parity": parity,
+        "run_manifest": cached.run_manifest,
+        "cython_cpp_recommendation": (
+            "not_recommended_yet: Phase 10 benchmark still targets pandas/tape/package facade and cache reuse; "
+            "collect pure-kernel profile evidence before Cython/C++."
+        ),
+    }
+
+
+def make_markdown(report: Dict) -> str:
+    lines = [
+        "# Options Engine Phase 10 Benchmark",
+        "",
+        f"Status: **{report['status']}**",
+        "",
+        "| metric | value |",
+        "| --- | ---: |",
+        f"| snapshots | `{report['snapshots']}` |",
+        f"| contracts | `{report['contracts']}` |",
+        f"| quotes | `{report['quotes']}` |",
+        f"| packages | `{report['packages']}` |",
+        f"| fills | `{report['fills']}` |",
+        f"| hedges | `{report['hedges']}` |",
+        f"| peak memory MB | `{report['memory_peak_mb']:.3f}` |",
+        f"| uncached seconds | `{report['uncached_seconds']:.6f}` |",
+        f"| cached seconds | `{report['cached_seconds']:.6f}` |",
+        f"| cache speedup | `{report['cache_speedup']:.3f}x` |",
+        f"| package cache size | `{report['package_cache_size']}` |",
+        "",
+        "## Parity Guard",
+        "",
+        f"- Passed: `{report['parity']['passed']}`",
+        f"- Final equity abs diff: `{report['parity']['final_equity_abs_diff']:.12f}`",
+        f"- Position max abs diff: `{report['parity']['position_max_abs_diff']:.12f}`",
+        f"- Fills equal: `{report['parity']['fills_equal']}`",
+        "",
+        "## Manifest",
+        "",
+        f"- Data hash: `{report['run_manifest'].get('data_hash')}`",
+        f"- Margin model: `{report['run_manifest'].get('margin_model')}`",
+        f"- Pricing model: `{report['run_manifest'].get('pricing_model')}`",
+        f"- Fidelity: `{report['run_manifest'].get('fidelity_manifest')}`",
+        "",
+        "## Cython / C++ Decision",
+        "",
+        report["cython_cpp_recommendation"],
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _registry(contracts: int) -> OptionInstrumentRegistry:
+    expiry = int(pd.Timestamp("2026-03-01 08:00:00", tz="UTC").value)
+    specs = []
+    for i in range(contracts):
+        strike = 80_000.0 + 1_000.0 * i
+        kind = OptionKind.CALL if i % 2 == 0 else OptionKind.PUT
+        specs.append(
+            OptionInstrumentSpec(
+                symbol=f"BTC-O{i:04d}.TEST",
+                venue="test",
+                underlying_id="BTC-PERP.TEST",
+                underlying_index_id="BTC-INDEX.TEST",
+                option_kind=kind,
+                exercise_style=ExerciseStyle.EUROPEAN,
+                premium_convention=PremiumConvention.LINEAR_QUOTE,
+                settlement_style=SettlementStyle.CASH,
+                strike=strike,
+                expiry_ns=expiry,
+                settlement_currency="USD",
+                premium_currency="USD",
+                quote_currency="USD",
+                multiplier=1.0,
+                contract_size=1.0,
+                qty_step=1.0,
+                tick_size=0.01,
+                convention_version="phase10_linear_benchmark_v1",
+            )
+        )
+    return OptionInstrumentRegistry.from_iterable(specs)
+
+
+def _chain(registry: OptionInstrumentRegistry, *, snapshots: int, rng) -> pd.DataFrame:
+    start = pd.Timestamp("2026-01-01 00:00:00", tz="UTC")
+    rows = []
+    for t in range(snapshots):
+        ts = int((start + pd.Timedelta(minutes=15 * t)).value)
+        index_price = 100_000.0 + 100.0 * np.sin(t / 10.0)
+        for code, spec in enumerate(registry.instruments):
+            intrinsic = max(index_price - spec.strike, 0.0) if spec.option_kind is OptionKind.CALL else max(spec.strike - index_price, 0.0)
+            time_value = 500.0 + 5.0 * code + float(rng.normal(0.0, 1.0))
+            mark = max(intrinsic + time_value, 1.0)
+            rows.append(
+                {
+                    "timestamp_ns": ts,
+                    "instrument_id": spec.symbol,
+                    "venue": "TEST",
+                    "underlying_id": spec.underlying_id,
+                    "expiry_ns": spec.expiry_ns,
+                    "strike": spec.strike,
+                    "option_kind": spec.option_kind.value,
+                    "bid_price": mark * 0.995,
+                    "bid_size": 50.0,
+                    "ask_price": mark * 1.005,
+                    "ask_size": 50.0,
+                    "mark_price": mark,
+                    "last_price": mark,
+                    "index_price": index_price,
+                    "forward_price": index_price,
+                    "mark_iv": 0.6,
+                    "bid_iv": 0.59,
+                    "ask_iv": 0.61,
+                    "delta": 0.5 if spec.option_kind is OptionKind.CALL else -0.5,
+                    "gamma": 0.0001,
+                    "vega": 100.0,
+                    "theta": -10.0,
+                    "open_interest": 1000.0,
+                    "volume": 100.0,
+                    "quote_currency": "USD",
+                    "settlement_currency": "USD",
+                    "sequence_id": code,
+                    "source_latency_ns": 1_000_000,
+                }
+            )
+    return pd.DataFrame(rows)
+
+
+def _packages(registry: OptionInstrumentRegistry, chain: pd.DataFrame, *, packages: int) -> Sequence[OptionPackageIntent]:
+    timestamps = sorted(chain["timestamp_ns"].unique())
+    symbols = list(registry.symbols)
+    out = []
+    for i in range(packages):
+        ts = int(timestamps[i % len(timestamps)])
+        symbol = symbols[i % len(symbols)]
+        side = OrderSide.BUY if i % 2 == 0 else OrderSide.SELL
+        out.append(
+            OptionPackageIntent(
+                timestamp_ns=ts,
+                package_id=f"bench-{i:05d}",
+                legs=(OptionPackageLeg(symbol, side, 1.0),),
+                quantity=1.0,
+            )
+        )
+    return tuple(out)
+
+
+def _parity(a, b) -> Dict:
+    equity_diff = float(abs(a.equity.iloc[-1] - b.equity.iloc[-1]))
+    position_diff = float(np.max(np.abs(a.positions.to_numpy() - b.positions.to_numpy())))
+    fills_equal = bool(a.fills_report.equals(b.fills_report))
+    return {
+        "passed": bool(equity_diff <= 1e-9 and position_diff <= 1e-12 and fills_equal),
+        "final_equity_abs_diff": equity_diff,
+        "position_max_abs_diff": position_diff,
+        "fills_equal": fills_equal,
+    }
+
+
+def _timeit(fn, repeats: int) -> float:
+    durations = []
+    for _ in range(max(1, repeats)):
+        start = time.perf_counter()
+        fn()
+        durations.append(time.perf_counter() - start)
+    return float(min(durations))
+
+
+def _peak_memory_mb(fn) -> float:
+    tracemalloc.start()
+    try:
+        fn()
+        _, peak = tracemalloc.get_traced_memory()
+    finally:
+        tracemalloc.stop()
+    return peak / 1_000_000.0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--snapshots", type=int, default=96)
+    parser.add_argument("--contracts", type=int, default=48)
+    parser.add_argument("--packages", type=int, default=96)
+    parser.add_argument("--repeats", type=int, default=3)
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--output-json", type=Path, default=PACKAGE_DIR / "benchmarks" / "options_phase10_baseline.json")
+    parser.add_argument("--output-md", type=Path, default=PACKAGE_DIR / "benchmarks" / "options_phase10_baseline.md")
+    args = parser.parse_args()
+
+    report = run_benchmark(
+        snapshots=args.snapshots,
+        contracts=args.contracts,
+        packages=args.packages,
+        repeats=args.repeats,
+        seed=args.seed,
+    )
+    args.output_json.write_text(json.dumps(report, indent=2, default=str) + "\n", encoding="utf-8")
+    args.output_md.write_text(make_markdown(report), encoding="utf-8")
+    print(json.dumps({"status": report["status"], "cache_speedup": report["cache_speedup"]}, indent=2))
+    if report["status"] != "pass":
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

quantbt/benchmarks/run_pct_equity_nautilus_smoke.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""Smoke compare native legacy `%_equity` and Nautilus `%_equity` validation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Dict, Optional
+
+import numpy as np
+import pandas as pd
+
+PACKAGE_DIR = Path(__file__).resolve().parents[1]
+PROJECT_DIR = PACKAGE_DIR.parent
+if str(PROJECT_DIR) not in sys.path:
+    sys.path.insert(0, str(PROJECT_DIR))
+
+from quantbt import QuantBTEndpoint  # noqa: E402
+from quantbt.adapters.nautilus import NautilusBackendConfig  # noqa: E402
+
+
+def run_smoke(rows: int = 300) -> Dict:
+    data = _synthetic_eth_data(rows=rows)
+    scenarios = [
+        {
+            "name": "aligned_fee_no_funding_no_slippage",
+            "native_fee_round_trip": 0.0008,
+            "native_use_funding": False,
+            "native_slippage": 0.0,
+            "nautilus_fee_rate": 0.0004,
+            "nautilus_use_funding": False,
+            "nautilus_slippage": 0.0,
+            "note": "Native one-way fee approximates ETH taker fee; custom Nautilus fee_rate is not applied.",
+        },
+        {
+            "name": "user_like_mismatch",
+            "native_fee_round_trip": 0.0005,
+            "native_use_funding": True,
+            "native_slippage": 0.0002,
+            "nautilus_fee_rate": 0.0005,
+            "nautilus_use_funding": False,
+            "nautilus_slippage": 0.0002,
+            "note": "Matches the observed notebook-style mismatch: fee convention, funding, and slippage differ.",
+        },
+    ]
+    results = []
+    for scenario in scenarios:
+        results.append(_run_scenario(data, scenario))
+    return {
+        "status": "pass",
+        "rows": int(rows),
+        "symbol": "ETHUSDT-PERP.BINANCE",
+        "scenarios": results,
+        "conclusion": _conclusion(results),
+    }
+
+
+def make_markdown(report: Dict) -> str:
+    lines = [
+        "# `%_equity` Native vs Nautilus Smoke",
+        "",
+        f"Status: **{report['status']}**",
+        f"Rows: `{report['rows']}`",
+        f"Symbol: `{report['symbol']}`",
+        "",
+    ]
+    for item in report["scenarios"]:
+        lines.extend(
+            [
+                f"## {item['name']}",
+                "",
+                f"- Native final equity: `{item['native']['final_equity']:.6f}`",
+                f"- Nautilus final equity: `{item['nautilus']['final_equity']:.6f}`",
+                f"- Final equity diff: `{item['final_equity_diff']:.6f}`",
+                f"- Native trades: `{item['native']['num_trades']}`",
+                f"- Nautilus trades: `{item['nautilus']['num_trades']}`",
+                f"- Signal transitions: `{item['diagnostic']['signal']['effective_transition_count']}`",
+                f"- Nautilus orders/fills: `{item['diagnostic']['orders']['orders_count']}` / `{item['diagnostic']['orders']['fills_count']}`",
+                f"- Checks: `{item['diagnostic']['checks']}`",
+                f"- Note: {item['note']}",
+                "",
+            ]
+        )
+    lines.extend(["## Conclusion", "", report["conclusion"], ""])
+    return "\n".join(lines)
+
+
+def _run_scenario(data: pd.DataFrame, scenario: Dict) -> Dict:
+    native = QuantBTEndpoint.pct_equity(
+        initial_capital=20_000,
+        leverage=5,
+        maintenance_ratio=0.005,
+        contract_size=1.0,
+        use_funding=bool(scenario["native_use_funding"]),
+        funding_rate=0.0001,
+        alloc_per_trade=0.5,
+        fee=float(scenario["native_fee_round_trip"]),
+        slippage=float(scenario["native_slippage"]),
+        use_pyramiding=False,
+    )
+    native_result = native.backtest(data=data, signal_col="pos_weight")
+
+    nautilus = QuantBTEndpoint.nautilus_validation(
+        initial_capital=20_000,
+        leverage=5,
+        alloc_per_trade=0.5,
+        hedge_type="%_equity",
+        fee_rate=float(scenario["nautilus_fee_rate"]),
+        use_funding=bool(scenario["nautilus_use_funding"]),
+        use_pyramiding=False,
+        slippage=float(scenario["nautilus_slippage"]),
+        nautilus_config=NautilusBackendConfig(
+            timeframe="1h",
+            starting_balance=20_000,
+            trade_notional=0.5,
+            close_positions_on_stop=False,
+            bypass_logging=True,
+            log_level="ERROR",
+        ),
+    )
+    nautilus_result = nautilus.simulate(
+        data=data,
+        signal_col="pos_weight",
+        symbols=["ETHUSDT-PERP.BINANCE"],
+        show_order_logs=False,
+    )
+    diagnostic = nautilus.nautilus_pct_equity_diagnostic(
+        data=data,
+        signal_col="pos_weight",
+        native_fee_round_trip=float(scenario["native_fee_round_trip"]),
+        native_use_funding=bool(scenario["native_use_funding"]),
+        native_slippage=float(scenario["native_slippage"]),
+    )
+    native_report = native_result.full_report()
+    nautilus_report = nautilus_result.full_report()
+    return {
+        "name": scenario["name"],
+        "note": scenario["note"],
+        "native": {
+            "final_equity": float(native_result.equity.iloc[-1]),
+            "total_return_pct": float(native_report["total_return_pct"]),
+            "num_trades": int(native_report["num_trades"]),
+        },
+        "nautilus": {
+            "final_equity": float(nautilus_result.equity.iloc[-1]),
+            "total_return_pct": float(nautilus_report["total_return_pct"]),
+            "num_trades": int(nautilus_report["num_trades"]),
+        },
+        "final_equity_diff": float(nautilus_result.equity.iloc[-1] - native_result.equity.iloc[-1]),
+        "diagnostic": _jsonable_diagnostic(diagnostic),
+    }
+
+
+def _synthetic_eth_data(rows: int) -> pd.DataFrame:
+    idx = pd.date_range("2024-01-01", periods=rows, freq="1h", tz="UTC")
+    grid = np.arange(rows)
+    close = pd.Series(2000 + 80 * np.sin(grid / 18) + 0.8 * grid + 20 * np.sin(grid / 5), index=idx)
+    signal = pd.Series(0.0, index=idx)
+    signal.iloc[10 : min(80, rows)] = 1.0
+    signal.iloc[min(110, rows) : min(170, rows)] = -1.0
+    signal.iloc[min(210, rows) : min(260, rows)] = 1.0
+    return pd.DataFrame(
+        {
+            "open": close,
+            "high": close * 1.002,
+            "low": close * 0.998,
+            "close": close,
+            "volume": 10_000.0,
+            "pos_weight": signal,
+        },
+        index=idx,
+    )
+
+
+def _conclusion(results) -> str:
+    aligned = next(item for item in results if item["name"] == "aligned_fee_no_funding_no_slippage")
+    mismatch = next(item for item in results if item["name"] == "user_like_mismatch")
+    return (
+        "When fee/funding/slippage semantics are aligned as closely as the current adapters allow, "
+        f"the synthetic final-equity gap is only `{aligned['final_equity_diff']:.6f}` USD and order/fill counts match. "
+        "The user-like setup intentionally differs: legacy `fee` is round-trip, Nautilus `fee_rate` is metadata today, "
+        "native funding/slippage are applied while Nautilus signal validation does not apply custom funding/slippage. "
+        f"That scenario shows a larger synthetic gap of `{mismatch['final_equity_diff']:.6f}` USD. "
+        "Large real-alpha gaps should be audited with the diagnostic helper first; if transition counts match, the next "
+        "production task is implementing custom fee/slippage/funding in the Nautilus signal adapter."
+    )
+
+
+def _jsonable_diagnostic(diagnostic: Dict) -> Dict:
+    out = dict(diagnostic)
+    out["signal"] = dict(out["signal"])
+    transition = out["signal"].pop("transition_report")
+    out["signal"]["transition_report_head"] = transition.head(20).to_dict(orient="records")
+    return out
+
+
+def _json_default(value):
+    if isinstance(value, (np.integer,)):
+        return int(value)
+    if isinstance(value, (np.floating,)):
+        return float(value)
+    if isinstance(value, (np.bool_,)):
+        return bool(value)
+    if isinstance(value, pd.Timestamp):
+        return value.isoformat()
+    raise TypeError(f"{type(value).__name__} is not JSON serializable")
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--rows", type=int, default=300)
+    parser.add_argument("--json-out", type=Path, default=PACKAGE_DIR / "benchmarks" / "pct_equity_nautilus_smoke.json")
+    parser.add_argument("--md-out", type=Path, default=PACKAGE_DIR / "benchmarks" / "pct_equity_nautilus_smoke.md")
+    args = parser.parse_args(argv)
+    report = run_smoke(rows=args.rows)
+    args.json_out.parent.mkdir(parents=True, exist_ok=True)
+    args.md_out.parent.mkdir(parents=True, exist_ok=True)
+    args.json_out.write_text(json.dumps(report, indent=2, default=_json_default) + "\n", encoding="utf-8")
+    args.md_out.write_text(make_markdown(report), encoding="utf-8")
+    print(make_markdown(report))
+    return 0 if report["status"] == "pass" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())