openquant.streaming_hpc

Compiled from Rust (crates/pyopenquant). Signatures and types are from the shipped .pyi stubs; descriptions are the functions’ own docstrings, as help() shows them. All Python modules.

Functions

generate_synthetic_flash_crash_stream

generate_synthetic_flash_crash_stream(
    events: int = 1000,
    crash_start_fraction: float = 0.7,
    calm_venues: int = 3,
    shock_venue: int = 0,
) -> list[tuple[int, float, float, float, int]]

Generate a deterministic two-regime event stream loosely modelled on the 2010 Flash Crash.

AFML §22.6.4. Event i has timestamp_ns = i * 1_000_000 (1 ms apart). Before the crash (which starts at event round(events * crash_start_fraction)), event i is on venue i % calm_venues with 120 bought and 130 sold, and the price grows by 0.01% per event; from the crash on, every event is on shock_venue with 80 bought and 320 sold, and the price falls by 0.25% per event. The price starts from 100 and moves before the first event is emitted. A small stream can round to no calm events or no crash events.

Parameters

events : int, default 1000

Number of events; must be > 0.

crash_start_fraction : float, default 0.7

Fraction of the stream before the crash, strictly between 0 and 1.

calm_venues : int, default 3

Number of venues the calm flow rotates over (venues 0 .. calm_venues - 1); > 0.

shock_venue : int, default 0

Venue that carries all the flow from the crash on; may be one of the calm venues.

Returns

list[tuple[int, float, float, float, int]]

(timestamp_ns, price, buy_volume, sell_volume, venue_id) rows, the input format of run_streaming_pipeline.

Raises

ValueError

If events is 0, crash_start_fraction is not finite and strictly between 0 and 1, or calm_venues is 0.

run_streaming_pipeline

run_streaming_pipeline(
    events: Sequence[tuple[int, float, float, float, int]],
    bucket_volume: float,
    support_buckets: int,
    lookback_events: int,
    vpin_cdf_threshold: float,
    hhi_threshold: float,
    cdf_lookback: int,
) -> Any

Run the VPIN/HHI early-warning engine over a stream of events, one snapshot per event.

AFML Chapter 22 (§22.6.4-22.6.5). VPIN runs on a volume clock: events fill buckets of bucket_volume (an event that overflows a bucket is split, keeping its buy/sell ratio), and VPIN is the mean of |V_buy - V_sell| / bucket_volume over the last support_buckets full buckets. vpin_cdf_threshold applies to the empirical CDF of VPIN over the last cdf_lookback VPIN values (one per completed bucket, ties counted half), not to raw VPIN; e.g. 0.99 with cdf_lookback >= 50. HHI is sum_v (Q_v / sum_j Q_j)^2, weighting venues by their share of volume over the last lookback_events events. An event alerts when vpin_cdf >= vpin_cdf_threshold and hhi >= hhi_threshold. Events are processed in input order; timestamps are carried through but neither validated nor used.

Parameters

events : list[tuple[int, float, float, float, int]]

(timestamp_ns, price, buy_volume, sell_volume, venue_id) rows, e.g. from generate_synthetic_flash_crash_stream. Buy and sell volumes are already classified by the caller; venue_id is a non-negative int.

bucket_volume : float

Volume per VPIN bucket, in the units of the event volumes; finite and > 0.

support_buckets : int

Number of completed buckets in the VPIN mean; must be > 0.

lookback_events : int

Number of events in the HHI window; must be > 0.

vpin_cdf_threshold : float

Alert threshold on the CDF of VPIN, in (0, 1) and at most 1 - 0.5 / cdf_lookback (the largest value the CDF can take).

hhi_threshold : float

Alert threshold on HHI (1 means one venue carries all the volume), in (0, 1].

cdf_lookback : int

Number of past VPIN values the CDF is taken over; must be >= 2.

Returns

dict[str, Any]

Keys:

• snapshots: list of (timestamp_ns, price, vpin, hhi, normalized_risk_score, is_alert, vpin_cdf) tuples, one per event in input order. vpin, hhi, vpin_cdf and normalized_risk_score (min(vpin_cdf / vpin_cdf_threshold, hhi / hhi_threshold)) are None until their windows fill, and is_alert is False then. vpin_cdf is last so that the first six positions keep their meaning.
• metrics: dict with processed_events (int), events_per_sec, avg_event_latency_micros, max_event_latency_micros and runtime_secs (floats; wall-clock timings that vary between runs).
• alert_count: number of alerting snapshots (int).

Raises

ValueError

If a configuration value is out of range (see above), or an event has a price that is not finite and > 0, a negative or non-finite volume, or zero total volume. The run stops at the first invalid event and returns no partial result.