tritium_core/lib.rs
1//! # tritium-core
2//!
3//! Foundation crate for Tritium. Pure, dependency-free, `no_std`-able. Holds the
4//! shared *vocabulary* and the *correctness ground truth* that every backend is
5//! measured against:
6//!
7//! - [`Trit`] — a value constrained to `{-1, 0, +1}` (~1.585 bits).
8//! - [`DType`] — the precision lattice (ternary, int, fp8/fp4, fp16/bf16/fp32).
9//! - [`TernaryFormat`] — canonical packing schemes (`TQ1_0`, `TQ2_0`). The byte
10//! layout / pack code lives in `tritium-format`; this is just the shared name + bpw.
11//! - [`ScaleGranularity`] + [`absmean`] — the scaling contract (BitNet b1.58 AbsMean).
12//! - [`GemmShape`] — `(M, N, K)` problem geometry.
13//! - [`reference_mpgemm`] — the slow, obviously-correct mixed-precision GEMM that
14//! every backend kernel must match within tolerance.
15//!
16//! Nothing here touches a GPU, a thread pool, or `std` (unless the `std` feature
17//! is on). Backends depend on this crate; this crate depends on nothing.
18#![cfg_attr(not(feature = "std"), no_std)]
19#![forbid(unsafe_code)]
20// v0.90 hardening: every public item must carry a doc comment.
21#![deny(missing_docs)]
22
23#[cfg(feature = "alloc")]
24extern crate alloc;
25
26mod dtype;
27mod error;
28mod reference;
29mod scale;
30mod shape;
31mod trit;
32
33pub use dtype::{DType, TernaryFormat};
34pub use error::TritError;
35pub use reference::{reference_conv1d, reference_fsq, reference_mpgemm};
36pub use scale::{ScaleGranularity, absmean};
37pub use shape::{ConvShape, GemmShape};
38pub use trit::Trit;
39
40/// log2(3): the information-theoretic floor for one ternary value, in bits.
41pub const TERNARY_IDEAL_BITS: f32 = 1.584_962_5;