lobkit 0.2.1__py3-none-any.whl

lobkit/plotting.py

@@ -0,0 +1,147 @@
+"""Diagnostic plots (requires matplotlib)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from lobkit.analysis import RegressionResult
+
+C = ["#4C72B0", "#DD8452", "#55A868", "#C44E52"]
+
+
+def _save(fig, ax, path, title):
+    ax.set_title(title, fontweight="bold", loc="left")
+    ax.spines[["top", "right"]].set_visible(False)
+    fig.tight_layout()
+    fig.savefig(path, dpi=150, bbox_inches="tight")
+
+
+def plot_ofi_impact(buckets: pd.DataFrame, fit: RegressionResult, path: str, title: str, unit: str = "ticks"):
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(8, 5.5))
+    ax.scatter(buckets["ofi"], buckets["d_mid"], s=8, alpha=0.35, color=C[0], edgecolor="none")
+    x = np.linspace(buckets["ofi"].min(), buckets["ofi"].max(), 50)
+    ax.plot(x, fit.alpha + fit.beta * x, color=C[3], lw=2,
+            label=f"slope {fit.beta:.3f} {unit}/unit OFI,  R² = {fit.r2:.2f}")
+    ax.axhline(0, color="grey", lw=0.6), ax.axvline(0, color="grey", lw=0.6)
+    ax.set_xlabel("order-flow imbalance in bucket")
+    ax.set_ylabel(f"mid-price change ({unit})")
+    ax.legend(frameon=False)
+    _save(fig, ax, path, title)
+    plt.close(fig)
+
+
+def plot_imbalance(table: pd.DataFrame, path: str, title: str, min_n: int = 200):
+    import matplotlib.pyplot as plt
+
+    t = table[table["n"] >= min_n]
+    fig, ax = plt.subplots(figsize=(8, 5))
+    ax.plot(t["imbalance_mid"], t["p_up"], "o-", color=C[0], lw=2)
+    ax.axhline(0.5, color="grey", ls="--", lw=1)
+    ax.set_xlabel("queue imbalance  bid size / (bid size + ask size)")
+    ax.set_ylabel("P(next mid move is up)")
+    ax.set_ylim(0, 1)
+    _save(fig, ax, path, title)
+    plt.close(fig)
+
+
+def plot_impact_vs_depth(table: pd.DataFrame, fit: RegressionResult, path: str, title: str):
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(8, 5))
+    inv = 1 / table["mean_depth"]
+    ax.plot(inv, table["beta"], "o", ms=8, color=C[0])
+    x = np.linspace(0, inv.max() * 1.05, 20)
+    ax.plot(x, fit.alpha + fit.beta * x, "--", color=C[3], label=f"linear fit, R² = {fit.r2:.2f}")
+    ax.set_xlabel("1 / average depth at best quotes")
+    ax.set_ylabel("price impact coefficient β")
+    ax.legend(frameon=False)
+    _save(fig, ax, path, title)
+    plt.close(fig)
+
+
+def plot_as(results: dict, path: str, title: str):
+    import matplotlib.pyplot as plt
+
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(13, 4.8))
+    bins = np.linspace(min(r.pnl.min() for r in results.values()), max(r.pnl.max() for r in results.values()), 50)
+    for i, (name, r) in enumerate(results.items()):
+        label = f"{name}: mean {r.pnl.mean():.1f}, std {r.pnl.std(ddof=1):.1f}"
+        ax1.hist(r.pnl, bins=bins, alpha=0.6, color=C[i], label=label)
+        t = np.linspace(0, 1, r.inventory_paths.shape[1])
+        ax2.plot(t, r.inventory_paths[0], ["-", "--"][i], color=C[i], lw=1.4, label=name)
+    ax1.set_xlabel("terminal P&L"), ax1.set_ylabel("simulations"), ax1.legend(frameon=False)
+    ax2.set_xlabel("time / T"), ax2.set_ylabel("inventory (one sample path)"), ax2.legend(frameon=False)
+    ax2.spines[["top", "right"]].set_visible(False)
+    _save(fig, ax1, path, title)
+    plt.close(fig)
+
+
+def plot_multi_level(table: pd.DataFrame, path: str, title: str):
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(8, 5))
+    ax.plot(table["levels"], table["oos_r2"], "o-", color=C[0], lw=2, label="out-of-sample")
+    ax.plot(table["levels"], table["r2"], "s--", color=C[1], lw=1.2, label="in-sample")
+    ax.set_xlabel("OFI from the best m price levels")
+    ax.set_ylabel("R² of mid-price change")
+    ax.set_xticks(table["levels"])
+    ax.legend(frameon=False)
+    _save(fig, ax, path, title)
+    plt.close(fig)
+
+
+def plot_microprice(adjustment: np.ndarray, path: str, title: str, unit: str = "ticks"):
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(8, 5))
+    n_imb = adjustment.shape[1]
+    x = (np.arange(n_imb) + 0.5) / n_imb
+    for s, row in enumerate(adjustment):
+        ax.plot(x, row, "o-", color=C[s % len(C)], lw=2, label=f"spread {s + 1} tick{'s' if s else ''}")
+    ax.plot(x, (x - 0.5), ":", color="grey", label="naive microprice, spread 1 tick")
+    ax.axhline(0, color="grey", lw=0.6)
+    ax.set_xlabel("queue imbalance  bid size / (bid size + ask size)")
+    ax.set_ylabel(f"micro-price minus mid ({unit})")
+    ax.legend(frameon=False)
+    _save(fig, ax, path, title)
+    plt.close(fig)
+
+
+def plot_as_lob(table: pd.DataFrame, path: str, title: str):
+    """Per-fill edge by strategy and risk aversion: spread captured, lost to adverse selection, kept."""
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(9, 5))
+    labels = [f"γ={g}\n{s}" for g, s in zip(table["gamma"], table["strategy"], strict=True)]
+    x = np.arange(len(table))
+    ax.bar(x - 0.27, table["spread_capture"], 0.27, color=C[0], label="spread captured")
+    ax.bar(x, table["adverse_1s"], 0.27, color=C[1], label="adverse selection after 1 s")
+    ax.bar(x + 0.27, table["adverse_10s"], 0.27, color=C[3], label="adverse selection after 10 s")
+    ax.plot(x, table["spread_capture"] + table["adverse_10s"], "D", color="black", label="kept after 10 s")
+    ax.axhline(0, color="grey", lw=0.6)
+    ax.set_xticks(x, labels)
+    ax.set_ylabel("ticks per fill")
+    ax.legend(frameon=False)
+    _save(fig, ax, path, title)
+    plt.close(fig)
+
+
+def plot_lead_lag(tables: dict, path: str, title: str):
+    """tables: label -> lead_lag() output. A peak right of zero means the first venue leads."""
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(8, 5))
+    for i, (name, t) in enumerate(tables.items()):
+        ax.plot(t["lag_s"] * 1000, t["corr"], "-", color=C[i % len(C)], lw=2, label=name)
+        peak = t.loc[t["corr"].idxmax()]
+        ax.plot(peak["lag_s"] * 1000, peak["corr"], "o", color=C[i % len(C)])
+    ax.axvline(0, color="grey", lw=0.6)
+    ax.axhline(0, color="grey", lw=0.6)
+    ax.set_xlabel("lag (ms): correlation of venue A's return now with venue B's return this much later")
+    ax.set_ylabel("correlation of mid returns")
+    ax.legend(frameon=False)
+    _save(fig, ax, path, title)
+    plt.close(fig)

lobkit/recorder.py

@@ -0,0 +1,222 @@
+"""Record live spot market data from Binance and Bybit (requires `pip install -e '.[live]'`).
+
+Binance, three streams on one websocket:
+  <sym>@bookTicker      every best bid/ask change      -> l1.csv
+  <sym>@aggTrade        trades with aggressor side     -> trades.csv
+  <sym>@depth@100ms     L2 diffs, synchronised with a  -> depth.csv (top N levels, sampled;
+                        REST snapshot via              load with load_depth)
+                        BinanceDepthSync
+Bybit (optional, same session and clock, for cross-venue studies):
+  orderbook.1.<SYM>     best bid/ask                   -> bybit_l1.csv
+  publicTrade.<SYM>     trades with aggressor side     -> bybit_trades.csv
+
+Timestamps: `ts` is the local receive time for quotes on both venues, so the
+two venues share one clock; trades carry the exchange time in `ts` and the
+local time in `ts_local`. A dropped connection is reopened automatically (and
+the Binance depth book resynchronised); the count is printed at the end.
+Binance may be unavailable in some jurisdictions; adjust WS_BASE/REST_BASE
+(e.g. to Binance.US endpoints) if needed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import csv
+import json
+import time
+from pathlib import Path
+
+import pandas as pd
+
+from lobkit.book import BinanceDepthSync, SequenceGap
+
+WS_BASE = "wss://stream.binance.com:9443"
+REST_BASE = "https://api.binance.com"
+BYBIT_WS = "wss://stream.bybit.com/v5/public/spot"
+
+L1_HEADER = ["ts", "update_id", "bid_px", "bid_sz", "ask_px", "ask_sz"]
+TRADES_HEADER = ["ts", "ts_local", "price", "qty", "side"]
+
+
+def _fetch_snapshot(symbol: str, limit: int = 1000) -> dict:
+    import requests
+
+    r = requests.get(f"{REST_BASE}/api/v3/depth", params={"symbol": symbol.upper(), "limit": limit}, timeout=10)
+    r.raise_for_status()
+    return r.json()
+
+
+def _writer(out: Path, name: str, header: list[str], files: list):
+    f = open(out / f"{name}.csv", "w", newline="")    # closed by record_binance
+    files.append(f)
+    w = csv.writer(f)
+    w.writerow(header)
+    return w
+
+
+async def record_binance(symbol: str = "btcusdt", seconds: int = 900, out_dir: str | Path = "data",
+                         depth_levels: int = 10, depth_every: float = 1.0, bybit: bool = False) -> Path:
+    """Record `seconds` of data into out_dir/<symbol>_<timestamp>/; bybit=True adds the Bybit streams."""
+    sym = symbol.lower()
+    out = Path(out_dir) / f"{sym}_{time.strftime('%Y%m%d_%H%M%S')}"
+    out.mkdir(parents=True, exist_ok=True)
+    t_end = time.time() + seconds
+    files: list = []
+    try:
+        jobs = [_binance(sym, t_end, out, depth_levels, depth_every, files)]
+        if bybit:
+            jobs.append(_bybit(sym.upper(), t_end, out, files))
+        for line in await asyncio.gather(*jobs):
+            print(line)
+    finally:
+        for f in files:
+            f.close()
+    print(f"recorded to {out}")
+    return out
+
+
+async def _recv(ws) -> tuple[dict, float]:
+    """Next message and its arrival time. The clock is read after recv() returns, never before:
+    a time taken before waiting would stamp each message with the previous one's arrival."""
+    raw = await asyncio.wait_for(ws.recv(), timeout=30)
+    return json.loads(raw), time.time()
+
+
+async def _reconnecting(name: str, url: str, t_end: float, session) -> int:
+    """Run session(ws) until t_end, reopening the connection if it drops. Returns the reconnect count."""
+    import websockets
+
+    reconnects = -1
+    while time.time() < t_end:
+        reconnects += 1
+        try:
+            async with websockets.connect(url, max_size=None, ping_interval=20) as ws:
+                await session(ws)
+        except (websockets.ConnectionClosed, asyncio.TimeoutError, OSError) as e:
+            print(f"{name}: connection lost ({e!r}); reconnecting")
+            await asyncio.sleep(1)
+    return max(reconnects, 0)
+
+
+async def _binance(sym: str, t_end: float, out: Path, depth_levels: int, depth_every: float, files: list) -> str:
+    l1 = _writer(out, "l1", L1_HEADER, files)
+    trades = _writer(out, "trades", TRADES_HEADER, files)
+    depth = _writer(out, "depth", ["ts", "side", "level", "price", "qty"], files)
+    resyncs = 0
+
+    async def session(ws):
+        nonlocal resyncs
+        sync, snapshot_task, last_depth, retry_at = BinanceDepthSync(), None, 0.0, 0.0   # fresh book per connection
+        while time.time() < t_end:
+            msg, now = await _recv(ws)
+            stream, d = msg["stream"], msg["data"]
+            if not stream.endswith("@depth@100ms"):
+                name, row = _binance_row(stream, d, now)
+                (l1 if name == "l1" else trades).writerow(row)
+            else:
+                try:
+                    sync.on_event(d)
+                    if snapshot_task is not None and snapshot_task.done():
+                        task, snapshot_task = snapshot_task, None
+                        if task.exception() is not None:
+                            print(f"snapshot fetch failed: {task.exception()!r}; retrying in 5 s")
+                            retry_at = now + 5    # don't hammer the REST API (rate limits, IP bans)
+                        else:
+                            sync.on_snapshot(task.result())    # False = too old; refetched below
+                except SequenceGap:                # from the stream, or replaying the buffer
+                    resyncs += 1
+                    if snapshot_task is not None:
+                        snapshot_task.cancel()     # its snapshot belongs to the abandoned book
+                    sync, snapshot_task = BinanceDepthSync(), None
+                    sync.on_event(d)
+                if not sync.synced and snapshot_task is None and now >= retry_at:
+                    snapshot_task = asyncio.create_task(asyncio.to_thread(_fetch_snapshot, sym))
+                if sync.synced and now - last_depth >= depth_every:
+                    last_depth = now
+                    for side in ("bid", "ask"):
+                        for lvl, (p, q) in enumerate(sync.book.levels(side, depth_levels)):
+                            depth.writerow([now, side, lvl, p, q])
+
+    url = f"{WS_BASE}/stream?streams={sym}@bookTicker/{sym}@aggTrade/{sym}@depth@100ms"
+    reconnects = await _reconnecting("binance", url, t_end, session)
+    return f"binance: {resyncs} depth resyncs, {reconnects} reconnects"
+
+
+async def _bybit(sym: str, t_end: float, out: Path, files: list) -> str:
+    l1 = _writer(out, "bybit_l1", L1_HEADER, files)
+    trades = _writer(out, "bybit_trades", TRADES_HEADER, files)
+
+    async def session(ws):
+        await ws.send(json.dumps({"op": "subscribe", "args": [f"orderbook.1.{sym}", f"publicTrade.{sym}"]}))
+        book = {"bid": None, "ask": None}                  # fresh best quotes per connection
+        last_ping = time.time()
+        while time.time() < t_end:
+            if time.time() - last_ping > 20:               # Bybit drops connections without app-level pings
+                await ws.send(json.dumps({"op": "ping"}))
+                last_ping = time.time()
+            msg, now = await _recv(ws)
+            for name, row in _bybit_rows(msg, book, now):
+                (l1 if name == "l1" else trades).writerow(row)
+
+    reconnects = await _reconnecting("bybit", BYBIT_WS, t_end, session)
+    return f"bybit: {reconnects} reconnects"
+
+
+def _binance_row(stream: str, d: dict, now: float) -> tuple[str, list]:
+    """("l1" | "trades", csv row) for a bookTicker or aggTrade message."""
+    if stream.endswith("@bookTicker"):
+        return "l1", [now, d["u"], d["b"], d["B"], d["a"], d["A"]]
+    return "trades", [d["T"] / 1000, now, d["p"], d["q"], -1 if d["m"] else 1]    # m: buyer is maker
+
+
+def _bybit_rows(msg: dict, book: dict, now: float) -> list[tuple[str, list]]:
+    """CSV rows for one Bybit message; book holds the current best bid/ask and is updated.
+
+    A snapshot replaces both sides (an empty side means no quote); a delta only
+    replaces the sides it carries. No L1 row is written while a side is missing.
+    """
+    topic = msg.get("topic", "")
+    if topic.startswith("orderbook"):
+        d = msg["data"]
+        for side, key in (("bid", "b"), ("ask", "a")):
+            if d[key] or msg.get("type") == "snapshot":
+                top = d[key][0] if d[key] else None
+                book[side] = top if top and float(top[1]) > 0 else None     # size 0 = level deleted
+        bid, ask = book["bid"], book["ask"]
+        return [("l1", [now, d["u"], bid[0], bid[1], ask[0], ask[1]])] if bid and ask else []
+    if topic.startswith("publicTrade"):
+        return [("trades", [tr["T"] / 1000, now, tr["p"], tr["v"], 1 if tr["S"] == "Buy" else -1])
+                for tr in msg["data"]]                                  # S: taker side
+    if msg.get("success") is False:
+        raise RuntimeError(f"bybit subscription failed: {msg}")
+    return []                                                           # pong, subscription ack
+
+
+def load_recording(path: str | Path, venue: str = "binance") -> tuple[pd.DataFrame, pd.DataFrame]:
+    """Return (quotes, trades) in lobkit's standard format for venue "binance" or "bybit".
+
+    Trades are stamped with their local receive time, the clock the quotes use:
+    the local clock can be off the exchange's by a second or more, which would
+    misalign trade and quote buckets.
+    """
+    prefix = {"binance": "", "bybit": "bybit_"}[venue]
+    path = Path(path)
+    quotes = pd.read_csv(path / f"{prefix}l1.csv").drop(columns="update_id")
+    trades = pd.read_csv(path / f"{prefix}trades.csv")
+    trades = trades.assign(ts=trades["ts_local"]).drop(columns="ts_local")
+    changed = quotes[["bid_px", "bid_sz", "ask_px", "ask_sz"]].diff().abs().sum(axis=1) > 0
+    changed.iloc[0] = True
+    return quotes[changed].reset_index(drop=True), trades
+
+
+def load_depth(path: str | Path) -> pd.DataFrame:
+    """Return the sampled L2 snapshots as a quotes frame with levels bid_px, ..., bid_px_2, ..."""
+    d = pd.read_csv(Path(path) / "depth.csv")
+    w = d.pivot(index="ts", columns=["side", "level"], values=["price", "qty"]).dropna()
+    out = pd.DataFrame({"ts": w.index.to_numpy()})
+    for lvl in sorted(d["level"].unique()):
+        sfx = "" if lvl == 0 else f"_{lvl + 1}"
+        for side in ("bid", "ask"):
+            out[f"{side}_px{sfx}"] = w[("price", side, lvl)].to_numpy()
+            out[f"{side}_sz{sfx}"] = w[("qty", side, lvl)].to_numpy()
+    return out

