Skip to main content

kinetic_signals/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3#![warn(missing_docs)]
4#![cfg_attr(docsrs, feature(doc_cfg))]
5
6//! # kinetic-signals
7//!
8//! Streaming feature extraction for high-velocity stochastic signals.
9//!
10//! A high-performance, domain-agnostic Rust crate for computing streaming
11//! statistics, long-memory estimates, point-process intensity, and normalized
12//! surprise metrics.
13//!
14//! ## Features
15//!
16//! - **Hurst Exponent** - Detects long-term memory and persistence in time-series data
17//! - **Hawkes Process** - Models self-exciting event clusters in point processes
18//! - **Surprise** - Detects anomalous transition magnitudes via normalized log-ratio z-scores
19//! - **Volatility** - Real-time variance and standard deviation tracking
20//! - **Shannon Entropy** - Measures signal complexity and information density
21//! - **Indicators** - Moving averages (EMA, SMA) and Z-score tracking
22//! - **Snapshot / restore** - Versioned checkpoints for `VolEstimator`, `EMA`, and `SMA`
23//! - **Buffer reuse** - [`compute_surprise_sequence_into`] and
24//!   [`compute_shannon_entropy_into`] write into caller-owned `Vec`s
25//!
26//! ## Performance (Ryzen 9 9950X)
27//!
28//! - Hurst (100 samples): ~50μs
29//! - Hawkes (10 events): ~5μs
30//! - Surprise: ~100ns
31//!
32//! ## Quick start
33//!
34//! Add the crate to `Cargo.toml` (see [Installation](https://github.com/rmems/kinetic-signals#installation)
35//! in the README for registry vs git dependencies), then call the estimators
36//! from Rust:
37//!
38//! ```rust,no_run
39//! use kinetic_signals::{SurpriseParams, VolEstimator, compute_hurst, compute_surprise};
40//!
41//! let _hurst = compute_hurst(&[1.0, 2.0, 3.0, 4.0, 5.0]);
42//! let _surprise = compute_surprise(150.0, 100.0, &SurpriseParams::default());
43//! let _vol = VolEstimator::new(64);
44//! ```
45//!
46//! ## Feature flags
47//!
48//! | Feature | Default | Description |
49//! |---------|---------|-------------|
50//! | *(none)* | yes | Core streaming estimators; zero required runtime dependencies |
51//! | `serde` | no | `Serialize` / `Deserialize` on [`VolEstimatorSnapshot`], [`EMASnapshot`], and [`SMASnapshot`] |
52//!
53//! ## Example
54//!
55//! ```rust
56//! use kinetic_signals::{
57//!     SurpriseParams, compute_hurst, compute_surprise, compute_surprise_sequence_into,
58//! };
59//!
60//! let data = vec![1.0, 2.0, 3.0, 4.0, 5.0];
61//! let h_result = compute_hurst(&data);
62//!
63//! let params = SurpriseParams::default();
64//! let surprise = compute_surprise(150.0, 100.0, &params);
65//!
66//! let mut buf = Vec::new();
67//! compute_surprise_sequence_into(&[100.0, 101.0, 102.0], &params, &mut buf);
68//! assert_eq!(buf.len(), 2);
69//! ```
70//!
71//! ## Numeric contract
72//!
73//! Public numerical APIs expect finite inputs. Non-finite values (`NaN`,
74//! `±Inf`) and other ill-conditioned cases (empty/short series, constant
75//! windows, non-positive surprise samples, near-zero variance) yield a
76//! **documented finite sentinel** rather than an accidental `NaN`. See each
77//! function's rustdoc and the README "Numeric input contract" table.
78//!
79pub mod entropy;
80pub mod hawkes;
81pub mod hurst;
82pub mod indicators;
83mod numeric;
84mod real;
85pub mod snapshot;
86pub mod stats;
87pub mod surprise;
88pub mod volatility;
89
90pub use entropy::{
91    EntropyResult, MAX_ENTROPY_BINS, compute_shannon_entropy, compute_shannon_entropy_into,
92};
93pub use hawkes::{HawkesParams, HawkesResult, compute_hawkes, compute_hawkes_streaming};
94pub use hurst::{HurstResult, compute_hurst};
95pub use indicators::{EMA, SMA, ZScore};
96pub use snapshot::{
97    EMASnapshot, MAX_SNAPSHOT_CAPACITY, RESTORE_OUTPUT_TOLERANCE, SMASnapshot,
98    SNAPSHOT_SCHEMA_VERSION, SnapshotError, VolEstimatorSnapshot,
99};
100pub use stats::{SignalStats, compute_signal_stats};
101pub use surprise::{
102    SurpriseParams, SurpriseResult, compute_surprise, compute_surprise_sequence,
103    compute_surprise_sequence_into, detect_anomaly, surprise_sequence_len,
104};
105pub use volatility::VolEstimator;
106
107/// Convenience glob-import of every public type and function from the
108/// crate's computation modules (entropy, hawkes, hurst, indicators, snapshot,
109/// stats, surprise, volatility). Application-level observability integrations are
110/// intentionally outside this signal-processing crate.
111///
112/// The prelude is covered by the crate's pre-1.0 SemVer policy (see the
113/// "Pre-1.0 SemVer / Stability Policy" section of `README.md`): removing or
114/// renaming an item exported here follows the same breaking-change rules as
115/// removing it from its owning module. Adding a new public item is usually
116/// safe, but because the prelude re-exports via glob (`pub use ...::*`), a
117/// new name can still collide with a downstream glob import, and a new
118/// trait implementation can make previously-unambiguous method calls
119/// ambiguous; treat such additions with the same compatibility review as
120/// any other public API change.
121pub mod prelude {
122    pub use crate::entropy::*;
123    pub use crate::hawkes::*;
124    pub use crate::hurst::*;
125    pub use crate::indicators::*;
126    pub use crate::snapshot::*;
127    pub use crate::stats::*;
128    pub use crate::surprise::*;
129    pub use crate::volatility::*;
130}
131
132/// Compile-time assertion: all public types are `Send + Sync`.
133/// If this fails, update docs/boundary-matrix.md thread-safety section.
134/// MAINTENANCE: Add new public types here when they are added to any module.
135fn _assert_send_sync() {
136    fn assert_send_sync<T: Send + Sync>() {}
137    assert_send_sync::<VolEstimator>();
138    assert_send_sync::<VolEstimatorSnapshot>();
139    assert_send_sync::<EMASnapshot>();
140    assert_send_sync::<SMASnapshot>();
141    assert_send_sync::<SnapshotError>();
142    assert_send_sync::<HurstResult>();
143    assert_send_sync::<HurstResult<f32>>();
144    assert_send_sync::<HawkesResult>();
145    assert_send_sync::<HawkesParams>();
146    assert_send_sync::<surprise::SurpriseResult>();
147    assert_send_sync::<surprise::SurpriseResult<f32>>();
148    assert_send_sync::<surprise::SurpriseParams>();
149    assert_send_sync::<surprise::SurpriseParams<f32>>();
150    assert_send_sync::<EntropyResult>();
151    assert_send_sync::<SignalStats>();
152    assert_send_sync::<EMA>();
153    assert_send_sync::<SMA>();
154    assert_send_sync::<ZScore>();
155}