Struct TritFloat 

pub struct TritFloat(/* private fields */);

A floating-point number encoded in balanced ternary with a native confidence field.

The confidence field propagates automatically through arithmetic, giving any computation a live uncertainty estimate without a separate Bayesian layer.

Use TritFloat::from_f32 to construct, .to_f32() to read the value, and .confidence() to read the certainty in [0, 1].

Implementations

impl TritFloat

pub fn zero() -> Self

The canonical zero, with neutral confidence.

pub fn from_f32(x: f32) -> Self

Convert an f32 to TritFloat with maximum confidence (certainty=1.0).

pub fn from_f32_with_confidence(x: f32, confidence: f32) -> Self

Convert an f32 to TritFloat with a specified confidence in [0, 1].

pub fn to_f32(self) -> f32

Convert to f32. Confidence is discarded; use .confidence() separately.

pub fn phase(self) -> i8

The phase trit: -1 (negative), 0 (zero), or +1 (positive).

pub fn exponent(self) -> i32

The exponent as a signed integer in [-121, +121].

pub fn mantissa(self) -> u32

The mantissa as a u32 in [0, 728]. Represents fractional part as M/729.

pub fn confidence(self) -> f32

Confidence as a float in [0.0, 1.0].

0.0 = completely unknown, 0.5 = neutral/unset, 1.0 = maximally certain.

pub fn is_zero(self) -> bool

True if this value is zero (phase trit = 0).

pub fn is_uncertain(self) -> bool

True if confidence is below 0.5 (both confidence trits ≤ 0).

pub fn raw(self) -> u32

The raw u32 backing value (for serialization and hardware interop).

pub fn from_raw(raw: u32) -> Self

Reconstruct from a raw u32 (as returned by .raw()).

pub fn mul_confidence(a: Self, b: Self) -> f32

Propagation rule for multiplication: weakest link. The result is only as confident as the less certain operand.

pub fn add_confidence(a: Self, b: Self) -> f32

Propagation rule for addition: average the evidence.

pub fn neg(self) -> Self

Negate: flip phase, preserve all other fields including confidence.

pub fn abs(self) -> Self

Absolute value: force phase to +1 (or 0 if zero).

pub fn add(self, rhs: Self) -> Self

Addition with confidence propagation (average rule).

pub fn sub(self, rhs: Self) -> Self

Subtraction with confidence propagation (average rule).

pub fn mul(self, rhs: Self) -> Self

Multiplication with confidence propagation (weakest-link rule).

pub fn dot(a: &[Self], b: &[Self]) -> Self

Dot product of two slices of TritFloats.

Confidence of the result = min confidence across all terms. Zero-phase terms are skipped entirely (@sparseskip at activation level).

pub fn dot_with_skips(a: &[Self], b: &[Self]) -> (Self, usize)

Dot product returning (result, skip_count) for sparsity instrumentation.

pub fn should_route(self, threshold: f32) -> bool

Returns true if this activation should be routed to an expert.

Uncertain activations (confidence < threshold) can skip expensive expert layers entirely — the confidence field directly gates MoE routing.

threshold = minimum confidence to route (suggested: 0.3–0.5)

pub fn div(self, rhs: Self) -> Self

Division with weakest-link confidence. Division by zero returns zero with 0 confidence — the caller can detect this via is_uncertain.

pub fn recip(self) -> Self

Reciprocal: 1/x. Confidence preserved; zero input returns 0-confidence zero.

pub fn powi(self, n: i32) -> Self

Integer power. Confidence preserved — single-operand chain.

pub fn sqrt(self) -> Self

Square root. Negative input returns 0-confidence zero (not a real number).

pub fn clamp(self, lo: f32, hi: f32) -> Self

Clamp the value to [lo, hi]. Confidence is preserved unchanged.

pub fn cmp_trit(self, rhs: Self) -> Self

Ternary comparison: returns +1 if self > rhs, −1 if self < rhs, 0 if equal. Confidence = min(conf_self, conf_rhs) — comparison is only as reliable as inputs.

pub fn softmax(slice: &[Self]) -> Vec<Self>

Numerically stable softmax over a slice of TritFloats.

Values are computed in f32; each output element carries the minimum confidence of all inputs (softmax mixes every element, so the whole slice’s certainty bounds the result).

pub fn phase_digits(slice: &[Self]) -> Vec<u8>

Extract phase digits (0=neg, 1=zero, 2=pos) for a slice into a Vec<u8>.

The pre-scan buffer: a single contiguous pass over raw u32 values (% 3) before the arithmetic loop. Separating phase-check from f32 math eliminates branch misprediction in the hot loop at high sparsity (≥50% zeros).

pub fn pack_phases_u64(slice: &[Self]) -> u64

Pack zero-phase flags for up to 64 TritFloats into a u64 bitmask.

Bit i = 1 if slice[i].is_zero(), else 0. mask.count_ones() instantly gives the skip count for a 64-element chunk. mask == 0 means all elements are active — no branch needed in the arithmetic loop. This is the preparation layer for AVX2 vectorization of the dot product.

pub fn dot_prescan(a: &[Self], b: &[Self]) -> (Self, usize)

Dot product with two-pass pre-scan for reduced branch misprediction.

Pass 1: extract all phase flags into u8 arrays (cache-hot, no branching). Pass 2: arithmetic only for active (non-zero-phase) pairs.

Outperforms dot_with_skips at ≥50% sparsity where misprediction of the inline zero-check dominates. At low sparsity the extra allocation cost makes it slightly slower — profile before choosing.

Trait Implementations

impl Clone for TritFloat

fn clone(&self) -> TritFloat

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TritFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for TritFloat

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for TritFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for TritFloat

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for TritFloat

fn eq(&self, other: &TritFloat) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for TritFloat

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for TritFloat

impl Eq for TritFloat

impl StructuralPartialEq for TritFloat