Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .claude/blackboard.md
Original file line number Diff line number Diff line change
@@ -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 (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
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
Expand Down
90 changes: 90 additions & 0 deletions .claude/knowledge/add-pm-probe.md
Original file line number Diff line number Diff line change
@@ -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 (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 |
| `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.
5 changes: 5 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
74 changes: 74 additions & 0 deletions examples/add_pm/main.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
//! 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
// `Pm::untouched` and the reference helpers are used by tests/add_pm.rs.
#[allow(dead_code)]
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<Pm> {
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() {
if cfg!(debug_assertions) {
eprintln!("release build only");
return;
}
#[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);
}
}
121 changes: 121 additions & 0 deletions examples/add_pm/pm.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
//! `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.
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 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)
}

// ------------------------------------------------------------------ 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<i32> {
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<i32>, b: Option<i32>) -> (Option<i32>, 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,
)
}
Loading
Loading