back-trader-python 1.4.0__py3-none-any.whl

backtrader/brokers/hft/queue.py

@@ -0,0 +1,238 @@
+"""Queue-position models for maker order fills in HFT simulation.
+
+Defines :class:`NoQueueModel` (and probabilistic variants like
+``ProbQueueModel``) that estimate how much volume sits ahead of a resting limit
+order and how it gets consumed by trades/depth updates, driving realistic maker
+fill timing in the tick matching engine.
+"""
+
+
+class NoQueueModel:
+    """No-op queue model: resting orders fill instantly on a matching trade."""
+
+    def estimate_queue_position(self, order, ob_snapshot):
+        """Return a fixed zero queue-ahead for the resting order."""
+        _ = (order, ob_snapshot)
+        return 0.0
+
+    def on_new_order(self, order, ob_snapshot):
+        """Initialize the order's queue state to a no-queue configuration."""
+        order._queue_ahead = self.estimate_queue_position(order, ob_snapshot)
+        order._queue_initial_ahead = float(getattr(order, "_queue_ahead", 0.0))
+        order._queue_trade_qty = 0.0
+        order._queue_fillable = 0.0
+
+    def update_on_trade(self, order, trade_event):
+        """Mark the order fully fillable up to the available trade volume."""
+        remaining = getattr(getattr(order, "executed", None), "remsize", None)
+        if remaining is None:
+            remaining = getattr(order, "size", 0.0)
+        if remaining is None:
+            remaining = 0.0
+        trade_volume = abs(getattr(trade_event, "volume", 0.0))
+        fillable = min(abs(float(remaining)), trade_volume)
+        order._queue_fillable = fillable
+        return fillable
+
+    def update_on_depth(self, order, prev_qty, new_qty):
+        """Clamp the queue-ahead to the latest depth at the order's price."""
+        _ = prev_qty
+        order._queue_ahead = min(
+            max(0.0, float(getattr(order, "_queue_ahead", 0.0))), float(new_qty)
+        )
+        order._queue_trade_qty = 0.0
+
+    def is_filled(self, order):
+        """Return True when the no-queue model has any fillable volume."""
+        return float(getattr(order, "_queue_fillable", 0.0)) > 0.0
+
+
+class ProbQueueModel:
+    """Probabilistic queue-position model for maker order fills.
+
+    Estimates the volume that sits ahead of a resting limit order based on the
+    displayed size at the order's price, then probabilistically consumes that
+    volume as trades and depth updates arrive. The ``power`` argument
+    parameterizes the front-vs-back-of-queue probability ratio (a value of 2
+    approximates the classical Cont/Stoikov-style weighting), and ``lot_size``
+    sets the discrete fill granularity.
+
+    Attributes:
+        power (float): Exponent used in the front/back probability ratio. A
+            higher value biases fills toward the back of the queue, making
+            position-dependent fill probability more pronounced.
+        lot_size (float): Default lot size used when the order does not expose
+            its own ``_queue_lot_size`` attribute, controlling the granularity
+            of partial fills.
+    """
+
+    def __init__(self, power: float = 2.0, lot_size: float = 1.0):
+        """Initialize the probabilistic queue model.
+
+        Args:
+            power: Exponent applied to the front/back-of-queue volumes when
+                computing the probability that an incoming aggressor
+                consumes a unit behind the resting order. Must be non-negative.
+            lot_size: Fallback lot size used by :meth:`is_filled` to round
+                fills to a discrete quantity. Must be strictly positive.
+        """
+        self.power = float(power)
+        self.lot_size = float(lot_size)
+
+    def estimate_queue_position(self, order, ob_snapshot):
+        """Estimate the volume sitting ahead of ``order`` in its price level.
+
+        Walks the appropriate side of the order book (``bids`` for buys,
+        ``asks`` for sells) and returns the displayed quantity at the order's
+        price level. If the order has no price or the price is not present in
+        the snapshot, returns ``0.0``.
+
+        Args:
+            order: The resting order being modeled. Must expose ``price`` and
+                an ``isbuy()`` method that returns ``True`` for buy orders.
+            ob_snapshot: Order book snapshot providing ``bids`` and ``asks``
+                as iterables of ``(price, quantity)`` tuples sorted with the
+                best price first.
+
+        Returns:
+            float: Quantity (in base asset units) ahead of the order at its
+            price level, or ``0.0`` when no price match is found.
+        """
+        price = getattr(order, "price", None)
+        if price is None:
+            return 0.0
+        levels = ob_snapshot.bids if order.isbuy() else ob_snapshot.asks
+        for level_price, level_qty in levels:
+            if level_price == price:
+                return float(level_qty)
+        return 0.0
+
+    def on_new_order(self, order, ob_snapshot):
+        """Initialize the queue-tracking state on a freshly placed order.
+
+        Records the initial queue-ahead (from
+        :meth:`estimate_queue_position`), captures it as the baseline
+        ``_queue_initial_ahead`` for later comparison, and resets the
+        running trade-volume accumulator.
+
+        Args:
+            order: The newly accepted resting order that will participate in
+                queue dynamics.
+            ob_snapshot: Order book snapshot taken at the moment the order
+                was accepted by the matching engine.
+        """
+        order._queue_ahead = self.estimate_queue_position(order, ob_snapshot)
+        order._queue_initial_ahead = float(getattr(order, "_queue_ahead", 0.0))
+        order._queue_trade_qty = 0.0
+
+    def _probability(self, front: float, back: float) -> float:
+        """Compute the probability that a consumed unit is behind this order.
+
+        Uses the front/back ratio raised to ``self.power`` so that a small
+        ``back`` (i.e. the order sits near the back of the queue) yields a
+        low probability and a small ``front`` yields a high probability.
+
+        Args:
+            front: Quantity sitting ahead of this order at its price level.
+            back: Quantity sitting behind this order at its price level.
+
+        Returns:
+            float: Probability in ``[0.0, 1.0]`` that the next consumed unit
+            passes behind the resting order. Returns ``1.0`` if both
+            quantities are zero.
+        """
+        front = max(0.0, float(front))
+        back = max(0.0, float(back))
+        denominator = back**self.power + front**self.power
+        if denominator <= 0.0:
+            return 1.0
+        return back**self.power / denominator
+
+    def update_on_trade(self, order, trade_event):
+        """Consume a trade event and update the order's queue-ahead.
+
+        Subtracts the absolute trade volume from the queue-ahead and
+        accumulates it into ``_queue_trade_qty`` so the subsequent depth
+        update can reconcile the displayed quantity against the volume
+        that was already attributed to trades.
+
+        Args:
+            order: The resting order being tracked. The method mutates
+                ``_queue_ahead``, ``_queue_trade_qty`` and ``_queue_fillable``
+                on the order in place.
+            trade_event: The trade event to consume. Must expose a
+                ``volume`` attribute (absolute trade size).
+
+        Returns:
+            float: The fillable volume computed via :meth:`is_filled` after
+            the trade has been applied (``0.0`` when nothing filled).
+        """
+        queue_ahead = float(getattr(order, "_queue_ahead", 0.0))
+        trade_qty = abs(float(getattr(trade_event, "volume", 0.0)))
+        if trade_qty <= 0.0:
+            order._queue_fillable = 0.0
+            return 0.0
+        queue_ahead -= trade_qty
+        order._queue_ahead = queue_ahead
+        order._queue_trade_qty = float(getattr(order, "_queue_trade_qty", 0.0)) + trade_qty
+        fillable = self.is_filled(order)
+        order._queue_fillable = fillable
+        return fillable
+
+    def update_on_depth(self, order, prev_qty, new_qty):
+        """Reconcile the order's queue-ahead against an updated depth value.
+
+        The order book manager reports the new total size at the order's
+        price level. The model first removes the volume already attributed
+        to trades (kept in ``_queue_trade_qty``) and then estimates the new
+        queue-ahead as a probabilistic blend of the previous front/back
+        split.
+
+        Args:
+            order: The resting order being tracked. The method mutates
+                ``_queue_ahead`` and ``_queue_trade_qty`` in place.
+            prev_qty: Displayed quantity at the order's price level before
+                the depth update.
+            new_qty: Displayed quantity at the order's price level after
+                the depth update.
+        """
+        change = float(prev_qty) - float(new_qty)
+        queue_ahead = float(getattr(order, "_queue_ahead", 0.0))
+        trade_qty = float(getattr(order, "_queue_trade_qty", 0.0))
+        change -= trade_qty
+        order._queue_trade_qty = 0.0
+        if change < 0.0:
+            order._queue_ahead = min(queue_ahead, float(new_qty))
+            return
+        front = queue_ahead
+        back = float(prev_qty) - front
+        probability = self._probability(front, back)
+        estimate = front - (1.0 - probability) * change + min(back - probability * change, 0.0)
+        order._queue_ahead = min(estimate, float(new_qty))
+
+    def is_filled(self, order):
+        """Compute the lot-rounded fillable volume for the order.
+
+        When the queue-ahead has gone non-positive, the order has been
+        fully consumed and the method returns the number of whole lots that
+        would have filled, rescaled to absolute volume. Otherwise returns
+        ``0.0``. The order's ``_queue_ahead`` is reset to zero when a
+        positive fill is produced.
+
+        Args:
+            order: The resting order being tracked. The method mutates
+                ``_queue_ahead`` when a positive fill is detected.
+
+        Returns:
+            float: Fillable volume rounded to whole lots (or ``0.0`` if the
+            order has not been fully consumed).
+        """
+        queue_ahead = float(getattr(order, "_queue_ahead", 0.0))
+        lot_size = abs(float(getattr(order, "_queue_lot_size", self.lot_size)))
+        if lot_size <= 0.0:
+            lot_size = 1.0
+        exec_lots = int(round((-queue_ahead) / lot_size))
+        if exec_lots > 0:
+            order._queue_ahead = 0.0
+            return exec_lots * lot_size
+        return 0.0

