Skip to main content

Crate kinetic_signals

Crate kinetic_signals 

Source
Expand description

§kinetic-signals

Streaming feature extraction for high-velocity stochastic signals.

A high-performance, domain-agnostic Rust crate for computing streaming statistics, long-memory estimates, point-process intensity, and normalized surprise metrics.

§Features

  • Hurst Exponent - Detects long-term memory and persistence in time-series data
  • Hawkes Process - Models self-exciting event clusters in point processes
  • Surprise - Detects anomalous transition magnitudes via normalized log-ratio z-scores
  • Volatility - Real-time variance and standard deviation tracking
  • Shannon Entropy - Measures signal complexity and information density
  • Indicators - Moving averages (EMA, SMA) and Z-score tracking
  • Snapshot / restore - Versioned checkpoints for VolEstimator, EMA, and SMA
  • Buffer reuse - compute_surprise_sequence_into and compute_shannon_entropy_into write into caller-owned Vecs

§Performance (Ryzen 9 9950X)

  • Hurst (100 samples): ~50μs
  • Hawkes (10 events): ~5μs
  • Surprise: ~100ns

§Quick start

Add the crate to Cargo.toml (see Installation in the README for registry vs git dependencies), then call the estimators from Rust:

use kinetic_signals::{SurpriseParams, VolEstimator, compute_hurst, compute_surprise};

let _hurst = compute_hurst(&[1.0, 2.0, 3.0, 4.0, 5.0]);
let _surprise = compute_surprise(150.0, 100.0, &SurpriseParams::default());
let _vol = VolEstimator::new(64);

§Feature flags

FeatureDefaultDescription
(none)yesCore streaming estimators; zero required runtime dependencies
serdenoSerialize / Deserialize on VolEstimatorSnapshot, EMASnapshot, and SMASnapshot

§Example

use kinetic_signals::{
    SurpriseParams, compute_hurst, compute_surprise, compute_surprise_sequence_into,
};

let data = vec![1.0, 2.0, 3.0, 4.0, 5.0];
let h_result = compute_hurst(&data);

let params = SurpriseParams::default();
let surprise = compute_surprise(150.0, 100.0, &params);

let mut buf = Vec::new();
compute_surprise_sequence_into(&[100.0, 101.0, 102.0], &params, &mut buf);
assert_eq!(buf.len(), 2);

§Numeric contract

Public numerical APIs expect finite inputs. Non-finite values (NaN, ±Inf) and other ill-conditioned cases (empty/short series, constant windows, non-positive surprise samples, near-zero variance) yield a documented finite sentinel rather than an accidental NaN. See each function’s rustdoc and the README “Numeric input contract” table.

Re-exports§

pub use entropy::EntropyResult;
pub use entropy::MAX_ENTROPY_BINS;
pub use entropy::compute_shannon_entropy;
pub use entropy::compute_shannon_entropy_into;
pub use hawkes::HawkesParams;
pub use hawkes::HawkesResult;
pub use hawkes::compute_hawkes;
pub use hawkes::compute_hawkes_streaming;
pub use hurst::HurstResult;
pub use hurst::compute_hurst;
pub use indicators::EMA;
pub use indicators::SMA;
pub use indicators::ZScore;
pub use snapshot::EMASnapshot;
pub use snapshot::MAX_SNAPSHOT_CAPACITY;
pub use snapshot::RESTORE_OUTPUT_TOLERANCE;
pub use snapshot::SMASnapshot;
pub use snapshot::SNAPSHOT_SCHEMA_VERSION;
pub use snapshot::SnapshotError;
pub use snapshot::VolEstimatorSnapshot;
pub use stats::SignalStats;
pub use stats::compute_signal_stats;
pub use surprise::SurpriseParams;
pub use surprise::SurpriseResult;
pub use surprise::compute_surprise;
pub use surprise::compute_surprise_sequence;
pub use surprise::compute_surprise_sequence_into;
pub use surprise::detect_anomaly;
pub use surprise::surprise_sequence_len;
pub use volatility::VolEstimator;

Modules§

entropy
Shannon entropy of a real-valued signal via histogram discretization.
hawkes
Hawkes self-exciting point process intensity estimation.
hurst
Hurst exponent estimation via rescaled-range (R/S) analysis.
indicators
Streaming technical indicators for real-valued signals.
prelude
Convenience glob-import of every public type and function from the crate’s computation modules (entropy, hawkes, hurst, indicators, snapshot, stats, surprise, volatility). Application-level observability integrations are intentionally outside this signal-processing crate.
snapshot
Versioned snapshot and restore for stateful streaming estimators.
stats
Higher-order moments of a real-valued signal.
surprise
Domain-agnostic surprise detection.
volatility
Rolling RMS volatility estimator — zero-alloc, fixed-size ring buffer.