Class VolumeCurve

java.lang.Object
com.quantfinlib.microstructure.VolumeCurve
public final class VolumeCurve extends Object
Dynamic intraday volume prediction — the model that makes a VWAP schedule live instead of historical. Two parts:
  1. The learned profile — per-bucket volume EWMA across days (feed each session via onVolume(int, long) and close it with rollDay()), giving the classic U-shaped expected curve without any external data;
  2. The intraday rescale — today rarely trades the average day's volume. The projection scales the remaining curve by today's realized-vs-expected ratio, shrunk toward 1 early in the day when the ratio is mostly noise: scale = 1 + w·(ratio − 1) with w = the fraction of the expected day already elapsed. A 2× morning turns into a confident 2× afternoon only as evidence accumulates.

expectedFractionElapsed(int, double) is exactly the BenchmarkExecutor.MarketState.expectedVolumeFractionElapsed input: VWAP tracks this curve, so plugging the two together upgrades VWAP from "yesterday's shape" to "today's shape, updated live." The static historical-profile counterpart is ml.IntradayLiquidityForecaster; this class is its dynamic sibling. Cross-asset (volumes are just sums), zero allocation per event, single writer.

  • Constructor Summary

    Constructors
    Constructor
    Description
    VolumeCurve()
    78 five-minute equity buckets, 10% day weight.
    VolumeCurve(int buckets, double alpha)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    buckets()
     
    int
    daysLearned()
     
    double
    expectedFractionElapsed(int bucket, double fracWithinBucket)
    Expected fraction of TODAY's total volume already traded, at fracWithinBucket through bucket — the live VWAP curve input.
    double
    expectedVolumeRemaining(int bucket, double fracWithinBucket)
    Volume still expected between now and the close, under the projection.
    void
    onVolume(int bucket, long qty)
    Market volume observed in bucket (call as prints arrive).
    double
    profileVolume(int bucket)
    The learned average volume for one bucket.
    double
    projectedDayVolume(int bucket, double fracWithinBucket)
    Projected total volume for today: the learned day total scaled by today's realized-vs-expected ratio, shrunk toward 1 by how much of the expected day has elapsed.
    void
    readState(DataInput in)
    Restores the learned profile; intraday state resets (restore at session start).
    double
    realizedToday()
    Today's realized volume so far (O(1) running total).
    void
    rollDay()
    Closes the session: folds today into the learned profile and resets the intraday state.
    VolumeCurve
    seedProfile(double[] volumesPerBucket)
    Seeds the profile from a known shape (any positive scale) — optional.
    void
    writeState(DataOutput out)
    Persists the learned profile (cross-day state) — see persist.Checkpoint.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • VolumeCurve

      public VolumeCurve(int buckets, double alpha)
      Parameters:
      buckets - buckets per session (e.g. 78 five-minute buckets for a 6.5h equity day; 288 for a 24h FX day)
      alpha - day-over-day EWMA weight, e.g. 0.1

    • VolumeCurve

      public VolumeCurve()
      78 five-minute equity buckets, 10% day weight.

  • Method Details

    • seedProfile

      public VolumeCurve seedProfile(double[] volumesPerBucket)
      Seeds the profile from a known shape (any positive scale) — optional.

    • onVolume

      public void onVolume(int bucket, long qty)
      Market volume observed in bucket (call as prints arrive).

    • rollDay

      public void rollDay()
      Closes the session: folds today into the learned profile and resets the intraday state. Call once per trading day. Unlike the vol/spread curves, a zero bucket IS a real observation here (no prints = no volume), so partial-coverage sessions (feed started mid-day) bias the profile — exclude them from rollDay or seed the shape via seedProfile(double[]) instead.

    • expectedFractionElapsed

      public double expectedFractionElapsed(int bucket, double fracWithinBucket)
      Expected fraction of TODAY's total volume already traded, at fracWithinBucket through bucket — the live VWAP curve input. Falls back to linear time when no profile is learned yet (VWAP degrades to TWAP, the honest default).

    • projectedDayVolume

      public double projectedDayVolume(int bucket, double fracWithinBucket)
      Projected total volume for today: the learned day total scaled by today's realized-vs-expected ratio, shrunk toward 1 by how much of the expected day has elapsed. Returns the learned total before any intraday evidence, 0 when nothing is learned or realized.

    • expectedVolumeRemaining

      public double expectedVolumeRemaining(int bucket, double fracWithinBucket)
      Volume still expected between now and the close, under the projection.

    • realizedToday

      public double realizedToday()
      Today's realized volume so far (O(1) running total).

    • profileVolume

      public double profileVolume(int bucket)
      The learned average volume for one bucket.

    • writeState

      public void writeState(DataOutput out) throws IOException
      Persists the learned profile (cross-day state) — see persist.Checkpoint.
      Throws:
      IOException

    • readState

      public void readState(DataInput in) throws IOException
      Restores the learned profile; intraday state resets (restore at session start). Throws if the checkpoint was written with a different bucket count or an unknown state version.
      Throws:
      IOException

    • buckets

      public int buckets()

    • daysLearned

      public int daysLearned()