backtrader/brokers/hft/recorder.py

@@ -0,0 +1,88 @@
+"""Event recorder for HFT simulation diagnostics.
+
+Defines :class:`Recorder`, a small bounded-history collector of timestamped
+per-symbol events used to capture and replay the matching engine's activity.
+"""
+
+
+class Recorder:
+    """Bounded-history collector of timestamped per-symbol events.
+
+    The recorder is used by the HFT simulation stack to capture activity
+    produced by the matching engine (orders, trades, cancels, etc.) so that
+    it can be inspected or replayed later. Events are stored as plain
+    dictionaries and trimmed to a configurable maximum length to keep memory
+    usage predictable during long runs.
+
+    Attributes:
+        _maxlen: Optional maximum number of events to retain. ``None`` means
+            unbounded (events accumulate for the lifetime of the recorder).
+        _events: Internal list of recorded event dictionaries, in insertion
+            order. Each entry has the shape
+            ``{"timestamp": ..., "symbol": ..., "payload": {...}}``.
+    """
+
+    def __init__(self, maxlen=None):
+        """Initialize the recorder with an optional retention cap.
+
+        Args:
+            maxlen: Maximum number of events to keep in memory. When the
+                cap is exceeded, the oldest events are dropped. ``None``
+                disables trimming and lets events accumulate indefinitely.
+        """
+        self._maxlen = maxlen
+        self._events = []
+
+    def record(self, timestamp, symbol, payload):
+        """Append a new event to the recorder.
+
+        The ``payload`` mapping is shallow-copied to insulate the recorder
+        from later mutations made by the caller. When ``_maxlen`` is set and
+        the new length would exceed it, the oldest entries are trimmed so
+        that the internal list never grows past the cap.
+
+        Args:
+            timestamp: Event timestamp. Any value that the caller considers
+                a valid time identifier (typically a ``float`` epoch second,
+                but the recorder does not enforce a type).
+            symbol: Trading symbol (e.g. ``"BTCUSDT"``) associated with the
+                event. Used purely for indexing/inspection downstream.
+            payload: Mapping describing the event body. The mapping is
+                shallow-copied before being stored so that subsequent
+                modifications to the caller's object do not affect the
+                recorded history.
+
+        Returns:
+            dict: The recorded event dictionary as it was inserted (with
+            ``timestamp``, ``symbol`` and the copied ``payload``).
+        """
+        item = {
+            "timestamp": timestamp,
+            "symbol": symbol,
+            "payload": dict(payload),
+        }
+        self._events.append(item)
+        if self._maxlen is not None and len(self._events) > self._maxlen:
+            self._events = self._events[-self._maxlen :]
+        return item
+
+    def snapshot(self):
+        """Return a shallow copy of the recorded events.
+
+        The returned list is a fresh list, but the event dictionaries inside
+        it are the same objects stored in the recorder. Callers that need to
+        mutate individual events should copy them explicitly.
+
+        Returns:
+            list[dict]: Recorded events in insertion order (oldest first).
+        """
+        return list(self._events)
+
+    def clear(self):
+        """Drop every recorded event from the recorder.
+
+        After this call :meth:`snapshot` returns an empty list and the
+        recorder behaves as if it had just been constructed. The configured
+        ``_maxlen`` is preserved.
+        """
+        self._events = []

