Qubx 4.0.0.dev1__tar.gz → 4.0.1__tar.gz

{qubx-4.0.0.dev1 → qubx-4.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: Qubx
-Version: 4.0.0.dev1
+Version: 4.0.1
 Summary: Qubx - Quantitative Trading Framework
 Project-URL: homepage, https://xlydian.com
 Project-URL: repository, https://github.com/xLydianSoftware/Qubx

{qubx-4.0.0.dev1 → qubx-4.0.1}/src/qubx/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '4.0.0.dev1'
-__version_tuple__ = version_tuple = (4, 0, 0, 'dev1')
+__version__ = version = '4.0.1'
+__version_tuple__ = version_tuple = (4, 0, 1)
 
 __commit_id__ = commit_id = None

{qubx-4.0.0.dev1 → qubx-4.0.1}/src/qubx/backtester/runner.py

@@ -612,7 +612,7 @@ class SimulationRunner:
             connectors=self._connectors,
             base_currencies=self.setup.base_currencies,
             time=time_provider,
-            cfg=AccountManagerConfig(),
+            cfg=AccountManagerConfig(maint_margin_rate=self.setup.maint_margin_rate),
             account_id=self.account_id,
             tcc=_exchange_to_tcc,
         )

{qubx-4.0.0.dev1 → qubx-4.0.1}/src/qubx/backtester/simulator.py

@@ -5,8 +5,9 @@ from joblib import delayed
 
 from qubx import QubxLogConfig, file_formatter, logger
 from qubx.backtester.utils import SetupTypes
-from qubx.core.basics import Instrument
+from qubx.core.basics import DEFAULT_MAINTENANCE_MARGIN, Instrument
 from qubx.core.exceptions import SimulationError
+from qubx.core.lookups import lookup
 from qubx.core.metrics import TradingSessionResult
 from qubx.data.storage import IStorage
 from qubx.emitters.inmemory import InMemoryMetricEmitter
