Class ClosingAuctionModel

java.lang.Object
com.quantfinlib.microstructure.ClosingAuctionModel
public final class ClosingAuctionModel extends Object
Closing-auction participation model. The CLOSING_PRICE benchmark curve back-loads the continuous session (f²) but is blind to the auction itself — and for many liquid names the close auction is 5-15% of the day, the single deepest liquidity event. Two questions decide how much of a parent to RESERVE for it:
  1. How big is the auction, typically? Learned across days: feed onAuctionResult(long, long) at each close and the auction's share of daily volume becomes a day-over-day EWMA (first session seeds — the same convention as the seasonality curves);
  2. Which way is TODAY's auction leaning? From the venue's imbalance dissemination (see the input contract below): an imbalance on the OPPOSITE side of your parent means the auction is looking for exactly your shares — reserve more; an imbalance on YOUR side means you would join a crowd competing to trade — reserve less and work the continuous market instead.

Input contract (documented, not proven)

onImbalance(long, boolean, long, double, double) expects the fields every major close-auction feed disseminates in the final minutes (Nasdaq NOII, NYSE order imbalance): the imbalance quantity and side (unmatched shares), the paired quantity (shares already crossable), and the indicative/reference prices. This library ships no venue imbalance feed, so this model is a documented-contract structure: the learning and the reserve logic are tested against synthetic inputs, but the mapping from YOUR venue's message format — and the imbalanceSensitivity calibration — must be validated against real dissemination data before the output steers size. That caveat is the honest price of shipping the model without pretending to have the data.

Usage with the executor: cap the continuous-session child at (1 − reserveFraction(buy)) × remaining — the model shapes what the CLOSING_PRICE curve leaves for the auction; it does not replace the curve. Zero allocation per event, single writer, one instance per symbol; the learned auction share persists via persist.Checkpoint, today's imbalance state resets on restore.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ClosingAuctionModel()
    10% day weight, ±50% imbalance tilt, reserve capped at 30%.
    ClosingAuctionModel(double dayAlpha, double imbalanceSensitivity, double maxReserveFraction)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    auctionShare()
    The learned typical auction share of daily volume (0 until learned).
    int
    daysLearned()
     
    double
    imbalanceRatio()
    Today's signed imbalance as a fraction of total auction interest (+ = buy-side unmatched); 0 before any dissemination.
    double
    indicativePressure()
    Where the auction is clearing relative to the continuous market, as a clamped relative difference; 0 before any dissemination.
    void
    onAuctionResult(long auctionVolume, long continuousVolume)
    Closes the day: folds the realized auction share of total volume into the learned baseline (first session seeds) and resets today's imbalance state.
    void
    onImbalance(long imbalanceQty, boolean buyImbalance, long pairedQty, double indicativePrice, double referencePrice)
    An imbalance dissemination tick (see the class input contract).
    void
    readState(DataInput in)
    Restores the learned share; today's imbalance state resets.
    double
    reserveFraction(boolean parentIsBuy)
    The fraction of the remaining parent to hold back for the auction.
    void
    writeState(DataOutput out)
    Persists the learned auction share — see persist.Checkpoint.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ClosingAuctionModel

      public ClosingAuctionModel(double dayAlpha, double imbalanceSensitivity, double maxReserveFraction)
      Parameters:
      dayAlpha - day-over-day EWMA weight for the auction share, e.g. 0.1
      imbalanceSensitivity - how hard the live imbalance tilts the reserve around the learned share, e.g. 0.5 (a fully one-sided book moves the reserve ±50%) — CALIBRATE on your venue
      maxReserveFraction - hard cap on what may be held back for the auction, e.g. 0.3

    • ClosingAuctionModel

      public ClosingAuctionModel()
      10% day weight, ±50% imbalance tilt, reserve capped at 30%.

  • Method Details

    • onImbalance

      public void onImbalance(long imbalanceQty, boolean buyImbalance, long pairedQty, double indicativePrice, double referencePrice)
      An imbalance dissemination tick (see the class input contract). Non-finite prices or empty books are gaps — nothing updates.
      Parameters:
      imbalanceQty - unmatched shares on buyImbalance's side
      buyImbalance - true when the unmatched interest is to BUY
      pairedQty - shares already matched at the indicative price
      indicativePrice - the price the auction would clear at now
      referencePrice - the continuous-market reference (last/mid)

    • onAuctionResult

      public void onAuctionResult(long auctionVolume, long continuousVolume)
      Closes the day: folds the realized auction share of total volume into the learned baseline (first session seeds) and resets today's imbalance state. Zero-volume days teach nothing.

    • reserveFraction

      public double reserveFraction(boolean parentIsBuy)
      The fraction of the remaining parent to hold back for the auction. Base = the learned auction share; the live imbalance tilts it: an imbalance OPPOSITE your side raises the reserve (the auction wants your shares), a same-side imbalance lowers it (you'd join a crowd). Capped at the configured maximum; 0 while nothing is learned.

    • auctionShare

      public double auctionShare()
      The learned typical auction share of daily volume (0 until learned).

    • imbalanceRatio

      public double imbalanceRatio()
      Today's signed imbalance as a fraction of total auction interest (+ = buy-side unmatched); 0 before any dissemination.

    • indicativePressure

      public double indicativePressure()
      Where the auction is clearing relative to the continuous market, as a clamped relative difference; 0 before any dissemination.

    • daysLearned

      public int daysLearned()

    • writeState

      public void writeState(DataOutput out) throws IOException
      Persists the learned auction share — see persist.Checkpoint.
      Throws:
      IOException

    • readState

      public void readState(DataInput in) throws IOException
      Restores the learned share; today's imbalance state resets. Throws on a version mismatch.
      Throws:
      IOException