backtrader/brokers/hft/state.py

@@ -0,0 +1,138 @@
+"""Per-symbol trading state tracking for HFT simulation.
+
+Defines :class:`StateTracker`, which accumulates per-symbol statistics (fees,
+trade count, traded volume/value) updated on each fill, used for reporting and
+fee accounting in the tick broker.
+"""
+
+
+class StateTracker:
+    """Per-symbol trading-state accumulator for the HFT tick broker.
+
+    Maintains, for every symbol seen in a fill, a running count of
+    trades, traded volume and traded notional value, and the
+    cumulative fees paid. Snapshots are produced for either a single
+    symbol or every known symbol and are intended for reporting and
+    fee accounting.
+    """
+
+    def __init__(self):
+        """Initialize the empty per-symbol state dict."""
+        self._states = {}
+
+    def reset(self):
+        """Clear all per-symbol state. Useful between backtest runs."""
+        self._states = {}
+
+    def get_state(self, symbol):
+        """Return (and lazily create) the state dict for ``symbol``.
+
+        The state dict holds four counters: ``fee`` (cumulative
+        commission), ``num_trades`` (number of fills), ``trading_volume``
+        (absolute shares/contracts traded) and ``trading_value``
+        (absolute notional traded, ``volume * price``).
+
+        Args:
+            symbol: Symbol whose state to fetch or create.
+
+        Returns:
+            dict: The mutable per-symbol state dict.
+        """
+        if symbol not in self._states:
+            self._states[symbol] = {
+                "fee": 0.0,
+                "num_trades": 0,
+                "trading_volume": 0.0,
+                "trading_value": 0.0,
+            }
+        return self._states[symbol]
+
+    def on_fill(self, symbol, price, size, commission, role=None):
+        """Record a fill and return the updated per-symbol state.
+
+        Args:
+            symbol: Symbol the fill belongs to.
+            price: Fill price (per unit). Used to update
+                ``trading_value``.
+            size: Signed fill size. Only its absolute value is added
+                to ``trading_volume``.
+            commission: Commission charged for the fill, added to
+                ``fee``.
+            role: Optional :class:`backtrader.brokers.hft.exchange.FillRole`
+                tag. The tracker ignores it; it is accepted so the
+                call site can pass the role verbatim.
+
+        Returns:
+            dict: The updated per-symbol state dict.
+        """
+        _ = role
+        state = self.get_state(symbol)
+        state["num_trades"] += 1
+        state["trading_volume"] += abs(size)
+        state["trading_value"] += abs(size) * price
+        state["fee"] += commission
+        return state
+
+    def snapshot(self, symbol, position, balance, mid_price=None):
+        """Build a per-symbol snapshot dict combining state and P&L.
+
+        Args:
+            symbol: Symbol to snapshot.
+            position: Current net position (signed shares/contracts).
+            balance: Cash balance attributable to ``symbol`` (or
+                the full account, depending on accounting).
+            mid_price: Optional mid price used to mark the position
+                to market when computing ``equity``. When ``None``,
+                ``equity`` equals ``balance``.
+
+        Returns:
+            dict: ``{"position", "balance", "fee", "num_trades",
+            "trading_volume", "trading_value", "equity"}``.
+        """
+        state = self.get_state(symbol)
+        equity = balance
+        if mid_price is not None:
+            equity += position * mid_price
+        return {
+            "position": position,
+            "balance": balance,
+            "fee": state["fee"],
+            "num_trades": state["num_trades"],
+            "trading_volume": state["trading_volume"],
+            "trading_value": state["trading_value"],
+            "equity": equity,
+        }
+
+    def snapshot_all(self, positions, balance_by_symbol=None, mid_prices=None):
+        """Build per-symbol snapshots for every known symbol.
+
+        The symbol set is the union of the keys already in the
+        tracker and the keys in the ``positions`` mapping, so symbols
+        that have only ever carried a position (but no fills) are
+        still included. Missing positions/balances default to
+        ``0.0``; missing mid prices leave ``equity`` equal to the
+        balance.
+
+        Args:
+            positions: Mapping of symbol -> signed position.
+            balance_by_symbol: Optional mapping of symbol -> cash
+                balance. ``None`` or missing keys default to ``0.0``.
+            mid_prices: Optional mapping of symbol -> mid price for
+                mark-to-market. ``None`` or missing keys leave
+                ``equity`` equal to the balance.
+
+        Returns:
+            dict: ``{symbol: snapshot_dict}`` for every known symbol.
+        """
+        balance_by_symbol = balance_by_symbol or {}
+        mid_prices = mid_prices or {}
+        symbols = set(self._states) | set(positions)
+        result = {}
+        for symbol in symbols:
+            result[symbol] = self.snapshot(
+                symbol,
+                positions.get(symbol, 0.0),
+                balance_by_symbol.get(symbol, 0.0),
+                mid_prices.get(symbol),
+            )
+        return result

