Crate tritium_core 

tritium-core

Foundation crate for Tritium. Pure, dependency-free, no_std-able. Holds the shared vocabulary and the correctness ground truth that every backend is measured against:

• Trit — a value constrained to {-1, 0, +1} (~1.585 bits).
• DType — the precision lattice (ternary, int, fp8/fp4, fp16/bf16/fp32).
• TernaryFormat — canonical packing schemes (TQ1_0, TQ2_0). The byte layout / pack code lives in tritium-format; this is just the shared name + bpw.
• ScaleGranularity + absmean — the scaling contract (BitNet b1.58 AbsMean).
• GemmShape — (M, N, K) problem geometry.
• reference_mpgemm — the slow, obviously-correct mixed-precision GEMM that every backend kernel must match within tolerance.

Nothing here touches a GPU, a thread pool, or std (unless the std feature is on). Backends depend on this crate; this crate depends on nothing.

Structs

ConvShape

Geometry of a ternary 1-D convolution Y[B, C_out, L_out] = scale ⊙ conv1d(X, W) — the codec’s conv op (ADR 0030). The weight is packed 2-D [C_out, (C_in/groups)·K] (the per-output-channel ternary reshape), so k_g() is the matmul contraction and n_g() the per-group output count.

GemmShape

Dimensions of a matmul C[M,N] = A[M,K] · Wᵀ, where W is the [N, K] ternary weight (row-major, output-major) and A is the activation [M, K].

Trit

A ternary value constrained to {-1, 0, +1}.

Enums

DType

Element precisions Tritium reasons about across backends.

ScaleGranularity

How a scale factor is shared across a weight tensor.

TernaryFormat

Canonical packing schemes for ternary weights — the shared vocabulary across crates. The byte-exact layout, pack, and unpack live in tritium-format; this enum only fixes the names, block size, and effective width so every crate agrees on them.

TritError

Errors from ternary type construction and reference math.

Constants

TERNARY_IDEAL_BITS

log2(3): the information-theoretic floor for one ternary value, in bits.

Functions

absmean

AbsMean scale — the BitNet b1.58 quantization scale for a slice of weights: scale = mean(|w|). Quantize with round(w / scale) clamped to {-1,0,1}; dequantize with trit * scale.

reference_conv1d

Reference ternary 1-D convolution — the multiply-free (add / subtract / skip) oracle every backend (CPU / CUDA / MCU) is measured against, and the numeric truth the codec conformance vectors freeze.

reference_fsq

Reference FSQ (finite scalar quantization) — the byte-exact clamp deploy grid, the oracle for the codec latent quantizer. Per element (channel c = i / len, L = levels[c]):

reference_mpgemm

Reference mixed-precision GEMM: ternary weights × f32 activations, with a per-output-channel scale.