Class VolatilityCurve

java.lang.Object
com.quantfinlib.microstructure.VolatilityCurve
public final class VolatilityCurve extends Object
Intraday volatility seasonality — the third leg of the seasonality trio beside VolumeCurve and SpreadForecaster: volatility is U-shaped through an equity day (wild open, quiet lunch, busy close) and session-humped through an FX day (London open, NY overlap), so "is the market volatile right now?" is meaningless without "…for this time of day."

Each session accumulates a per-bucket mean of the observed volatility (feed SignalEngine.volPerSqrtSecond at whatever cadence you poll it); rollDay() folds it into a per-bucket baseline with the day-over-day EWMA, the first session seeding directly.

regime(int, double) is the point of the class: the normalized volatility-regime signal that execution.BenchmarkExecutor.MarketState documents as its volatility input — current vol against the time-of-day baseline, mapped to ~0 (calm for this hour) … 1 (extreme), so "the open is always wild" doesn't read as an urgency signal but a genuinely wild lunchtime does. Before any baseline is learned the regime is 0 (neutral) — the honest default. Cross-asset, zero allocation, single writer.

  • Constructor Summary

    Constructors
    Constructor
    Description
    VolatilityCurve()
    78 equity buckets, 10% day weight.
    VolatilityCurve(int buckets, double dayAlpha)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    baseline(int bucket)
    The learned time-of-day baseline vol for a bucket (0 until learned).
    int
    buckets()
     
    int
    daysLearned()
     
    void
    onVol(int bucket, double volPerSqrtSecond)
    An observed volatility reading for bucket (e.g.
    void
    readState(DataInput in)
    Restores the learned baseline; today's accumulation resets (restore at session start).
    double
    regime(int bucket, double currentVolPerSqrtSecond)
    The normalized volatility-regime signal for BenchmarkExecutor.MarketState.volatility: how elevated the current vol is against this hour's baseline, clamp(current/baseline − 1, 0, 1). 0 when calm-for-the-hour, unlearned, or fed a non-finite reading — a bad input reads as neutral, never as urgency.
    void
    rollDay()
    Closes the session: folds today's per-bucket mean vol into the baseline (buckets without observations keep their learned value).
    VolatilityCurve
    seedBaseline(double[] volPerBucket)
    Seeds the baseline from a known shape (same units you will feed) — optional.
    void
    writeState(DataOutput out)
    Persists the learned baseline (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

    • VolatilityCurve

      public VolatilityCurve(int buckets, double dayAlpha)
      Parameters:
      buckets - time buckets per session (78 equities, 288 for 24h FX)
      dayAlpha - baseline EWMA weight across days, e.g. 0.1

    • VolatilityCurve

      public VolatilityCurve()
      78 equity buckets, 10% day weight.

  • Method Details

    • seedBaseline

      public VolatilityCurve seedBaseline(double[] volPerBucket)
      Seeds the baseline from a known shape (same units you will feed) — optional.

    • onVol

      public void onVol(int bucket, double volPerSqrtSecond)
      An observed volatility reading for bucket (e.g. SignalEngine.volPerSqrtSecond, polled per interval). Non-finite or negative readings are ignored.

    • rollDay

      public void rollDay()
      Closes the session: folds today's per-bucket mean vol into the baseline (buckets without observations keep their learned value). Seeding is PER BUCKET — a bucket first observed on day 5 (feed started mid-session on day 1, a half day skipped the afternoon) seeds from its own first observation rather than EWMA-ramping from 0, which would leave regime(int, double) falsely reading "extreme" at that hour for weeks.

    • baseline

      public double baseline(int bucket)
      The learned time-of-day baseline vol for a bucket (0 until learned).

    • regime

      public double regime(int bucket, double currentVolPerSqrtSecond)
      The normalized volatility-regime signal for BenchmarkExecutor.MarketState.volatility: how elevated the current vol is against this hour's baseline, clamp(current/baseline − 1, 0, 1). 0 when calm-for-the-hour, unlearned, or fed a non-finite reading — a bad input reads as neutral, never as urgency.

    • writeState

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

    • readState

      public void readState(DataInput in) throws IOException
      Restores the learned baseline; today's accumulation resets (restore at session start). Throws on a bucket-count or version mismatch.
      Throws:
      IOException

    • buckets

      public int buckets()

    • daysLearned

      public int daysLearned()