irithyll_core/
lib.rs

1//! Core types and inference engine for irithyll streaming ML.
2//!
3//! `irithyll-core` is the `#![no_std]` foundation shared by the full irithyll
4//! crate and embedded targets. It provides loss functions, the streaming
5//! [`Observation`] trait, a compact 12-byte packed node format, and branch-free
6//! ensemble traversal for deploying trained models on bare metal
7//! (Cortex-M0+, 32 KB flash).
8//!
9//! The crate has a hard dependency boundary: only `libm` is mandatory. All
10//! dynamic-allocation paths (histogram binning, tree construction, drift
11//! detectors, neural architectures) gate on the `alloc` feature.
12//!
13//! # Feature Flags
14//!
15//! | Feature | Description |
16//! |---------|-------------|
17//! | `alloc` | Enables dynamic-allocation types: trees, ensembles, drift, neural |
18//! | `std` | Enables `alloc` plus standard I/O (required for full `irithyll` crate) |
19//! | `serde` | Derives `Serialize`/`Deserialize` on config and snapshot types |
20//! | `kmeans-binning` | K-means histogram binning strategy (requires `alloc`) |
21//! | `parallel` | Rayon-parallel tree training (requires `alloc`) |
22//! | `simd` | AVX2 histogram accumulation acceleration (requires `std`) |
23//! | `simd-avx2` | Explicit AVX2 SIMD intrinsics (requires `std`) |
24//! | `embedded-bench` | Cortex-M semihosting bench helpers |
25//! | `iai-bench` | iai-callgrind regression bench source |
26//!
27//! # Embedded Inference
28//!
29//! Train a model with the full `irithyll` crate, then export:
30//!
31//! ```ignore
32//! use irithyll_core::{EnsembleView, FormatError};
33//!
34//! // packed_bytes is a &[u8] from irithyll::export_embedded()
35//! let packed_bytes: &[u8] = &[];
36//! let view = EnsembleView::from_bytes(packed_bytes)?;
37//! let prediction = view.predict(&[1.0f32, 2.0, 3.0]);
38//! # Ok::<(), FormatError>(())
39//! ```
40//!
41//! The packed format stores each node in 12 bytes (5 nodes per cache line).
42//! Traversal is branch-free: child selection uses `cmov`/`csel`-equivalent
43//! conditionals that avoid pipeline stalls on Cortex-M.
44
45#![no_std]
46#![warn(missing_docs)]
47#![deny(unsafe_op_in_unsafe_fn)]
48#![cfg_attr(docsrs, feature(doc_cfg))]
49// Note: irithyll-core contains legitimate `unsafe impl Send/Sync` for tree types
50// and optional AVX2 SIMD intrinsics. The main irithyll crate forbids unsafe code.
51
52#[cfg(feature = "alloc")]
53extern crate alloc;
54
55#[cfg(feature = "std")]
56extern crate std;
57
58#[cfg(all(test, not(feature = "alloc")))]
59extern crate alloc;
60
61pub mod drift;
62pub mod error;
63pub mod loss;
64pub mod math;
65pub mod packed;
66pub mod packed_i16;
67pub mod quantize;
68pub mod rng;
69pub mod sample;
70pub mod simd;
71pub mod streaming_primitives;
72pub mod traverse;
73pub mod traverse_i16;
74pub mod view;
75pub mod view_i16;
76
77#[cfg(feature = "alloc")]
78#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
79pub mod histogram;
80
81#[cfg(feature = "alloc")]
82#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
83pub mod feature;
84
85#[cfg(feature = "alloc")]
86#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
87pub mod learner;
88
89#[cfg(feature = "alloc")]
90#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
91pub mod tree;
92
93#[cfg(feature = "alloc")]
94#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
95pub mod ensemble;
96
97#[cfg(feature = "alloc")]
98#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
99pub mod reservoir;
100
101#[cfg(feature = "alloc")]
102#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
103pub mod snn;
104
105#[cfg(feature = "alloc")]
106#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
107pub mod ssm;
108
109#[cfg(feature = "alloc")]
110#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
111pub mod attention;
112
113#[cfg(feature = "alloc")]
114#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
115pub mod continual;
116
117#[cfg(feature = "alloc")]
118#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
119pub mod lstm;
120
121#[cfg(feature = "alloc")]
122#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
123pub mod turbo_quant;
124
125#[cfg(feature = "alloc")]
126#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
127pub mod mgrade;
128
129// Convenience re-exports -- inference
130pub use error::FormatError;
131pub use packed::{EnsembleHeader, PackedNode, TreeEntry};
132pub use packed_i16::{PackedNodeI16, QuantizedEnsembleHeader};
133pub use view::EnsembleView;
134pub use view_i16::QuantizedEnsembleView;
135
136// Convenience re-exports -- training core types
137pub use loss::{Loss, LossType};
138#[cfg(feature = "alloc")]
139#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
140pub use sample::Sample;
141pub use sample::{Observation, SampleRef};
142
143// Convenience re-exports -- drift detection
144pub use drift::DriftSignal;
145#[cfg(feature = "alloc")]
146#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
147pub use drift::{DriftDetector, DriftDetectorState};
148
149// Convenience re-exports -- config/error (requires alloc)
150#[cfg(feature = "alloc")]
151#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
152pub use error::{ConfigError, IrithyllError, Result};
irithyll_core/lib.rs

irithyll_core/
lib.rs
