From 896e0720057d35be4c2ce2a8ba01ef54022a61fa Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 04:41:49 +0000 Subject: [PATCH 1/5] examples/add_pm: P x M lanes added in place, carry as the exact escape (D-ADD-PM lab) Sign-magnitude addition of Codec9 / DR512 lanes 64 at a time on the U8x64 facade, with no decode to a signed integer: untouched is the identity, a touched zero is +0, and the same-polarity lanes whose sum passes 255 come back as a carry mask instead of saturating silently. Tests: every 512 x 512 codeword pair against an i32 oracle, equality with the decode path, associativity off the carry lanes, and a fold that escapes carry lanes into a wide tally and stays exact. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XAqKMNZqKXSaeb9g2ypywF --- Cargo.toml | 5 ++ examples/add_pm/main.rs | 66 +++++++++++++++ examples/add_pm/pm.rs | 112 +++++++++++++++++++++++++ tests/add_pm.rs | 182 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 365 insertions(+) create mode 100644 examples/add_pm/main.rs create mode 100644 examples/add_pm/pm.rs create mode 100644 tests/add_pm.rs diff --git a/Cargo.toml b/Cargo.toml index 33437a18..9f7f275e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -80,6 +80,11 @@ name = "pof_antennas" path = "examples/pof_antennas/main.rs" required-features = ["std"] +[[example]] +name = "add_pm" +path = "examples/add_pm/main.rs" +required-features = ["std"] + [[example]] name = "u9_abacus" path = "examples/u9_abacus/main.rs" diff --git a/examples/add_pm/main.rs b/examples/add_pm/main.rs new file mode 100644 index 00000000..7f6dff9c --- /dev/null +++ b/examples/add_pm/main.rs @@ -0,0 +1,66 @@ +//! D-ADD-PM: cost of adding `P × M` lanes in place (`add_pm`) against +//! decode → i32 → encode (`add_decoded`), per 64 lanes. Correctness lives in +//! `tests/add_pm.rs`; this only times the two paths on the host tier. +//! +//! cargo run --release --example add_pm --features std +mod pm; + +use std::hint::black_box; +use std::time::Instant; + +use ndarray::simd::U8x64; +use pm::{add_decoded, add_pm, Pm}; + +fn blocks(n: usize, seed: u64) -> Vec { + let mut s = seed; + (0..n) + .map(|_| { + let mut mag = [0u8; 64]; + for m in &mut mag { + s ^= s << 13; + s ^= s >> 7; + s ^= s << 17; + *m = (s % 160) as u8; + } + s ^= s << 13; + s ^= s >> 7; + s ^= s << 17; + Pm { mag: U8x64::from_array(mag), pos: s } + }) + .collect() +} + +fn time(name: &str, a: &[Pm], b: &[Pm], f: fn(Pm, Pm) -> (Pm, u64)) { + let reps = 50; + let mut best = f64::MAX; + for _ in 0..reps { + let t = Instant::now(); + let mut acc = 0u64; + for (x, y) in a.iter().zip(b) { + let (s, c) = f(black_box(*x), black_box(*y)); + acc ^= s.pos ^ c; + black_box(s.mag); + } + black_box(acc); + best = best.min(t.elapsed().as_nanos() as f64 / a.len() as f64); + } + println!("{name}: {best:.2} ns per 64 lanes (best of {reps})"); +} + +fn main() { + assert!(!cfg!(debug_assertions), "release build only"); + #[cfg(target_arch = "x86_64")] + println!( + "# avx2={} avx512f={} avx512bw={} (runtime); built avx512bw={}", + std::arch::is_x86_feature_detected!("avx2"), + std::arch::is_x86_feature_detected!("avx512f"), + std::arch::is_x86_feature_detected!("avx512bw"), + cfg!(target_feature = "avx512bw") + ); + let n = 4096; // 4096 blocks = 256 KiB of magnitudes per operand: L2-resident + let (a, b) = (blocks(n, 0x1234_5678), blocks(n, 0x8765_4321)); + for _ in 0..2 { + time("add_pm (in place)", &a, &b, add_pm); + time("add_decoded (decode -> i32 -> encode)", &a, &b, add_decoded); + } +} diff --git a/examples/add_pm/pm.rs b/examples/add_pm/pm.rs new file mode 100644 index 00000000..7977e00d --- /dev/null +++ b/examples/add_pm/pm.rs @@ -0,0 +1,112 @@ +//! `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; +//! - 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. +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. +#[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 mut pos = (same & a.pos) | (!same & p_opp); + // a touched zero is +0 + pos |= mag.cmpeq_mask(zero); + // untouched is the identity: where b is untouched take a, where a is take b + let mag = U8x64::mask_blend(!tb, mag, a.mag); + let pos = (tb & pos) | (!tb & a.pos); + let mag = U8x64::mask_blend(!ta, mag, b.mag); + let pos = (ta & pos) | (!ta & b.pos); + (Pm { mag, pos }, carry) +} + +// ------------------------------------------------------------------ scalar reference +// Decode to i32 and back: the path `add_pm` avoids, and the oracle it is checked by. + +/// One lane's value: `None` = never touched. +pub fn decode_lane(m: u8, p: bool) -> Option { + match (p, m) { + (false, 0) => None, + (false, m) => Some(-i32::from(m)), + (true, m) => Some(i32::from(m)), + } +} + +/// A touched value in ±255 to its lane; zero is `+0`. +pub fn encode_lane(v: i32) -> (u8, bool) { + assert!((-255..=255).contains(&v), "out of range: {v}"); + (v.unsigned_abs() as u8, v >= 0) +} + +/// The reference sum of one lane: value (or never touched) and overflow. +pub fn add_ref(a: Option, b: Option) -> (Option, bool) { + match (a, b) { + (None, x) | (x, None) => (x, false), + (Some(x), Some(y)) => (Some(x + y), (x + y).abs() > 255), + } +} + +/// `add_pm` by decode → i32 → encode, 64 lanes. Carry lanes are saturated. +pub fn add_decoded(a: Pm, b: Pm) -> (Pm, u64) { + let (am, bm) = (a.mag.to_array(), b.mag.to_array()); + let mut mag = [0u8; 64]; + let (mut pos, mut carry) = (0u64, 0u64); + for i in 0..64 { + let x = decode_lane(am[i], a.pos >> i & 1 == 1); + let y = decode_lane(bm[i], b.pos >> i & 1 == 1); + let (s, over) = add_ref(x, y); + if let Some(v) = s { + let (m, p) = encode_lane(v.clamp(-255, 255)); + mag[i] = m; + pos |= u64::from(p) << i; + } + carry |= u64::from(over) << i; + } + (Pm { mag: U8x64::from_array(mag), pos }, carry) +} diff --git a/tests/add_pm.rs b/tests/add_pm.rs new file mode 100644 index 00000000..0df11e50 --- /dev/null +++ b/tests/add_pm.rs @@ -0,0 +1,182 @@ +#![cfg(feature = "std")] +//! Exactness of the `add_pm` probe (`examples/add_pm/pm.rs`): `P × M` lanes +//! added in place against a decode-to-i32 oracle. + +#[path = "../examples/add_pm/pm.rs"] +mod pm; + +use ndarray::simd::U8x64; +use pm::{add_decoded, add_pm, add_ref, decode_lane, touched, Pm}; + +fn lane(x: Pm, i: usize) -> Option { + decode_lane(x.mag.to_array()[i], x.pos >> i & 1 == 1) +} + +/// Codeword `c` in 0..512: magnitude `c & 255`, presence bit 8. +fn block_of(codes: &[u16]) -> Pm { + let mut mag = [0u8; 64]; + let mut pos = 0u64; + for (i, &c) in codes.iter().enumerate() { + mag[i] = (c & 0xff) as u8; + pos |= u64::from(c >> 8 & 1) << i; + } + Pm { mag: U8x64::from_array(mag), pos } +} + +/// Every (a, b) codeword pair, 64 per block. +fn all_pairs() -> Vec<(Pm, Pm, Vec<(u16, u16)>)> { + let pairs: Vec<(u16, u16)> = (0..512u16).flat_map(|a| (0..512u16).map(move |b| (a, b))).collect(); + pairs + .chunks(64) + .map(|c| { + let a: Vec = c.iter().map(|p| p.0).collect(); + let b: Vec = c.iter().map(|p| p.1).collect(); + (block_of(&a), block_of(&b), c.to_vec()) + }) + .collect() +} + +#[test] +fn every_codeword_pair_matches_the_i32_oracle() { + let (mut over, mut checked) = (0usize, 0usize); + for (a, b, codes) in all_pairs() { + let (s, carry) = add_pm(a, b); + for i in 0..codes.len() { + let (want, overflow) = add_ref(lane(a, i), lane(b, i)); + assert_eq!(carry >> i & 1 == 1, overflow, "carry, codes {:?}", codes[i]); + checked += 1; + if overflow { + over += 1; + let m = s.mag.to_array()[i]; + assert_eq!(m, 255, "a carry lane saturates"); + // polarity of the inputs (both inputs share it on a carry) + assert_eq!(lane(s, i).map(i32::signum), want.map(i32::signum), "{:?}", codes[i]); + } else { + assert_eq!(lane(s, i), want, "codes {:?}", codes[i]); + } + } + } + assert_eq!(checked, 512 * 512); + // exactly the touched same-polarity pairs with |a| + |b| > 255 + let expect: usize = (1..=255i32) + .flat_map(|x| (1..=255i32).map(move |y| usize::from(x + y > 255))) + .sum::() + * 2; + assert_eq!(over, expect, "carry count"); + assert!(over > 0); +} + +#[test] +fn never_touched_comes_out_only_of_two_never_touched_inputs() { + for (a, b, _) in all_pairs() { + let (s, _) = add_pm(a, b); + assert_eq!(touched(s), touched(a) | touched(b)); + } +} + +#[test] +fn a_touched_zero_is_plus_zero() { + // -5 + +5, +0 + +0, -255 + +255 + let a = block_of(&[5, 0x100, 255]); + let b = block_of(&[0x105, 0x100, 0x1ff]); + let (s, carry) = add_pm(a, b); + assert_eq!(carry, 0); + for i in 0..3 { + assert_eq!(s.mag.to_array()[i], 0); + assert_eq!(s.pos >> i & 1, 1, "lane {i} must be +0, not the never-touched code"); + } +} + +#[test] +fn add_pm_equals_the_decode_path_on_every_pair() { + for (a, b, _) in all_pairs() { + assert_eq!(add_pm(a, b), add_decoded(a, b)); + } +} + +struct Rng(u64); +impl Rng { + fn next(&mut self) -> u64 { + self.0 ^= self.0 << 13; + self.0 ^= self.0 >> 7; + self.0 ^= self.0 << 17; + self.0 + } + fn block(&mut self, max: u16) -> Pm { + let codes: Vec = (0..64) + .map(|_| { + let m = (self.next() % (u64::from(max) + 1)) as u16; + let p = (self.next() & 1) as u16; + // a quarter never touched + if self.next() % 4 == 0 { 0 } else { m | p << 8 } + }) + .collect(); + block_of(&codes) + } +} + +#[test] +fn addition_is_associative_where_nothing_carries() { + let mut r = Rng(0x9E37_79B9_7F4A_7C15); + let mut compared = 0usize; + for _ in 0..20_000 { + let (a, b, c) = (r.block(255), r.block(255), r.block(255)); + let (ab, k1) = add_pm(a, b); + let (ab_c, k2) = add_pm(ab, c); + let (bc, k3) = add_pm(b, c); + let (a_bc, k4) = add_pm(a, bc); + let clean = !(k1 | k2 | k3 | k4); + for i in 0..64 { + if clean >> i & 1 == 1 { + assert_eq!(lane(ab_c, i), lane(a_bc, i)); + compared += 1; + } + } + } + assert!(compared > 100_000, "anti-vacuity: {compared} lanes compared"); +} + +/// The escape in use: fold a stream of delta blocks into one lane block; +/// carry lanes move their exact sum into a wide tally and restart untouched. +/// The result must equal an i64 sum of the decoded stream. +#[test] +fn a_fold_with_the_carry_escape_is_exact() { + let mut r = Rng(0xC0DE_C9C9_0000_0001); + let mut acc = Pm::untouched(); + let mut wide = [0i64; 64]; + let mut truth = [None::; 64]; + let mut escapes = 0usize; + for _ in 0..5_000 { + let d = r.block(200); + for i in 0..64 { + if let Some(v) = lane(d, i) { + *truth[i].get_or_insert(0) += i64::from(v); + } + } + let (s, carry) = add_pm(acc, d); + if carry != 0 { + for i in 0..64 { + if carry >> i & 1 == 1 { + let (x, y) = (lane(acc, i).unwrap(), lane(d, i).unwrap()); + wide[i] += i64::from(x + y); + escapes += 1; + } + } + } + // carry lanes restart touched at +0: their value now lives in `wide` + let mut mag = s.mag.to_array(); + let mut pos = s.pos; + for i in 0..64 { + if carry >> i & 1 == 1 { + mag[i] = 0; + pos |= 1 << i; + } + } + acc = Pm { mag: U8x64::from_array(mag), pos }; + } + for i in 0..64 { + let got = lane(acc, i).map(|v| i64::from(v) + wide[i]); + assert_eq!(got, truth[i], "lane {i}"); + } + assert!(escapes > 0, "anti-vacuity: the stream must overflow"); +} From e9f9f878ad016dcacddb24e0141703b573b4c8d0 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 04:42:18 +0000 Subject: [PATCH 2/5] examples/add_pm: drop the identity blends; gate the +0 normalization on presence The never-touched code is a zero magnitude, so untouched + x = x is the sign-magnitude addition itself (a disable run removing the identity step stayed green, because the step was dead). Only the zero-to-+0 rule needs presence: two never-touched inputs must stay never touched. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XAqKMNZqKXSaeb9g2ypywF --- examples/add_pm/pm.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/examples/add_pm/pm.rs b/examples/add_pm/pm.rs index 7977e00d..5ce078e2 100644 --- a/examples/add_pm/pm.rs +++ b/examples/add_pm/pm.rs @@ -7,7 +7,8 @@ //! 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; +//! 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; @@ -55,14 +56,13 @@ pub fn add_pm(a: Pm, b: Pm) -> (Pm, u64) { 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 mut pos = (same & a.pos) | (!same & p_opp); - // a touched zero is +0 - pos |= mag.cmpeq_mask(zero); - // untouched is the identity: where b is untouched take a, where a is take b - let mag = U8x64::mask_blend(!tb, mag, a.mag); - let pos = (tb & pos) | (!tb & a.pos); - let mag = U8x64::mask_blend(!ta, mag, b.mag); - let pos = (ta & pos) | (!ta & b.pos); + 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) } From 6c209f33662145879c52505b9bcaae3463f81908 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 04:43:42 +0000 Subject: [PATCH 3/5] add_pm: knowledge doc and blackboard result (D-ADD-PM) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XAqKMNZqKXSaeb9g2ypywF --- .claude/blackboard.md | 15 ++++++ .claude/knowledge/add-pm-probe.md | 90 +++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 .claude/knowledge/add-pm-probe.md diff --git a/.claude/blackboard.md b/.claude/blackboard.md index 9524709c..a30cd448 100644 --- a/.claude/blackboard.md +++ b/.claude/blackboard.md @@ -1,3 +1,18 @@ +## 2026-11-15 — RESULT: D-ADD-PM, Codec9 `P × M` lanes added in place + +`examples/add_pm/` + `tests/add_pm.rs`; doc `.claude/knowledge/add-pm-probe.md`. +Sign-magnitude addition of DR512 lanes on the `U8x64` facade, no decode: +untouched is the identity (no blend needed: the never-touched code is a zero +magnitude), a touched zero is +0, same-polarity sums past 255 return in a +carry mask. All 512 × 512 pairs exact against an i32 oracle (64,770 carry +pairs), bit-identical to the decode path, associative off the carry lanes, +and a carry-escaped fold is exact. Disables D1–D4 each red. Cost per 64 +lanes: AVX-512 11.9 ns vs 89.7 ns decode; AVX2 285 ns vs 134 ns, because the +AVX2 `U8x64` `mask_blend` / `saturating_add` / `saturating_sub` are scalar +loops (facet-stride burn-down). Verdict ADOPT-LAB; nothing added to `codec9` +or the facade. Loose ends: the AVX2 burn-down, the lance-graph end-to-end +fold, subtraction. + ## 2026-11-14 — RESULT: bit-plane and Abakus refresh (pre-registered below) Six refresh variants interleaved per sample (rotated order), median of 31 x diff --git a/.claude/knowledge/add-pm-probe.md b/.claude/knowledge/add-pm-probe.md new file mode 100644 index 00000000..37caffdd --- /dev/null +++ b/.claude/knowledge/add-pm-probe.md @@ -0,0 +1,90 @@ +# D-ADD-PM: Codec9 `P × M` lanes added in place + +READ BY: savant-architect, vector-synthesis, simd-savant, the DR512 / Codec9 +owner. Follows `dr512-epistemic-pm-invariant.md` (the law) and +`u9-abacus-probe.md` (D: carry escalation into a wider tally). + +Probe: `examples/add_pm/` (`pm.rs` holds the arithmetic, `main.rs` times it). +Correctness: `tests/add_pm.rs`. Facade words only; no backend, facade or +`codec9` change. + +```sh +cargo test --release --test add_pm --features std +cargo run --release --example add_pm --features std +``` + +## Question + +Can signed deltas in DR512 form (one `u8` magnitude + one presence bit per +lane; `P=0, M=0` never touched) be added without decoding to a signed +integer, keep the never-touched state, and report overflow instead of +saturating? + +## The operation + +`add_pm(a, b) -> (lanes, carry)` over 64 lanes, sign-magnitude: + +- same polarity: `M = sat(M_a + M_b)`, `P = P_a`; carry where `M_a > 255 - M_b`; +- opposite polarity: `M = max - min`, `P` of the larger magnitude; +- a zero result is `+0` when either input was touched; two never-touched + inputs stay never touched. + +Words: `saturating_add`, `saturating_sub`, `simd_max`, `simd_min`, +`cmpgt_mask` (unsigned), `cmpeq_mask`, one `mask_blend`, and `u64` mask +logic. No shuffle, no `u8`/`i8` crossing. + +**Finding:** no identity blend is needed. The never-touched code is a zero +magnitude, so `untouched ⊕ x = x` is the sign-magnitude addition itself. A +disable run that removed the first version's identity step stayed green; the +step was dead and is gone. Presence matters in exactly one place: the +zero-to-+0 normalization must not fire when both inputs were untouched. + +The carry mask is the exact escape Codec9's encoder does not have (it +saturates silently, as D-XLOG-C9-0 measured in lance-graph): the caller adds +the carry lanes' exact sum through a wider tally, which is D's carry +escalation. + +## Correctness (all green) + +| test | what | +|---|---| +| `every_codeword_pair_matches_the_i32_oracle` | all 512 × 512 pairs; carry count = exactly the touched same-polarity pairs with \|a\|+\|b\| > 255 (64,770) | +| `never_touched_comes_out_only_of_two_never_touched_inputs` | touched(out) = touched(a) \| touched(b), all pairs | +| `a_touched_zero_is_plus_zero` | −5 + +5, +0 + +0, −255 + +255 give `P=1, M=0` | +| `add_pm_equals_the_decode_path_on_every_pair` | bit-identical to decode → i32 → encode | +| `addition_is_associative_where_nothing_carries` | 20,000 random triple blocks, > 100,000 lanes compared | +| `a_fold_with_the_carry_escape_is_exact` | 5,000-block fold, carry lanes escaped to a wide tally, equals the i64 sum | + +Disable controls, each red: +D1 no zero-to-+0 normalization (5 tests); +D2 normalization not gated on presence (3); +D3 saturated sum treated as exact, carry forced 0 (4); +D4 opposite polarity takes the smaller magnitude's sign (4). + +## Cost (ns per 64 lanes, best of 50, 4,096 blocks, L2-resident) + +| tier | `add_pm` | decode → i32 → encode | +|---|---|---| +| AVX-512 (default `target-cpu=native`, built `avx512bw=true`) | 11.8 – 11.9 | 89.7 | +| AVX2 (`--config .cargo/config-v3.toml`, built `avx512bw=false`) | 284.7 – 285.3 | 133.5 – 134.7 | + +On AVX-512 the in-place sum is about 7.5x the decode path. On AVX2 it is +about 2x SLOWER, and not because of the algebra: the AVX2 `U8x64` is +array-backed, and its `mask_blend`, `saturating_add` and `saturating_sub` are +per-byte scalar loops (`src/simd_avx2.rs`, the 81 array-backed AVX2 hits of +the 2026-10-27 facet-stride audit). The AVX2 number measures that facade +gap. Same host for both rows; the AVX2 row is the v3 build on an AVX-512 +machine, not AVX2 silicon. + +## Verdict + +ADOPT-LAB as the signed-delta operand shape: exact, presence-preserving, and +the carry is the escape. Not adopted into `codec9` or the facade. + +## Open + +- Burn down the AVX2 array-backed `U8x64` words this uses; then re-time. +- End to end in lance-graph: fold the triangle-pairing delta stream + (D-XLOG-C9-0) with `add_pm` and check the carry lanes equal its escape lanes. +- Only addition is covered. Subtraction is addition with the polarity bit + flipped on touched lanes (an untouched lane must stay untouched); not built. From 1d26ed4da5218e215020993803613769391d2ab4 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 04:44:19 +0000 Subject: [PATCH 4/5] add_pm: clippy and fmt Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XAqKMNZqKXSaeb9g2ypywF --- examples/add_pm/main.rs | 12 ++++++++++-- examples/add_pm/pm.rs | 13 +++++++++++-- tests/add_pm.rs | 26 +++++++++++++++++++++----- 3 files changed, 42 insertions(+), 9 deletions(-) diff --git a/examples/add_pm/main.rs b/examples/add_pm/main.rs index 7f6dff9c..32db27c4 100644 --- a/examples/add_pm/main.rs +++ b/examples/add_pm/main.rs @@ -3,6 +3,8 @@ //! `tests/add_pm.rs`; this only times the two paths on the host tier. //! //! cargo run --release --example add_pm --features std +// `Pm::untouched` and the reference helpers are used by tests/add_pm.rs. +#[allow(dead_code)] mod pm; use std::hint::black_box; @@ -25,7 +27,10 @@ fn blocks(n: usize, seed: u64) -> Vec { s ^= s << 13; s ^= s >> 7; s ^= s << 17; - Pm { mag: U8x64::from_array(mag), pos: s } + Pm { + mag: U8x64::from_array(mag), + pos: s, + } }) .collect() } @@ -48,7 +53,10 @@ fn time(name: &str, a: &[Pm], b: &[Pm], f: fn(Pm, Pm) -> (Pm, u64)) { } fn main() { - assert!(!cfg!(debug_assertions), "release build only"); + if cfg!(debug_assertions) { + eprintln!("release build only"); + return; + } #[cfg(target_arch = "x86_64")] println!( "# avx2={} avx512f={} avx512bw={} (runtime); built avx512bw={}", diff --git a/examples/add_pm/pm.rs b/examples/add_pm/pm.rs index 5ce078e2..5d1b5b64 100644 --- a/examples/add_pm/pm.rs +++ b/examples/add_pm/pm.rs @@ -29,7 +29,10 @@ pub struct Pm { impl Pm { /// Every lane never touched. pub fn untouched() -> Self { - Pm { mag: U8x64::splat(0), pos: 0 } + Pm { + mag: U8x64::splat(0), + pos: 0, + } } } @@ -108,5 +111,11 @@ pub fn add_decoded(a: Pm, b: Pm) -> (Pm, u64) { } carry |= u64::from(over) << i; } - (Pm { mag: U8x64::from_array(mag), pos }, carry) + ( + Pm { + mag: U8x64::from_array(mag), + pos, + }, + carry, + ) } diff --git a/tests/add_pm.rs b/tests/add_pm.rs index 0df11e50..e96f89df 100644 --- a/tests/add_pm.rs +++ b/tests/add_pm.rs @@ -1,4 +1,5 @@ #![cfg(feature = "std")] +#![allow(clippy::needless_range_loop)] //! Exactness of the `add_pm` probe (`examples/add_pm/pm.rs`): `P × M` lanes //! added in place against a decode-to-i32 oracle. @@ -20,12 +21,20 @@ fn block_of(codes: &[u16]) -> Pm { mag[i] = (c & 0xff) as u8; pos |= u64::from(c >> 8 & 1) << i; } - Pm { mag: U8x64::from_array(mag), pos } + Pm { + mag: U8x64::from_array(mag), + pos, + } } /// Every (a, b) codeword pair, 64 per block. -fn all_pairs() -> Vec<(Pm, Pm, Vec<(u16, u16)>)> { - let pairs: Vec<(u16, u16)> = (0..512u16).flat_map(|a| (0..512u16).map(move |b| (a, b))).collect(); +/// A block pair and the codeword pair of each of its lanes. +type PairBlock = (Pm, Pm, Vec<(u16, u16)>); + +fn all_pairs() -> Vec { + let pairs: Vec<(u16, u16)> = (0..512u16) + .flat_map(|a| (0..512u16).map(move |b| (a, b))) + .collect(); pairs .chunks(64) .map(|c| { @@ -108,7 +117,11 @@ impl Rng { let m = (self.next() % (u64::from(max) + 1)) as u16; let p = (self.next() & 1) as u16; // a quarter never touched - if self.next() % 4 == 0 { 0 } else { m | p << 8 } + if self.next().is_multiple_of(4) { + 0 + } else { + m | p << 8 + } }) .collect(); block_of(&codes) @@ -172,7 +185,10 @@ fn a_fold_with_the_carry_escape_is_exact() { pos |= 1 << i; } } - acc = Pm { mag: U8x64::from_array(mag), pos }; + acc = Pm { + mag: U8x64::from_array(mag), + pos, + }; } for i in 0..64 { let got = lane(acc, i).map(|v| i64::from(v) + wide[i]); From 4209a04ef78e349781cf034cdc667d999b5cdb77 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 04:44:29 +0000 Subject: [PATCH 5/5] add_pm: correct the carry-pair count (65,280) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XAqKMNZqKXSaeb9g2ypywF --- .claude/blackboard.md | 2 +- .claude/knowledge/add-pm-probe.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/blackboard.md b/.claude/blackboard.md index a30cd448..f2265e69 100644 --- a/.claude/blackboard.md +++ b/.claude/blackboard.md @@ -4,7 +4,7 @@ Sign-magnitude addition of DR512 lanes on the `U8x64` facade, no decode: untouched is the identity (no blend needed: the never-touched code is a zero magnitude), a touched zero is +0, same-polarity sums past 255 return in a -carry mask. All 512 × 512 pairs exact against an i32 oracle (64,770 carry +carry mask. All 512 × 512 pairs exact against an i32 oracle (65,280 = 2 × 32,640 carry pairs), bit-identical to the decode path, associative off the carry lanes, and a carry-escaped fold is exact. Disables D1–D4 each red. Cost per 64 lanes: AVX-512 11.9 ns vs 89.7 ns decode; AVX2 285 ns vs 134 ns, because the diff --git a/.claude/knowledge/add-pm-probe.md b/.claude/knowledge/add-pm-probe.md index 37caffdd..af25b8ab 100644 --- a/.claude/knowledge/add-pm-probe.md +++ b/.claude/knowledge/add-pm-probe.md @@ -48,7 +48,7 @@ escalation. | test | what | |---|---| -| `every_codeword_pair_matches_the_i32_oracle` | all 512 × 512 pairs; carry count = exactly the touched same-polarity pairs with \|a\|+\|b\| > 255 (64,770) | +| `every_codeword_pair_matches_the_i32_oracle` | all 512 × 512 pairs; carry count = exactly the touched same-polarity pairs with \|a\|+\|b\| > 255 (65,280 = 2 × 32,640) | | `never_touched_comes_out_only_of_two_never_touched_inputs` | touched(out) = touched(a) \| touched(b), all pairs | | `a_touched_zero_is_plus_zero` | −5 + +5, +0 + +0, −255 + +255 give `P=1, M=0` | | `add_pm_equals_the_decode_path_on_every_pair` | bit-identical to decode → i32 → encode |