@@ -45,6 +46,7 @@ def simulate(
     accurate_stop_orders_execution: bool = False,
     signal_timeframe: str = "1Min",
     enable_funding: bool = False,
+    maint_margin_rate: float = DEFAULT_MAINTENANCE_MARGIN,
     debug: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = "WARNING",
     show_latency_report: bool = False,
     portfolio_log_freq: str = "5Min",
@@ -76,6 +78,7 @@ def simulate(
         - accurate_stop_orders_execution (bool): If True, enables more accurate stop order execution simulation.
         - signal_timeframe (str): Timeframe for signals, default is "1Min".
         - enable_funding (bool): If True, enables funding rate simulation, default is False.
+        - maint_margin_rate (float): Maintenance margin as a fraction of notional for simulated positions (the account's `maint_margin_rate`).
         - debug (Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None): Logging level for debugging.
         - show_latency_report: If True, shows simulator's latency report.
         - portfolio_log_freq (str): Frequency for portfolio logging, default is "5Min".
@@ -125,6 +128,7 @@ def simulate(
         accurate_stop_orders_execution=accurate_stop_orders_execution,
         run_separate_instruments=run_separate_instruments,
         enable_funding=enable_funding,
+        maint_margin_rate=maint_margin_rate,
     )
     if not simulation_setups:
         logger.error(
@@ -259,10 +263,13 @@ def _run_setup(
         # Adjust the start date for the simulation to the onboard date of the instrument with the minimum onboard date.
         # TODO: this can be removed once we add some artificial data stream to move the simulation
         if setup.setup_type in [SetupTypes.SIGNAL, SetupTypes.SIGNAL_AND_TRACKER]:
+            # - a relisted symbol has data from its first listing on
             listed_dates = [
-                to_utc_naive(to_timestamp(instrument.listed_at))
+                to_utc_naive(to_timestamp(listing.listed_at))
                 for instrument in setup.instruments
-                if instrument.listed_at is not None
+                for listing in lookup.find_listings(instrument.exchange, instrument.symbol, instrument.market_type)
+                or [instrument]
+                if listing.listed_at is not None
             ]
             if listed_dates:
                 start = max(start, min(listed_dates))

{qubx-4.0.0.dev1 → qubx-4.0.1}/src/qubx/backtester/utils.py

@@ -8,6 +8,7 @@ import pandas as pd
 
 from qubx import logger
 from qubx.core.basics import (
+    DEFAULT_MAINTENANCE_MARGIN,
     STABLE_CURRENCIES,
     Balance,
     CtrlChannel,
@@ -114,6 +115,7 @@ class SimulationSetup:
     signal_timeframe: str = "1Min"
     accurate_stop_orders_execution: bool = False
     enable_funding: bool = False
+    maint_margin_rate: float = DEFAULT_MAINTENANCE_MARGIN
     base_currencies: dict[str, str] = field(init=False, default_factory=dict)
 
     def __post_init__(self) -> None:
@@ -405,6 +407,7 @@ def recognize_simulation_configuration(
     accurate_stop_orders_execution: bool,
     run_separate_instruments: bool = False,
     enable_funding: bool = False,
+    maint_margin_rate: float = DEFAULT_MAINTENANCE_MARGIN,
 ) -> list[SimulationSetup]:
     """
     Recognize and create setups based on the provided simulation configuration.
@@ -426,6 +429,7 @@ def recognize_simulation_configuration(
     - accurate_stop_orders_execution (bool): If True, enables more accurate stop order execution simulation.
     - run_separate_instruments (bool): If True, creates separate setups for each instrument.
     - enable_funding (bool): If True, enables funding rate simulation, default is False.
+    - maint_margin_rate (float): Maintenance margin as a fraction of notional for simulated positions.
 
     Returns:
     - list[SimulationSetup]: A list of SimulationSetup objects, each representing a
@@ -447,7 +451,7 @@ def recognize_simulation_configuration(
                 recognize_simulation_configuration(
                     _n + n, v, instruments, exchanges, capital, basic_currency, commissions, 
                     signal_timeframe, accurate_stop_orders_execution, run_separate_instruments,
-                    enable_funding
+                    enable_funding, maint_margin_rate
                 )
             )
 
@@ -468,14 +472,14 @@ def recognize_simulation_configuration(
             if run_separate_instruments:
                 # Create separate setups for each instrument
                 for instrument in setup_instruments:
-                    _s1 = c1[instrument.symbol] if isinstance(_s, pd.DataFrame) else _s
+                    _s1 = _s[instrument.symbol] if isinstance(_s, pd.DataFrame) else _s
                     r.append(
                         SimulationSetup(
                             _t, f"{name}/{instrument.symbol}", _s1, c1,   # type: ignore
                             [instrument],
                             exchanges, capital, basic_currency, commissions, 
                             signal_timeframe, accurate_stop_orders_execution,
-                            enable_funding
+                            enable_funding, maint_margin_rate
                         )
                     )
             else:
@@ -485,7 +489,7 @@ def recognize_simulation_configuration(
                         setup_instruments,
                         exchanges, capital, basic_currency, commissions, 
                         signal_timeframe, accurate_stop_orders_execution,
-                        enable_funding
+                        enable_funding, maint_margin_rate
                     )
                 )
         else:
@@ -495,7 +499,7 @@ def recognize_simulation_configuration(
                         # name + "/" + str(j), s, instruments, exchange, capital, basic_currency, commissions
                         name, s, instruments, exchanges, capital, basic_currency, commissions,  # type: ignore
                         signal_timeframe, accurate_stop_orders_execution, run_separate_instruments,
-                        enable_funding
+                        enable_funding, maint_margin_rate
                     )
                 )
 
@@ -509,7 +513,7 @@ def recognize_simulation_configuration(
                         f"{name}/{instrument.symbol}", configs, None, [instrument],
                         exchanges, capital, basic_currency, commissions, 
                         signal_timeframe, accurate_stop_orders_execution,
-                        enable_funding
+                        enable_funding, maint_margin_rate
                     )
                 )
         else:
@@ -519,7 +523,7 @@ def recognize_simulation_configuration(
                     name, configs, None, instruments,
                     exchanges, capital, basic_currency, commissions, 
                     signal_timeframe, accurate_stop_orders_execution,
-                    enable_funding
+                    enable_funding, maint_margin_rate
                 )
             )
 
@@ -538,7 +542,7 @@ def recognize_simulation_configuration(
                         f"{name}/{instrument.symbol}", _c1, None, [instrument],
                         exchanges, capital, basic_currency, commissions, 
                         signal_timeframe, accurate_stop_orders_execution,
-                        enable_funding
+                        enable_funding, maint_margin_rate
                     )
                 )
         else:
@@ -548,7 +552,7 @@ def recognize_simulation_configuration(
                     name, c1, None, setup_instruments,
                     exchanges, capital, basic_currency, commissions, 
                     signal_timeframe, accurate_stop_orders_execution,
-                    enable_funding
+                    enable_funding, maint_margin_rate
                 )
             )
 

{qubx-4.0.0.dev1 → qubx-4.0.1}/src/qubx/core/account_manager/state.py

@@ -489,11 +489,19 @@ class AccountState:
         # the framework hold references to it), never swapped for a new object.
         existing = self._positions.get(instrument)
         if existing is None:
-            position.maint_margin_rate = self.maint_margin_rate
-            self._positions[instrument] = position
+            self._adopt_position(instrument, position)
         else:
             existing.reset_by_position(position)
 
+    def _adopt_position(self, instrument: Instrument, position: Position) -> Position:
+        # - every held position margins at the account's rate, however it got here; a venue-reported
+        #   margin is kept, a framework one is recomputed now rather than on the next mark
+        position.maint_margin_rate = self.maint_margin_rate
+        if not position._maint_margin_external and position.is_open() and not np.isnan(position.last_update_price):
+            position._update_maint_margin()
+        self._positions[instrument] = position
+        return position
+
     def settle_position(self, instrument: Instrument) -> None:
         # Reconcile a delisted/gone position to flat WITHOUT trading: the exchange has
         # already cash-settled it, so we zero quantity/market value while preserving the
@@ -525,7 +533,7 @@ class AccountState:
         """
         existing = self._positions.get(snapshot.instrument)
         if existing is None:
-            self._positions[snapshot.instrument] = snapshot
+            self._adopt_position(snapshot.instrument, snapshot)
             logger.info(
                 f"[{self.exchange}] reconcile: materialized position <y>{snapshot.instrument}</y> from snapshot "
                 f"-> size=<g>{snapshot.quantity}</g> avg={snapshot.position_avg_price}"
@@ -663,9 +671,7 @@ class AccountState:
     def ensure_position(self, instrument: Instrument) -> Position:
         pos = self._positions.get(instrument)
         if pos is None:
-            pos = Position(instrument=instrument)
-            pos.maint_margin_rate = self.maint_margin_rate
-            self._positions[instrument] = pos
+            pos = self._adopt_position(instrument, Position(instrument=instrument))
         return pos
 
     def adjust_balance(self, currency: str, delta: float) -> None:

{qubx-4.0.0.dev1 → qubx-4.0.1}/src/qubx/core/basics.py

@@ -23,7 +23,7 @@ from qubx.core.utils import (
 )
 from qubx.utils.clock import start_clock_discipline, time_now
 from qubx.utils.misc import Stopwatch
-from qubx.utils.time import to_timedelta
+from qubx.utils.time import to_timedelta, to_utc_naive
 
 dt_64 = np.datetime64
 td_64 = np.timedelta64
@@ -408,7 +408,7 @@ class Instrument:
     _: KW_ONLY
     contract_size: float = 1.0  # quantity per contract: base units (linear) or quote units (inverse)
     inverse: bool = False
-    listing_id: str | None = None  # instrument-service listing id, stable through renames
+    listing_id: str | None = None  # instrument-service listing id; a new symbol is a new listing
     underlying: Underlying | None = None
     calendar: str | None = None  # when this listing trades: "24/7", a MIC ("XNAS") or None
     expiry: datetime | None = None
@@ -451,6 +451,13 @@ class Instrument:
         """What the listing is a contract on (NVDA.XNAS for a bStock, XAU for PAXG); `asset` when the underlying is unknown."""
         return self.underlying.code if self.underlying is not None else self.asset
 
+    def is_listed_at(self, time: datetime | str) -> bool:
+        """listed_at <= time < delisted_at, an unknown date leaving that side open."""
+        t = to_utc_naive(time)
+        return (self.listed_at is None or to_utc_naive(self.listed_at) <= t) and (
+            self.delisted_at is None or t < to_utc_naive(self.delisted_at)
+        )
+
     def is_futures(self) -> bool:
         return self.market_type in [MarketType.FUTURE, MarketType.SWAP]
 
@@ -2080,6 +2087,10 @@ class RestoredState:
 class InstrumentsLookup:
     def get_lookup(self) -> dict[str, Instrument]: ...
 
+    def get_listings(self) -> list[Instrument]:
+        """Every listing, including the earlier, delisted incarnations of relisted symbols that get_lookup() drops."""
+        return list(self.get_lookup().values())
+
     def find(
         self,
         exchange: str,
@@ -2118,6 +2129,10 @@ class InstrumentsLookup:
 
         return None
 
+    def find_listings(self, exchange: str, symbol: str, market_type: MarketType | None = None) -> list[Instrument]:
+        """Every listing a symbol has had, the current (find_symbol) one first."""
+        return [i for i in [self.find_symbol(exchange, symbol, market_type)] if i is not None]
+
     def find_instruments(
         self,
         exchange: str,
@@ -2128,29 +2143,23 @@ class InstrumentsLookup:
     ) -> list[Instrument]:
         """
         Find instruments by exchange, quote, market type and as of date.
-        If as_of is not None, then only instruments that are not delisted after as_of date will be returned.
+        If as_of is not None, only instruments listed at that time are returned, delisted predecessors
+        of relisted symbols included (see get_listings).
         - exchange: str - exchange name
         - base: str | None - base currency
         - quote: str | None - quote currency
         - market_type: MarketType | None - market type
         - as_of is a string in format YYYY-MM-DD or pd.Timestamp or None
         """
-        _limit_time = pd.Timestamp(as_of) if as_of else None
+        _limit_time = to_utc_naive(as_of) if as_of else None
         matched = [
             i
-            for i in self.get_lookup().values()
+            for i in (self.get_lookup().values() if _limit_time is None else self.get_listings())
             if i.exchange == exchange
             and (base is None or i.base == base or i.asset == base)
             and (quote is None or i.quote == quote)
             and (market_type is None or i.market_type == market_type)
-            and (
-                _limit_time is None
-                or (i.listed_at is None or pd.Timestamp(i.listed_at).tz_localize(None) <= _limit_time)
-            )
-            and (
-                _limit_time is None
-                or (i.delisted_at is None or pd.Timestamp(i.delisted_at).tz_localize(None) >= _limit_time)
-            )
+            and (_limit_time is None or i.is_listed_at(_limit_time))
         ]
         if base is not None:
             aliases = sorted({i.base for i in matched} - {base})