lobkit/simulator.py

@@ -0,0 +1,234 @@
+"""Zero-intelligence limit order book (Cont, Stoikov & Talreja 2010).
+
+Unit-size orders on a tick grid:
+  * limit buy (sell) orders arrive i ticks below the best ask (above the best
+    bid) at rate lambda(i), i = 1..K;
+  * market buy and sell orders arrive at rate mu each;
+  * each order resting i ticks from the opposite best is cancelled at rate
+    theta(i), so a queue of size Q is cancelled at rate theta(i) * Q.
+
+No agent has information, yet the model reproduces key empirical facts:
+order-flow imbalance moves prices linearly, and queue imbalance predicts the
+next mid-price move. That makes it a ground truth for testing analytics code.
+
+An optional quoter (e.g. a market maker) can rest one unit on each side. Its
+orders join the back of the queue, move up as orders ahead of them trade or
+cancel, and fill only when a market order reaches them.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+CST_LAMBDA = (1.85, 1.51, 1.09, 0.88, 0.77)   # orders/second at distance 1..5 ticks
+CST_THETA = (0.71, 0.81, 0.68, 0.56, 0.47)    # cancellation rate per resting order
+CST_MU = 0.94                                  # market orders/second per side
+
+
+@dataclass
+class SimulationResult:
+    quotes: pd.DataFrame   # ts, bid_px, bid_sz, ask_px, ask_sz (+ bid_px_2, ... if n_levels > 1) after every event
+    trades: pd.DataFrame   # ts, price, qty, side (+1 buyer-initiated)
+    fills: pd.DataFrame | None = None   # quoter's fills: ts, side (+1 quoter bought), price, mid before the fill
+
+
+# quoter(t, mid, inventory) -> (bid, ask) in price units, or None to stay out of the book
+Quoter = Callable[[float, float, int], "tuple[float, float] | None"]
+
+
+def simulate_lob(n_events: int = 300_000, lam=CST_LAMBDA, theta=CST_THETA, mu: float = CST_MU,
+                 initial_depth: int = 3, n_ticks: int = 20_000, tick: float = 1.0,
+                 seed: int | None = 0, n_levels: int = 1, quoter: Quoter | None = None,
+                 requote_every: float = 1.0, t_end: float | None = None) -> SimulationResult:
+    """Simulate up to n_events book events, stopping early at time t_end if given.
+
+    n_levels > 1 also records the 2nd..n-th best non-empty levels. A quoter is
+    asked for new quotes every requote_every seconds; its old orders are
+    cancelled first, and a quote that would cross the book is placed one tick
+    inside it instead (post-only). Without a quoter the random stream, and so
+    every result, is the same as before quoters existed.
+    """
+    rng = random.Random(seed)
+    K = len(lam)
+    bid = [0] * n_ticks
+    ask = [0] * n_ticks
+    centre = n_ticks // 2
+    for p in range(centre):
+        bid[p] = initial_depth
+    for p in range(centre + 1, n_ticks):
+        ask[p] = initial_depth
+    bb, ba = centre - 1, centre + 1
+    lam_total = sum(lam)
+
+    ts = np.empty(n_events)
+    rec = np.empty((n_events, 4 * n_levels), dtype=np.int64)
+    trades, fills = [], []
+    t = 0.0
+    my_b = my_a = -1                  # quoter's bid / ask level, -1 = none
+    ahead_b = ahead_a = inv = 0       # orders queued ahead of it, its inventory
+    next_quote = 0.0
+
+    for n in range(n_events):
+        if bb < K + 1 or ba > n_ticks - K - 2:
+            raise RuntimeError("price walked off the grid; increase n_ticks")
+        c_bid = [theta[i] * bid[ba - 1 - i] for i in range(K)]
+        c_ask = [theta[i] * ask[bb + 1 + i] for i in range(K)]
+        if 0 <= ba - 1 - my_b < K:                          # the quoter's own orders don't cancel randomly
+            c_bid[ba - 1 - my_b] -= theta[ba - 1 - my_b]
+        if 0 <= my_a - bb - 1 < K:
+            c_ask[my_a - bb - 1] -= theta[my_a - bb - 1]
+        sc_bid, sc_ask = sum(c_bid), sum(c_ask)
+        total = 2 * lam_total + 2 * mu + sc_bid + sc_ask
+        t += rng.expovariate(total)
+        if t_end is not None and t >= t_end:
+            break
+        u = rng.random() * total
+
+        if u < lam_total:                                   # limit buy
+            for i in range(K):
+                u -= lam[i]
+                if u < 0:
+                    p = ba - 1 - i
+                    bid[p] += 1
+                    bb = max(bb, p)
+                    break
+            else:
+                bid[ba - K] += 1
+        elif (u := u - lam_total) < lam_total:              # limit sell
+            for i in range(K):
+                u -= lam[i]
+                if u < 0:
+                    p = bb + 1 + i
+                    ask[p] += 1
+                    ba = min(ba, p)
+                    break
+            else:
+                ask[bb + K] += 1
+        elif (u := u - lam_total) < mu:                     # market buy
+            trades.append((t, ba * tick, 1.0, 1))
+            if ba == my_a:
+                if ahead_a == 0:
+                    fills.append((t, -1, ba * tick, (bb + ba) * tick / 2))
+                    inv, my_a = inv - 1, -1
+                else:
+                    ahead_a -= 1
+            ask[ba] -= 1
+            while ask[ba] == 0:
+                ba += 1
+        elif (u := u - mu) < mu:                            # market sell
+            trades.append((t, bb * tick, 1.0, -1))
+            if bb == my_b:
+                if ahead_b == 0:
+                    fills.append((t, 1, bb * tick, (bb + ba) * tick / 2))
+                    inv, my_b = inv + 1, -1
+                else:
+                    ahead_b -= 1
+            bid[bb] -= 1
+            while bid[bb] == 0:
+                bb -= 1
+        elif (u := u - mu) < sc_bid:                        # cancel a bid
+            for i in range(K):
+                u -= c_bid[i]
+                if u < 0:
+                    break
+            else:                                           # float rounding: never cancel an empty queue
+                i = max(j for j in range(K) if c_bid[j] > 0)
+            p = ba - 1 - i
+            if p == my_b and rng.random() * (bid[p] - 1) < ahead_b:   # the cancelled order was ahead of ours
+                ahead_b -= 1
+            bid[p] -= 1
+            while bid[bb] == 0:
+                bb -= 1
+        else:                                               # cancel an ask
+            u -= sc_bid
+            for i in range(K):
+                u -= c_ask[i]
+                if u < 0:
+                    break
+            else:
+                i = max(j for j in range(K) if c_ask[j] > 0)
+            p = bb + 1 + i
+            if p == my_a and rng.random() * (ask[p] - 1) < ahead_a:
+                ahead_a -= 1
+            ask[p] -= 1
+            while ask[ba] == 0:
+                ba += 1
+
+        if quoter is not None and t >= next_quote:
+            next_quote = t + requote_every
+            xb, xa = bb, ba                                 # best quotes of everyone else
+            if xb == my_b and bid[xb] == 1:
+                xb -= 1
+                while bid[xb] == 0:
+                    xb -= 1
+            if xa == my_a and ask[xa] == 1:
+                xa += 1
+                while ask[xa] == 0:
+                    xa += 1
+            q = quoter(t, (xb + xa) * tick / 2, inv)
+            b = a = -1
+            if q is not None:
+                b = min(math.floor(q[0] / tick + 1e-9), xa - 1)
+                a = max(math.ceil(q[1] / tick - 1e-9), xb + 1)
+                if b >= a:
+                    b = a = -1
+            if b != my_b:                                   # an unchanged level keeps its queue priority
+                if my_b >= 0:
+                    bid[my_b] -= 1
+                    while bid[bb] == 0:
+                        bb -= 1
+                if b >= 0:
+                    ahead_b = bid[b]
+                    bid[b] += 1
+                    bb = max(bb, b)
+                my_b = b
+            if a != my_a:
+                if my_a >= 0:
+                    ask[my_a] -= 1
+                    while ask[ba] == 0:
+                        ba += 1
+                if a >= 0:
+                    ahead_a = ask[a]
+                    ask[a] += 1
+                    ba = min(ba, a)
+                my_a = a
+
+        ts[n] = t
+        if n_levels == 1:
+            rec[n] = (bb, bid[bb], ba, ask[ba])
+        else:
+            rec[n] = _top_levels(bid, ask, bb, ba, n_levels)
+
+    else:
+        n = n_events                                        # no early stop at t_end
+    ts, rec = ts[:n], rec[:n]
+    quotes = pd.DataFrame({"ts": ts})
+    for m in range(n_levels):
+        sfx = "" if m == 0 else f"_{m + 1}"
+        quotes[f"bid_px{sfx}"] = rec[:, 4 * m] * tick
+        quotes[f"bid_sz{sfx}"] = rec[:, 4 * m + 1].astype(float)
+        quotes[f"ask_px{sfx}"] = rec[:, 4 * m + 2] * tick
+        quotes[f"ask_sz{sfx}"] = rec[:, 4 * m + 3].astype(float)
+    trade_df = pd.DataFrame(trades, columns=["ts", "price", "qty", "side"])
+    fill_df = pd.DataFrame(fills, columns=["ts", "side", "price", "mid"]) if quoter is not None else None
+    return SimulationResult(quotes, trade_df, fill_df)
+
+
+def _top_levels(bid: list[int], ask: list[int], bb: int, ba: int, n: int) -> list[int]:
+    """(bid_px, bid_sz, ask_px, ask_sz) for the n best non-empty levels, flattened."""
+    out = []
+    for _ in range(n):
+        out += [bb, bid[bb], ba, ask[ba]]
+        bb -= 1
+        while bid[bb] == 0:
+            bb -= 1
+        ba += 1
+        while ask[ba] == 0:
+            ba += 1
+    return out