Qubx 1.1.2.dev14__tar.gz → 1.1.2.dev15__tar.gz

{qubx-1.1.2.dev14 → qubx-1.1.2.dev15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Qubx
-Version: 1.1.2.dev14
+Version: 1.1.2.dev15
 Summary: Qubx - Quantitative Trading Framework
 Project-URL: homepage, https://xlydian.com
 Project-URL: repository, https://github.com/xLydianSoftware/Qubx

{qubx-1.1.2.dev14 → qubx-1.1.2.dev15}/src/qubx/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.2.dev14'
-__version_tuple__ = version_tuple = (1, 1, 2, 'dev14')
+__version__ = version = '1.1.2.dev15'
+__version_tuple__ = version_tuple = (1, 1, 2, 'dev15')
 
 __commit_id__ = commit_id = None

{qubx-1.1.2.dev14 → qubx-1.1.2.dev15}/src/qubx/backtester/runner.py

@@ -131,6 +131,11 @@ class SimulationRunner:
         self._create_backtest_context()
         self._handle_ctx_subscriptions()
 
+    @property
+    def data_time_range(self) -> tuple[int, int] | None:
+        """Time range (ns) of historical data actually processed: (first, last), or None if no data arrived."""
+        return self._simulated_data_source.data_time_range
+
     def run(self, silent: bool = False, catch_keyboard_interrupt: bool = True, close_data_readers: bool = False):
         """
         Run the backtest from start to stop.

{qubx-1.1.2.dev14 → qubx-1.1.2.dev15}/src/qubx/backtester/simulated_data.py

@@ -846,9 +846,17 @@ class SimulatedDataIterator(Iterator):
         self._slicer = None
         self._slicing_iterator = None
         self._current_time = None
+        self._first_data_time: int | None = None
         self._start = None
         self._stop = None
 
+    @property
+    def data_time_range(self) -> tuple[int, int] | None:
+        """Time range (ns) of historical data actually processed: (first, last), or None if no data arrived."""
+        if self._first_data_time is not None and self._current_time is not None:
+            return (self._first_data_time, self._current_time)
+        return None
+
     @property
     def emulation_time_indent_seconds(self) -> float:
         """
@@ -1104,6 +1112,7 @@ class SimulatedDataIterator(Iterator):
         self._start = to_timestamp(start)
         self._stop = to_timestamp(stop)
         self._current_time = None
+        self._first_data_time = None
         self._slicer = IteratedDataStreamsSlicer()
         return self
 
@@ -1137,6 +1146,8 @@ class SimulatedDataIterator(Iterator):
                 if t < self._current_time:
                     is_historical = True
                 else:
+                    if self._first_data_time is None:
+                        self._first_data_time = t
                     self._current_time = t
 
                 return instr, data_type, v, is_historical

{qubx-1.1.2.dev14 → qubx-1.1.2.dev15}/src/qubx/core/exceptions.py

@@ -48,3 +48,7 @@ class SimulationError(Exception):
 
 class SimulationConfigError(Exception):
     pass
+
+
+class WarmupValidationError(Exception):
+    pass

{qubx-1.1.2.dev14 → qubx-1.1.2.dev15}/src/qubx/utils/runner/runner.py

@@ -2,6 +2,7 @@ import asyncio
 import socket
 import time
 from collections import defaultdict
+from dataclasses import dataclass
 from functools import reduce
 from pathlib import Path
 from threading import Thread
@@ -28,6 +29,7 @@ from qubx.core.basics import (
     TransactionCostsCalculator,
 )
 from qubx.core.context import StrategyContext
+from qubx.core.exceptions import WarmupValidationError
 from qubx.core.helpers import BasicScheduler
 from qubx.core.initializer import BasicStrategyInitializer
 from qubx.core.interfaces import (
@@ -879,6 +881,79 @@ def _apply_inverse_exchange_mapping(exchanges: list[str]) -> list[str]:
     return mapped_exchanges
 
 
+@dataclass(frozen=True)
+class WarmupResult:
+    """Captures the outcome of a warmup simulation for validation."""
+
+    requested_start_ns: int
+    requested_stop_ns: int
+    data_start_ns: int | None
+    data_stop_ns: int | None
+    initial_capital: float
+    final_capital: float
+
+    @property
+    def requested_duration_ns(self) -> int:
+        return self.requested_stop_ns - self.requested_start_ns
+
+    @property
+    def data_duration_ns(self) -> int:
+        if self.data_start_ns is not None and self.data_stop_ns is not None:
+            return self.data_stop_ns - self.data_start_ns
+        return 0
+
+    @property
+    def coverage_ratio(self) -> float:
+        if self.requested_duration_ns <= 0:
+            return 1.0
+        if self.data_start_ns is None:
+            return 0.0
+        return max(0.0, self.data_duration_ns / self.requested_duration_ns)
+
+    @property
+    def has_data(self) -> bool:
+        return self.data_start_ns is not None
+
+
+def _validate_warmup_result(result: WarmupResult, min_coverage_ratio: float = 0.5) -> None:
+    """Validate that warmup simulation produced usable state for live trading."""
+    if not result.has_data:
+        raise WarmupValidationError(
+            f"Warmup received no data at all. "
+            f"Requested window: {to_timedelta(result.requested_duration_ns, unit='ns')}. "
+            f"Check your warmup data source configuration."
+        )
+
+    if result.coverage_ratio < min_coverage_ratio:
+        data_start_gap = to_timedelta(result.data_start_ns - result.requested_start_ns, unit="ns")
+        data_end_gap = to_timedelta(result.requested_stop_ns - result.data_stop_ns, unit="ns")
+        raise WarmupValidationError(
+            f"Warmup data coverage insufficient: "
+            f"received {to_timedelta(result.data_duration_ns, unit='ns')} "
+            f"of requested {to_timedelta(result.requested_duration_ns, unit='ns')} "
+            f"({result.coverage_ratio:.1%} coverage, minimum required: {min_coverage_ratio:.0%}). "
+            f"Data started {data_start_gap} late, ended {data_end_gap} early. "
+            f"Check your warmup data source — it may have a max_history limit "
+            f"that is shorter than the warmup period."
+        )
+
+    if result.final_capital <= 0:
+        raise WarmupValidationError(
+            f"Warmup resulted in non-positive capital: {result.final_capital:.2f} "
+            f"(started with {result.initial_capital:.2f}). "
+            f"This typically means the warmup simulation traded with insufficient data, "
+            f"causing unrealistic losses. Check warmup data coverage and indicator warmup periods."
+        )
+
+    if result.initial_capital > 0 and result.final_capital < result.initial_capital * 0.5:
+        logger.warning(
+            f"<red>Warmup capital dropped significantly: "
+            f"{result.initial_capital:.2f} -> {result.final_capital:.2f} "
+            f"({(1 - result.final_capital / result.initial_capital):.1%} loss). "
+            f"Review warmup data coverage and strategy behavior during warmup.</red>"
+        )
+
+
 def _run_warmup(
     ctx: IStrategyContext,
     restored_state: RestoredState | None,
@@ -973,6 +1048,7 @@ def _run_warmup(
         initializer=ctx.initializer,
         warmup_mode=True,
     )
+    _initial_capital = ctx.account.get_total_capital()
 
     # - set the time provider to the simulated runner
     _live_time_provider = simulated_formatter.time_provider
@@ -995,6 +1071,17 @@ def _run_warmup(
 
     logger.info("<yellow>Warmup completed</yellow>")
 
+    data_range = warmup_runner.data_time_range
+    warmup_result = WarmupResult(
+        requested_start_ns=to_timestamp(warmup_start_time).value,
+        requested_stop_ns=to_timestamp(current_time).value,
+        data_start_ns=data_range[0] if data_range else None,
+        data_stop_ns=data_range[1] if data_range else None,
+        initial_capital=_initial_capital,
+        final_capital=warmup_runner.ctx.account.get_total_capital(),
+    )
+    _validate_warmup_result(warmup_result)
+
     # - reset the strategy ctx to point back to live context
     if hasattr(ctx.strategy, "ctx"):
         setattr(ctx.strategy, "ctx", ctx)