covstream/lib.rs
1#![deny(unsafe_op_in_unsafe_fn)]
2
3//! `covstream` is a fixed-dimension streaming covariance library with Lean-backed
4//! specifications.
5//!
6//! The crate is built around two public entry points:
7//!
8//! - [`CovstreamState`] is the default user-facing API. It stores a chosen
9//! [`MatrixLayout`] and returns buffers in that layout.
10//! - [`CovstreamCore`] is the lower-level engine. It gives direct access to the
11//! underlying state and explicit extraction methods for each layout.
12//!
13//! Safe ingest paths reject:
14//!
15//! - wrong sample dimensions
16//! - malformed flat batch buffers
17//! - non-finite inputs such as `NaN` and `Inf`
18//!
19//! Covariance and shrinkage extraction require at least two observed samples.
20//! Until then the library returns [`CovstreamError::InsufficientSamples`].
21//!
22//! For higher-throughput pipelines that already validate inputs upstream, the
23//! `trusted_finite` ingest methods skip finite-value checks while preserving
24//! shape checks.
25//!
26//! Security and safety notes:
27//!
28//! - The crate does not perform network I/O, file I/O, subprocess execution, or
29//! environment-based configuration in its library API.
30//! - The checked ingest paths validate dimensions and reject non-finite values.
31//! - The only `unsafe` code is isolated to optional AArch64 SIMD leaf kernels in
32//! `src/kernels.rs`.
33
34mod core;
35mod error;
36mod kernels;
37mod layout;
38mod packing;
39pub mod shrinkage;
40mod state;
41
42pub use core::CovstreamCore;
43pub use error::CovstreamError;
44pub use layout::MatrixLayout;
45pub use shrinkage::{
46 diagonal_mean_row_major, scaled_identity_row_major, shrink_row_major,
47 shrink_with_mode_row_major, ShrinkageMode,
48};
49pub use state::CovstreamState;