Class HawkesIntensity

java.lang.Object
com.quantfinlib.microstructure.HawkesIntensity
public final class HawkesIntensity extends Object
Self-exciting (Hawkes) event intensity — the model behind the trader's observation that "activity breeds activity": one trade raises the probability of the next, so order flow arrives in bursts, not as a steady Poisson drizzle. The exponential Hawkes form keeps the whole process in two numbers: 
  λ(t) = μ + S(t),   S(t) = Σ over past events of α·e^(−β(t−tᵢ))
where μ is the baseline arrival rate, α the excitation each event adds, and β the decay. S updates in O(1) per event (decay what is there, add α), which is what makes Hawkes streaming-friendly while richer clustering models are not.

Stability is enforced, not assumed: the branching ratio α/β is the expected number of children each event spawns; at ≥ 1 the process is explosive (each event begets more than one, and the intensity diverges), so the constructor rejects it. Read burstScore(long) as the regime signal: 0 = baseline flow, 1 = the self-excited component equals the baseline (activity running 2×), and it decays back with the configured half-life when the burst ends.

Uses: pre-positioning for activity bursts (a burst means queues consume faster, so QueueModel horizons shorten), conflation pressure forecasting, and as a dimensionless ensemble input. Feed every arrival of the event type you care about (trades, quotes, or your own fills) via onEvent(long); timestamps must be non-decreasing (a backwards timestamp is ignored, because feed-merge jitter must not inject negative decay). Zero allocation per event, single writer, one instance per symbol per event type.

Calibration. fit(long[], long, long) estimates μ, α and β from event timestamps by maximum likelihood, using the O(n) recursion for the exponential kernel (Ozaki 1979, Ann. Inst. Statist. Math. 31(1)):

  ℓ = Σᵢ log(μ + α Aᵢ) − μT − (α/β) Σᵢ (1 − e^{−β(T − tᵢ)}),
  A₁ = 0,  Aᵢ = e^{−β(tᵢ − tᵢ₋₁)} (1 + Aᵢ₋₁)

maximised by Nelder-Mead over (log μ, log α, log β) with the stationarity constraint α/β < 1 enforced. Here α is the jump in intensity per event (events per second) and β the decay rate per second, so the half-life passed to the constructor is ln 2 / β.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    HawkesIntensity.Fit
    A maximum-likelihood calibration.

  • Constructor Summary

    Constructors
    Constructor
    Description
    HawkesIntensity()
    Baseline 2 events/s, excitation 0.1/s per event, 2s half-life (branching ~0.29).
    HawkesIntensity(double baselineRatePerSec, double excitation, long decayHalfLifeNanos)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    burstScore(long nowNanos)
    The dimensionless burst regime: self-excited intensity over the baseline, clamped to [0, 1] at "activity running 2× baseline". 0 in steady flow; decays back with the configured half-life.
    long
    events()
     
    static HawkesIntensity.Fit
    fit(long[] timestampsNanos, long startNanos, long endNanos)
    Maximum-likelihood fit of an exponential-kernel Hawkes process to event times observed over [startNanos, endNanos].
    double
    intensity(long nowNanos)
    The current intensity λ(now) in events per second.
    void
    onEvent(long timestampNanos)
    One event arrival.

    Methods inherited from class Object

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

  • Constructor Details

    • HawkesIntensity

      public HawkesIntensity(double baselineRatePerSec, double excitation, long decayHalfLifeNanos)
      Parameters:
      baselineRatePerSec - μ — arrival rate with no excitation, e.g. 2.0
      excitation - α — intensity each event adds (per second), e.g. 0.1
      decayHalfLifeNanos - how fast excitation fades, e.g. 2s. Stability requires branching ratio α/β < 1 where β = ln2/halfLife (per second): at a 2s half-life, β ≈ 0.35/s, so α must stay below ~0.35 — rejected otherwise.

    • HawkesIntensity

      public HawkesIntensity()
      Baseline 2 events/s, excitation 0.1/s per event, 2s half-life (branching ~0.29).

  • Method Details

    • onEvent

      public void onEvent(long timestampNanos)
      One event arrival. Timestamps must be non-decreasing; an out-of-order timestamp is dropped (negative decay would grow past excitation instead of fading it).

    • intensity

      public double intensity(long nowNanos)
      The current intensity λ(now) in events per second.

    • burstScore

      public double burstScore(long nowNanos)
      The dimensionless burst regime: self-excited intensity over the baseline, clamped to [0, 1] at "activity running 2× baseline". 0 in steady flow; decays back with the configured half-life.

    • events

      public long events()

    • fit

      public static HawkesIntensity.Fit fit(long[] timestampsNanos, long startNanos, long endNanos)
      Maximum-likelihood fit of an exponential-kernel Hawkes process to event times observed over [startNanos, endNanos].
      Parameters:
      timestampsNanos - non-decreasing event times inside the window
      Throws:
      IllegalArgumentException - with fewer than 10 events or a malformed window