Package com.quantfinlib.execution

@NullMarked package com.quantfinlib.execution

Order routing, execution algorithms and the venue models they learn from. The main classes: SmartOrderRouter (fee-adjusted multi-venue splitting, dark-first option), its zero-allocation hot-lane sibling HftSor, and the full-checklist AdaptiveSor (expected-cost routing over displayed + hidden liquidity, fees/rebates, latency, fill probability and a reliability veto, with contingent dark probes) learning from VenueScorecard (streaming per-venue fill rate, measured latency, realized dark fills), TwapScheduler / VwapScheduler (schedule design with anti-gaming jitter and exact largest-remainder allocation), PovTracker (streaming percentage-of-volume participation), ImplementationShortfallScheduler (Almgren-Chriss-optimal slicing), WmrFixingScheduler (benchmark-window TWAP replication), BenchmarkExecutor (the dynamic benchmark algo: one stateful executor tracking VWAP / TWAP / Arrival / Implementation Shortfall / Closing / Opening / Participation, re-deciding each interval from live spread, depth, volatility, volume curve, alpha and liquidity, cross-asset), LiquiditySeekingAlgo (the opportunistic archetype: burst when the spread is under its time-of-day forecast in a calm regime, guaranteed by a completion floor over the final stretch), PortfolioExecutor (multi-symbol portfolio-level scheduling over per-symbol BenchmarkExecutor children: leg-balance band for two-sided transitions, per-interval notional budget allocated risk-weighted; overlays only ever damp a child's own due, so per-symbol benchmark integrity holds), IcebergOrder (display/reload state machine), DarkPoolSimulator (midpoint cross with minimum-execution-quantity), MidPegTracker (peg repricing with thresholds) and VenueBenchmark (fill rate, effective spread, markout per venue).

The spread-and-microstructure layer: SpreadExecutionAlgo (two-legged pairs/basis execution: the illiquid lead leg worked patiently, the liquid hedge leg chasing at the ratio, and a hard legging-risk cap), OrderPlacementPolicy (post-or-cross as expected-cost arithmetic, with the post region in closed form), AntiGamingJitter (seeded size/time randomization; totals exact, monotonicity preserved, deterministic per seed), FuturesRollAlgo (roll on the liquidity-migration S-curve, executed as calendar spreads) and Ucb1Selector (UCB1 bandit for venue/variant selection while scorecards are still thin: exploration decays exactly as evidence accumulates, no arm is ever fully abandoned).

4.0. This package stays in the stable jar in 4.0. The 3.1 design proposed moving it out, but stable packages (backtest) depend on it, and a move would make the module graph cyclic. See docs/DESIGN_4.0.md.

Class	Description
AdaptiveSor	The full-checklist smart order router: where SmartOrderRouter ranks venues purely on fee-adjusted displayed price and HftSor does the same at tick-path speed, this router prices in everything a production SOR actually weighs: Displayed liquidity and fees/rebates — the all-in price, as before; Probability of fill / venue reliability — a venue's VenueScorecard fill rate discounts its quote: expected cost adds (1 − fillRate) × missPenalty (the spread-ish cost of re-routing a faded child), and venues below a reliability floor are vetoed outright; Latency — slower venues pay latency × urgency: in a moving market, microseconds of delay are adverse selection.
AdaptiveSor.Config	Tunable penalties; AdaptiveSor.Config.defaults() is a sane starting point.
AdaptiveSor.RoutingDecision	The routed plan: lit legs cover up to the requested quantity (best-expected-cost first); probes are additive contingent dark legs sent alongside; unrouted is the shortfall no eligible lit venue could absorb (0 on a fully routed order).
AntiGamingJitter	Anti-gaming randomization for schedule-driven algos — a TWAP that fires identical children on a metronome is a gift to anyone watching the tape: predators detect the clock in a handful of intervals and lean on every child.
BenchmarkExecutor	The dynamic benchmark execution algorithm: one stateful executor that works a parent order toward any of the standard benchmarks (VWAP, TWAP, Arrival Price, Implementation Shortfall, Closing Price, Opening Price, and Participation (POV)).
BenchmarkExecutor.Benchmark	The benchmark this parent is measured against.
BenchmarkExecutor.MarketState	A snapshot of the real-time inputs a benchmark algo evaluates.
DarkPoolSimulator	Midpoint-cross dark pool model: hidden resting orders match at the current lit-market midpoint, honoring minimum-execution-quantity constraints (a standard anti-gaming feature).
DarkPoolSimulator.Fill
FuturesRollAlgo	The futures roll: the trade every futures position must do and most do badly.
HftSor	Hot-lane smart order router: the zero-allocation sibling of SmartOrderRouter, for when the routing decision sits on the tick-to-order path.
IcebergOrder	Iceberg order state machine: shows only a small display tranche of the full quantity and reloads automatically when the visible portion fills.
ImplementationShortfallScheduler	Implementation-shortfall (arrival-price) schedule: turns the AlmgrenChriss optimal trajectory into executable Slices.
LiquiditySeekingAlgo	The opportunistic execution archetype, counterpart to BenchmarkExecutor's schedule-driven family.
LiquiditySeekingAlgo.Config	Algorithm settings.
MidPegTracker	Mid-rate pegging model: tracks the target price of a mid-pegged order with an offset and optional limit cap, and decides when the peg has drifted far enough to justify a reprice (each reprice costs queue priority and a message, so small moves are ignored).
OrderPlacementPolicy	The post-or-cross decision — the smallest and most repeated choice in execution, made explicit as expected-cost arithmetic instead of habit.
OrderPlacementPolicy.Placement	The decision plus the arithmetic that made it.
OrderPlacementPolicy.PostRegion	The fill-probability region where posting beats crossing.
PortfolioExecutor	True multi-symbol portfolio-level scheduling: a basket (rebalance, transition, program trade) executed as one coordinated schedule rather than N independent parents.
PortfolioExecutor.Config	Execution limits for the portfolio.
PovTracker	POV (percentage-of-volume) execution tracker: the streaming counterpart of the precomputed TwapScheduler/VwapScheduler schedules.
Slice	One child slice of an execution schedule.
SmartOrderRouter	Smart Order Router: splits a marketable order across venues to minimize the all-in (fee-adjusted) execution price, respecting each venue's displayed/estimated size.
SmartOrderRouter.RouteLeg	One child order of the routing plan.
SmartOrderRouter.RoutingPlan
SpreadExecutionAlgo	Two-legged spread execution with legging-risk control — pairs trades, cash-vs-futures basis, stub-vs-hedge: the trade is the spread, and the risk is the moment you own one leg without the other.
SpreadExecutionAlgo.Children	This interval's child quantities, per leg.
TwapScheduler	TWAP (time-weighted average price) schedule design: splits a parent order into evenly spaced child slices, optionally with randomized sizes to reduce schedule predictability (anti-gaming).
Ucb1Selector	UCB1 multi-armed bandit: principled selection among venues, LPs or algo variants when the scorecards are still thin.
VenueBenchmark	Venue benchmarking from execution outcomes: fill rate, latency-to-fill, effective spread paid, and post-trade markout (adverse selection) per venue, ranked by execution quality.
VenueBenchmark.Sample	One routing outcome.
VenueBenchmark.VenueStats
VenueQuote	A venue's dealable top of book for routing.
VenueScorecard	Streaming per-venue execution quality — the equities counterpart of fx.LpScorecard: displayed prices tell you where a venue claims you'll trade; the scorecard tells you what actually happens when you send there.
VwapScheduler	VWAP schedule design: allocates child slices proportionally to an expected intraday volume profile (e.g. from com.quantfinlib.ml.IntradayLiquidityForecaster), so participation tracks the market's own volume curve.
WmrFixingScheduler	Benchmark-fixing execution schedule, WMR-style: orders benchmarked to a fixing (the WM/Refinitiv 4pm London fix and its cousins) are executed by spreading the parent evenly across the fixing's calculation window, so realized cost tracks the benchmark rather than betting against it — the window is 5 minutes for major pairs, and the benchmark is computed from observations inside it, so TWAP-in-window is the neutral replication.