backtrader/brokers/impact_models.py

@@ -0,0 +1,118 @@
+"""Market impact models for order book depth matching.
+
+Provides pluggable market impact models used by TickBroker to
+estimate price impact of large orders consuming depth levels.
+
+Models:
+    - MarketImpactModel: Abstract base class
+    - LinearImpactModel: Linear price impact proportional to order size
+    - SquareRootImpactModel: Square-root impact model (more realistic)
+
+Example::
+
+    from backtrader.brokers.impact_models import SquareRootImpactModel
+    model = SquareRootImpactModel(coefficient=0.1)
+    impact = model.calculate_impact(price=50000, size=10.0)
+"""
+
+import math
+from abc import ABC, abstractmethod
+
+__all__ = ["MarketImpactModel", "LinearImpactModel", "SquareRootImpactModel"]
+
+
+class MarketImpactModel(ABC):
+    """Abstract base class for market impact models.
+
+    Market impact models estimate how a trade of a given size at a given
+    price level will move the market price, accounting for liquidity
+    consumption effects.
+    """
+
+    @abstractmethod
+    def calculate_impact(self, price, size) -> float:
+        """Calculate the absolute price impact.
+
+        Args:
+            price: Current price level.
+            size: Order size being filled.
+
+        Returns:
+            Absolute price impact (always >= 0).
+        """
+
+
+class LinearImpactModel(MarketImpactModel):
+    """Linear market impact: impact = coefficient * size * price.
+
+    Simple model where price impact scales linearly with order size.
+    Suitable for small orders relative to market depth.
+
+    Args:
+        coefficient: Impact coefficient (default: 0.001).
+            Higher values mean more price impact per unit size.
+    """
+
+    def __init__(self, coefficient=0.001):
+        """Initialize the linear impact model.
+
+        Args:
+            coefficient: Impact coefficient (default: 0.001).
+                Higher values mean more price impact per unit size.
+        """
+        self.coefficient = coefficient
+
+    def calculate_impact(self, price, size) -> float:
+        """Calculate linear price impact.
+
+        Returns:
+            coefficient * size * price
+        """
+        return self.coefficient * abs(size) * price
+
+
+class SquareRootImpactModel(MarketImpactModel):
+    """Square-root market impact: impact = coefficient * sqrt(size) * price.
+
+    More realistic model based on empirical research showing that price
+    impact scales with the square root of order size. Better suited for
+    large orders.
+
+    Args:
+        coefficient: Impact coefficient (default: 0.01).
+        daily_volume: Average daily volume for normalization (default: 0.0).
+            If > 0, size is normalized by daily volume before sqrt.
+    """
+
+    def __init__(self, coefficient=0.01, daily_volume=0.0):
+        """Initialize the square-root impact model.
+
+        Args:
+            coefficient: Impact coefficient (default: 0.01).
+            daily_volume: Average daily volume for normalization (default: 0.0).
+                If > 0, size is normalized by daily volume before sqrt.
+        """
+        self.coefficient = coefficient
+        self.daily_volume = daily_volume
+
+    def calculate_impact(self, price, size) -> float:
+        """Calculate square-root price impact.
+
+        If daily_volume > 0:
+            impact = coefficient * sqrt(size / daily_volume) * price
+        Else:
+            impact = coefficient * sqrt(size) * price
+
+        Returns:
+            Absolute price impact.
+        """
+        abs_size = abs(size)
+        if abs_size <= 0:
+            return 0.0
+
+        if self.daily_volume > 0:
+            normalized = abs_size / self.daily_volume
+        else:
+            normalized = abs_size
+
+        return self.coefficient * math.sqrt(normalized) * price