From 0f61670dc8a127054dc74b1ab4de5a825107606c Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 11:00:21 +0000 Subject: [PATCH] hpc::abakus::pm: add_pm / neg_pm / sub_pm as an experimental library module The P x M arithmetic moves out of the add_pm example into ndarray::hpc::abakus::pm, the one source of truth; Codec9 keeps the representation. add_pm and sub_pm return a #[must_use] PmSum: lane() reports a carry lane as Escaped, exact() is Some only when nothing carried, and the saturated bytes come only from into_saturated_parts(). The example keeps the scalar oracle and timing and calls the library, so tests/add_pm.rs (and the backend rows that run it) now test the library code. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XAqKMNZqKXSaeb9g2ypywF --- examples/add_pm/pm.rs | 96 +++------------------ src/hpc/abakus/mod.rs | 10 +++ src/hpc/abakus/pm.rs | 191 ++++++++++++++++++++++++++++++++++++++++++ src/hpc/mod.rs | 2 + 4 files changed, 216 insertions(+), 83 deletions(-) create mode 100644 src/hpc/abakus/mod.rs create mode 100644 src/hpc/abakus/pm.rs diff --git a/examples/add_pm/pm.rs b/examples/add_pm/pm.rs index 60e7b2cf..4eb6b38c 100644 --- a/examples/add_pm/pm.rs +++ b/examples/add_pm/pm.rs @@ -1,96 +1,26 @@ -//! `add_pm`: Codec9 / DR512 `P × M` lanes added in place, 64 at a time. -//! -//! A lane is a magnitude `M` (one byte of a [`U8x64`]) and a presence bit `P` -//! (one bit of a `u64`). The DR512 law (`.claude/knowledge/dr512-epistemic-pm-invariant.md`): -//! `P=0, M=0` is never touched; `P=0, M>0` is `-M`; `P=1` is `+M`. -//! -//! The sum is sign-magnitude addition, with no decode to a signed integer: -//! -//! - an untouched lane is the identity (`untouched ⊕ x = x`), and the result -//! is touched if either input was. This needs no blend: the never-touched -//! code is a zero magnitude, so the identity is the addition itself; -//! - same polarity: `M = M_a + M_b`, `P = P_a`; the lanes where that sum -//! passes 255 are returned in the carry mask, with `M` saturated at 255; -//! - opposite polarity: `M = max - min`, `P` from the larger magnitude; -//! - a touched zero result is `+0` (`P=1`), never the never-touched code. -//! -//! The carry mask is the exact-escape signal Codec9's own encoder lacks (it -//! saturates silently): a caller applies the exact sum of those lanes -//! through a wider path. Off the carry lanes the result is exact. +//! `add_pm` probe: the timing harness and the scalar oracle for +//! [`ndarray::hpc::abakus::pm`], where the arithmetic now lives (one source +//! of truth). These wrappers return the saturated parts so the oracle can +//! check every lane, including the saturated byte of a carry lane. //! //! Subtraction is the same addition of the polarity-negated operand -//! ([`neg_pm`], [`sub_pm`]). XOR governs polarity; magnitudes stay unsigned. +//! (`neg_pm`, `sub_pm`). XOR governs polarity; magnitudes stay unsigned. +use ndarray::hpc::abakus::pm as lib; +// `neg_pm` and `touched` are used by tests/add_pm.rs, not by the timing example. +#[allow(unused_imports)] +pub use ndarray::hpc::abakus::pm::{neg_pm, touched, Pm}; use ndarray::simd::U8x64; -/// 64 `P × M` lanes. -#[derive(Clone, Copy, Debug, PartialEq)] -pub struct Pm { - pub mag: U8x64, - pub pos: u64, -} - -impl Pm { - /// Every lane never touched. - pub fn untouched() -> Self { - Pm { - mag: U8x64::splat(0), - pos: 0, - } - } -} - -/// Lanes that hold a value (touched): `P=1`, or `M != 0`. -#[inline(always)] -pub fn touched(x: Pm) -> u64 { - x.pos | !x.mag.cmpeq_mask(U8x64::splat(0)) -} - -/// `a ⊕ b` lane-wise, and the lanes whose exact sum is outside ±255. +/// [`lib::add_pm`] as `(lanes, carry)`; carry lanes are saturated. #[inline(always)] pub fn add_pm(a: Pm, b: Pm) -> (Pm, u64) { - let zero = U8x64::splat(0); - let (ta, tb) = (touched(a), touched(b)); - let same = !(a.pos ^ b.pos); - // same polarity: saturating sum; carry where M_a > 255 - M_b - let sum = a.mag.saturating_add(b.mag); - let room = U8x64::splat(255).saturating_sub(b.mag); - let carry = same & ta & tb & a.mag.cmpgt_mask(room); - // opposite polarity: |M_a - M_b|, polarity of the larger magnitude - let hi = a.mag.simd_max(b.mag); - let lo = a.mag.simd_min(b.mag); - let diff = hi.saturating_sub(lo); - let a_larger = a.mag.cmpgt_mask(b.mag); - let p_opp = (a_larger & a.pos) | (!a_larger & b.pos); - let mag = U8x64::mask_blend(same, diff, sum); - let pos = (same & a.pos) | (!same & p_opp); - // A zero result is +0 when either input was touched, and stays the - // never-touched code when neither was. No identity blend is needed: read - // as sign-magnitude, the never-touched code is a zero magnitude, so - // `untouched ⊕ x = x` falls out of the addition itself; only this zero - // normalization has to know about presence. - let pos = pos | (mag.cmpeq_mask(zero) & (ta | tb)); - (Pm { mag, pos }, carry) -} - -/// `-b` lane-wise: the polarity bit flips on lanes with a magnitude. -/// -/// `P_¬b = P_b ⊕ (M_b ≠ 0)`. A zero magnitude keeps its polarity, so the -/// never-touched code (`P=0, M=0`) stays never touched and `+0` stays `+0`: -/// `-0` is never produced, and remains only the never-touched sentinel. -#[inline(always)] -pub fn neg_pm(b: Pm) -> Pm { - let nonzero = !b.mag.cmpeq_mask(U8x64::splat(0)); - Pm { - mag: b.mag, - pos: b.pos ^ nonzero, - } + lib::add_pm(a, b).into_saturated_parts() } -/// `a ⊖ b` lane-wise: `a ⊕ (-b)`, with `add_pm`'s carry contract. There is -/// no separate subtractor. +/// [`lib::sub_pm`] as `(lanes, carry)`; carry lanes are saturated. #[inline(always)] pub fn sub_pm(a: Pm, b: Pm) -> (Pm, u64) { - add_pm(a, neg_pm(b)) + lib::sub_pm(a, b).into_saturated_parts() } // ------------------------------------------------------------------ scalar reference diff --git a/src/hpc/abakus/mod.rs b/src/hpc/abakus/mod.rs new file mode 100644 index 00000000..03ff4f6f --- /dev/null +++ b/src/hpc/abakus/mod.rs @@ -0,0 +1,10 @@ +//! Abakus: arithmetic over the Codec9 / DR512 representation. +//! +//! [`crate::hpc::codec9`] owns the representation (magnitude, presence, +//! scale, rounding, the never-touched sentinel). This module owns operations +//! on values already in that form, and their carry contract. +//! +//! **Experimental.** No stability guarantee; the API may change without a +//! deprecation period. + +pub mod pm; diff --git a/src/hpc/abakus/pm.rs b/src/hpc/abakus/pm.rs new file mode 100644 index 00000000..fc11c94e --- /dev/null +++ b/src/hpc/abakus/pm.rs @@ -0,0 +1,191 @@ +//! Signed `P × M` lanes added and subtracted in place, 64 at a time. +//! +//! A lane is a magnitude `M` (one byte of a [`U8x64`]) and a polarity bit `P` +//! (one bit of a `u64`), under the DR512 law: `P=0, M=0` is never touched, +//! `P=0, M>0` is `-M`, `P=1` is `+M` (so `P=1, M=0` is the touched `+0`). +//! +//! - [`add_pm`]: sign-magnitude addition. Same polarity adds the magnitudes; +//! opposite polarity takes the difference and the larger one's polarity. A +//! zero result is `+0` when either input was touched, and stays never +//! touched when neither was. +//! - [`neg_pm`]: flips the polarity on lanes with a magnitude, +//! `P_¬b = P_b ⊕ (M_b ≠ 0)`, so the never-touched code and `+0` are fixed +//! points and `-0` is never produced. +//! - [`sub_pm`]: `add_pm(a, neg_pm(b))`. There is no separate subtractor. +//! +//! **The carry contract.** A lane whose exact result is outside ±255 is a +//! carry lane. Its byte is saturated and is not the result. [`PmSum`] does +//! not hand its lanes out as a plain [`Pm`]: [`PmSum::lane`] reports a carry +//! lane as [`PmLane::Escaped`], and the raw bytes come only from +//! [`PmSum::into_saturated_parts`], whose name says what they are. The caller +//! applies the exact value of each carry lane through a wider path. +//! +//! Proven in `tests/add_pm.rs` (every 512 × 512 codeword pair against an +//! `i32` oracle, for both operations) on the AVX-512, AVX2, AVX, x86-64-v2, +//! NEON and wasm32 realizations. Experimental, see [`super`]. +use crate::simd::U8x64; + +/// 64 `P × M` lanes. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Pm { + /// Magnitude per lane. + pub mag: U8x64, + /// Polarity per lane; with a zero magnitude, the presence bit. + pub pos: u64, +} + +impl Pm { + /// Every lane never touched. + pub fn untouched() -> Self { + Pm { + mag: U8x64::splat(0), + pos: 0, + } + } +} + +/// Lanes that hold a value: `P=1`, or `M != 0`. +#[inline(always)] +pub fn touched(x: Pm) -> u64 { + x.pos | !x.mag.cmpeq_mask(U8x64::splat(0)) +} + +/// One lane of a [`PmSum`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum PmLane { + /// Neither input touched this lane. + NeverTouched, + /// The exact result, in `-255..=255`. + Exact(i16), + /// The exact result is outside ±255; the lane holds no value. + Escaped, +} + +/// The result of [`add_pm`] or [`sub_pm`]: 64 lanes and the carry mask. +#[must_use = "carry lanes hold no value; read them through `lane` or handle `carry`"] +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct PmSum { + lanes: Pm, + carry: u64, +} + +impl PmSum { + /// Lanes whose exact result is outside ±255. + pub fn carry(&self) -> u64 { + self.carry + } + + /// Lane `i` (`i < 64`). + pub fn lane(&self, i: usize) -> PmLane { + assert!(i < 64, "lane {i} out of range"); + if self.carry >> i & 1 == 1 { + return PmLane::Escaped; + } + let m = i16::from(self.lanes.mag.to_array()[i]); + match (self.lanes.pos >> i & 1 == 1, m) { + (false, 0) => PmLane::NeverTouched, + (false, m) => PmLane::Exact(-m), + (true, m) => PmLane::Exact(m), + } + } + + /// The lanes as a [`Pm`], when no lane carried. + pub fn exact(&self) -> Option { + (self.carry == 0).then_some(self.lanes) + } + + /// The raw lanes and the carry mask. On a carry lane the byte is + /// saturated at 255 with the inputs' polarity: it is not the result, and + /// the caller must replace it with the exact value. + pub fn into_saturated_parts(self) -> (Pm, u64) { + (self.lanes, self.carry) + } +} + +/// `a ⊕ b` lane-wise. See the module doc for the carry contract. +#[inline(always)] +pub fn add_pm(a: Pm, b: Pm) -> PmSum { + let zero = U8x64::splat(0); + let (ta, tb) = (touched(a), touched(b)); + let same = !(a.pos ^ b.pos); + // same polarity: saturating sum; carry where M_a > 255 - M_b + let sum = a.mag.saturating_add(b.mag); + let room = U8x64::splat(255).saturating_sub(b.mag); + let carry = same & ta & tb & a.mag.cmpgt_mask(room); + // opposite polarity: |M_a - M_b|, polarity of the larger magnitude + let hi = a.mag.simd_max(b.mag); + let lo = a.mag.simd_min(b.mag); + let diff = hi.saturating_sub(lo); + let a_larger = a.mag.cmpgt_mask(b.mag); + let p_opp = (a_larger & a.pos) | (!a_larger & b.pos); + let mag = U8x64::mask_blend(same, diff, sum); + let pos = (same & a.pos) | (!same & p_opp); + // A zero result is +0 when either input was touched. The never-touched + // code is a zero magnitude, so `untouched ⊕ x = x` needs no blend; only + // this normalization reads presence. + let pos = pos | (mag.cmpeq_mask(zero) & (ta | tb)); + PmSum { + lanes: Pm { mag, pos }, + carry, + } +} + +/// `-b` lane-wise: polarity flipped where the magnitude is non-zero. +#[inline(always)] +pub fn neg_pm(b: Pm) -> Pm { + let nonzero = !b.mag.cmpeq_mask(U8x64::splat(0)); + Pm { + mag: b.mag, + pos: b.pos ^ nonzero, + } +} + +/// `a ⊖ b` lane-wise: `add_pm(a, neg_pm(b))`. +#[inline(always)] +pub fn sub_pm(a: Pm, b: Pm) -> PmSum { + add_pm(a, neg_pm(b)) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn block(vals: &[Option]) -> Pm { + let mut mag = [0u8; 64]; + let mut pos = 0u64; + for (i, v) in vals.iter().enumerate() { + if let Some(v) = *v { + mag[i] = v.unsigned_abs() as u8; + pos |= u64::from(v >= 0) << i; + } + } + Pm { + mag: U8x64::from_array(mag), + pos, + } + } + + #[test] + fn lane_reports_never_touched_exact_and_escaped() { + let a = block(&[None, Some(-5), Some(200), Some(0)]); + let b = block(&[None, Some(5), Some(100), Some(0)]); + let s = add_pm(a, b); + assert_eq!(s.lane(0), PmLane::NeverTouched); + assert_eq!(s.lane(1), PmLane::Exact(0), "-5 + +5 = +0"); + assert_eq!(s.lane(2), PmLane::Escaped, "300 has no lane value"); + assert_eq!(s.lane(3), PmLane::Exact(0), "+0 + +0 = +0"); + assert_eq!(s.carry(), 1 << 2); + assert_eq!(s.exact(), None, "a carried sum is not exact"); + let (raw, carry) = s.into_saturated_parts(); + assert_eq!((raw.mag.to_array()[2], carry), (255, 1 << 2)); + } + + #[test] + fn exact_is_some_without_carry() { + let a = block(&[Some(10), Some(-20)]); + let s = sub_pm(a, a); + let e = s.exact().expect("no carry"); + assert_eq!(touched(e), 0b11, "x - x is a touched +0"); + assert_eq!(e.pos & 0b11, 0b11); + } +} diff --git a/src/hpc/mod.rs b/src/hpc/mod.rs index 14020cd9..6527fab2 100644 --- a/src/hpc/mod.rs +++ b/src/hpc/mod.rs @@ -49,6 +49,8 @@ pub mod quantized; pub mod codec8; /// Canonical DR512 numerical codec, with compile-time rounding and calibration. pub mod codec9; +/// Arithmetic over the Codec9 representation (experimental). +pub mod abakus; pub mod lapack; pub mod fft; pub mod vml;