diff --git a/.claude/blackboard.md b/.claude/blackboard.md index a418eb7e..9524709c 100644 --- a/.claude/blackboard.md +++ b/.claude/blackboard.md @@ -1,3 +1,207 @@ +## 2026-11-14 — RESULT: bit-plane and Abakus refresh (pre-registered below) + +Six refresh variants interleaved per sample (rotated order), median of 31 x +2,000, three runs per tier. AVX-512 run 2 was disturbed (half and full rows +inflated in every column); runs 1 and 3 quoted. ns per tile: + +| tier | tile | set bits | walk x1 (I32x16) | planes U64x8 | Abakus U64x8 | +|---|---|---|---|---|---| +| AVX-512 | empty | 0 | 36.2 to 36.6 | 2,110 to 2,130 | 2,118 to 2,513 | +| | 1/64 | 54 | 70.0 to 72.2 | 2,064 to 2,110 | 2,119 to 2,421 | +| | 1/2 | 2,027 | 1,584 to 1,624 | 2,127 to 2,187 | 2,177 to 2,775 | +| | 3/4 | 3,138 | 2,294 to 2,309 | 2,091 to 2,107 | 2,119 to 2,474 | +| | full | 4,096 | 2,780 to 3,262 | 2,115 to 2,521 | 2,485 to 2,605 | +| AVX2 | 1/2 | 2,027 | 1,694 to 2,568 | 6,135 to 8,454 | 4,693 to 6,271 | +| | full | 4,096 | 3,286 to 3,401 | 6,088 to 6,542 | 4,678 to 4,954 | + +- R1 exact: holds. Every single cell, empty, full, 200 random tiles, the + extreme uniform weights incl. negative and -1. Disables, each red: sign + plane added instead of subtracted (1 test), Abakus drops the sixteens + column (2), Abakus keeps the carry in its own column (2), planes skip the + upper 8 lanes (1). +- R2 density-independent within 10%: holds on AVX-512 (empty 2,110 to 2,130, + full 2,115 to 2,521 incl. the disturbed run) and AVX2. +- R3 planes below 1,000 ns at half density: FAILED, kill hit. Planes are + 2,127 to 2,187 ns, slower than the walk (0.74x to 0.85x). +- R4 planes lose at 1/64: holds, by about 30x. +- R5 Abakus no faster than planes on AVX-512: holds (0.79x to 1.00x). +- R6 Abakus faster than planes on AVX2: holds, 1.30x to 1.46x, every density. + +Crossover on AVX-512: planes beat the walk from about 3/4 density +(3/4: 1.10x; full: 1.29x to 1.31x in the undisturbed runs). On AVX2 the walk +wins at every density (planes 0.01x to 0.55x of the walk's speed). + +Why the planes cost what they cost (arithmetic, not measured per port): the +work is fixed at 16 planes x 64 words x 2 vectors = 2,048 `U64x8` +and+popcnt+add per refresh, i.e. all 4,096 cells x 16 lanes x 16 bits are +touched whether set or not; the walk touches one 32-byte row per SET bit. +The planes only pay off where most cells are set. + +Decision: keep both in the lab as measured alternatives. The walk stays the +reference refresh below about 3/4 density; on AVX-512 a dense tile could +switch to planes, which is a measured dispatch, not a replacement. The +Abakus counter is the better form wherever the vector popcount is emulated. + +## 2026-11-14 — PRE-REGISTRATION: D-U64X64-NNUE-1, bit-plane refresh (per-bit addressing) + +Instead of walking set bits and gathering weight rows, transpose the weights +into bit planes: `plane[b][k][j]` is a `u64` whose bit `r` is bit `b` of +`w[k][r][j]` (two's complement `i16`, `b < 16`). Then +`h[j] = bias[j] + Σ_{b<15} 2^b·n[b][j] − 2^15·n[15][j]`, with +`n[b][j] = Σ_k popcount(tile[k] & plane[b][k][j])`. The tile bit is read in +place as the address; no row is gathered. Planes are 131,072 B, the same +bytes as the weights, transposed once per weight set (not timed). + +Routes, both over `U64x8` (8 output lanes `j` per vector), no zero-word skip, +so the cost is independent of density: +- G-P1 `nnue_refresh_planes`: `n += popcnt(splat(tile[k]) & plane)`. +- G-P2 `nnue_refresh_abakus`: the Abakus column counter. Masks are added + into carry-save columns ones/twos/fours/eights/sixteens with the full-adder + law (`ternlog` 0x96 sum, 0xE8 carry: the carry moves to the adjacent + column), Harley-Seal over groups of 16 words; one popcount per column + at the end instead of one per word. + +Predictions: +- R1 exact: both equal the per-cell oracle on every corpus (incl. weights + with the sign bit set, i.e. negative weights). +- R2 G-P1 time is density-independent within 10% (empty vs full). +- R3 AVX-512 (vpopcntdq): G-P1 half tile below 1,000 ns, faster than the + gather walk x1 (1,560 ns). Kill: G-P1 slower than x1 at half density. +- R4 crossover: G-P1 loses to x1 at density 1/64 (54 set bits, ~60 ns). +- R5 AVX-512: G-P2 no faster than G-P1 (vpopcntq is one instruction, so + saving popcounts buys nothing). +- R6 AVX2 tier (config-v3, `U64x8::popcnt` is 8 scalar `count_ones`): G-P2 + faster than G-P1. Kill: G-P2 slower than G-P1 on AVX2. + +## 2026-11-14 — RESULT: multi-accumulator refresh (pre-registered below) — hypothesis FALSIFIED + +Same bench, four refresh variants interleaved per sample with a rotated +order, AVX-512, three runs (ns per tile, median of 31 x 2,000): + +| tile | set bits | x1 | x2 | x4 | +|---|---|---|---|---| +| empty | 0 | 18.3 to 19.1 | 49.8 to 64.9 | 66.1 to 68.5 | +| 1/2 | 2,027 | 1,559 to 1,562 | 1,616 to 1,620 | 2,510 to 2,512 | +| full | 4,096 | 2,785 to 2,804 | 3,077 to 3,098 | 4,773 to 4,813 | + +- Q1 exact: holds (both variants against the per-cell oracle on every corpus; + disable "simd2 drops the second accumulator" turns 2 tests red; the + single-cell tiles never reach the second accumulator). +- Q2 x2 at least 1.3x faster: FAILED, and the kill is hit: x2 is 0.96x of x1 + on the half tile, 0.90x on the full tile. The refresh is not latency-bound + on the add chain. +- Q3 x4 at most 1.15x faster than x2: holds trivially; x4 is 0.64x of x2. +- Q4 empty tile within 5 ns: FAILED, +31 to +46 ns for x2. + +Disassembly (objdump): the x1 inner loop is six instructions per set bit +(`tzcnt`, `shl`, `vpmovsxwd` from memory, `vpaddd`, `blsr`, `jne`); the value +carried between iterations is the bit mask through `blsr`, not only the sum. +x2 is 70 instructions with an extra branch per bit pair; x4 is 85 with its +accumulator array spilled (`vmovdqa` to and from the stack, `push`/`pop`). +What does bound x1 (the widening load's port, or one mispredicted branch at +each word end) is NOT measured; no hardware counters on this host. + +Kept in the lab as a recorded negative result; x1 stays the reference. + +## 2026-11-14 — PRE-REGISTRATION: D-U64X64-NNUE-1 follow-up, multi-accumulator refresh + +Hypothesis: refresh (about 0.77 ns per set bit, one `vpaddd` chain on one +`I32x16`) is latency-bound on that chain, not bound by loads or by the bit +walk. Variants, same weights and tile, sums added at the end: +- `nnue_refresh_simd2`: two `I32x16` accumulators; consecutive set bits of a + word alternate between them. +- `nnue_refresh_simd4`: four accumulators, same rule. + +Predictions (AVX-512, half-full tile, 2,027 set bits; baseline I32x16 1,555 ns): +- Q1 exact: both equal the per-cell oracle on every corpus route G uses. +- Q2 two accumulators: 1.3x to 2x faster than one. Kill (hypothesis wrong): + below 1.15x. +- Q3 four accumulators: no more than 1.15x faster than two (the add chain is + no longer the limit at two; loads of a 32-byte row per bit take over). +- Q4 empty tile: no slower than one accumulator by more than 5 ns (the extra + setup is three zero vectors and two adds). + +## 2026-11-14 — RESULT: D-U64X64-NNUE-1 (pre-registered below) + +Lab route G, `examples/u64x64/nnue.rs`; tests `tests/u64x64_nnue.rs` (10); +bench `cargo run --release --example u64x64_nnue --features std`. Tier read +from the binary: avx512f=true, avx512bw=true, avx512vpopcntdq=true. Units: +ns per tile or per update, median of 31 samples x 2,000 calls. + +| prediction | result | +|---|---| +| P1 exact on 4,096 single cells, empty, full, 200 random tiles | holds, all four routes against the per-cell `i64` oracle | +| P2 1,000 mixed updates match a refresh; undo returns the start | holds; 300+ updates turned cells on and off together | +| P3 no allocation in refresh or update | holds (per-thread counter, shown live) | +| P4 1-bit update ≥100x cheaper than a half-tile refresh | MISSED: 58x (26.6 ns vs 1,555 ns). The update scans all 64 words; that floor is about 18 to 23 ns, the cost of refreshing an empty tile | +| P4 8-bit update ≥20x; kill below 5x | holds: 37x scattered, 48x in one word | +| P5 `I32x16` refresh ≥2x scalar on a half tile; kill if slower | MISSED, kill not hit: 1.06x. LLVM compiles the scalar 16-lane add to the same `vpmovsxwd` + `vpaddd` (objdump), so both routes are SIMD on AVX-512 | +| P6 a tile is a set; a bag with a repeated edge differs | holds (pinned counterexample) | + +Refresh cost scales with set bits: 17.7 ns empty, 58.7 ns at 54 bits, 1,555 ns +at 2,027, 2,684 ns full (about 0.6 to 0.8 ns per set bit, one dependent add +per bit on one accumulator). Update, half-full tile: 1 bit 26.6 ns, 8 bits +42.6 ns scattered / 32.4 ns in one word, 64 bits 123.3 ns scattered / 54.3 ns +in one word; one cell toggled repeatedly 28.7 ns. + +Resident: weights 131,072 B (4,096 x 16 i16; fits L2, not L1), tile 512 B, +accumulator 64 B; scratch 0 B. + +Disable runs, all red: update forgets removals (3 tests), refresh skips bit 63 +(7), SIMD refresh drops the bias (5), row-order check removed (1), `i16::MIN` +admitted (1), update ignores word 0 (3). + +Not measured: AVX2, NEON, wasm and scalar tiers; two-accumulator refresh (the +per-bit cost looks latency-bound); a source with real FK fan-out. + +Haiku run: substrate-mapper over `examples/u64x64/` (11 files read in full). 2 items checked against source (`route_b.rs:387-389` text; `fixture.rs:360` `Weights`), 0 wrong; it self-corrected 2 of its own lines. Not relied on for any conclusion: the lab was also read directly. + +Side finding: `masked_group_count_u32` counts into the caller's `i64` with +`wrapping_add(1)`. Exact within one call (a wrap needs 2^63 rows) but a +caller that accumulates across calls inherits silent wrapping. + +## 2026-11-14 — PRE-REGISTRATION: D-U64X64-NNUE-1, an NNUE-style accumulator over a bound 64×64 Boolean tile + +Question: can a source-issued `BitTile` (`[u64; 64]`, 512 B, 4,096 cells, +word `k` = category, bit `r` = row; `examples/u64x64/fixture.rs`) drive an +exact, incrementally updatable weighted accumulator +`h[j] = bias[j] + Σ_{(k,r) set} w[k][r][j]`, `j < 16`? + +Kinds kept apart: a bit is presence (set semantics, no sign, no count); a +weight is a signed `i16`; the accumulator is `i32`. Bound: `|bias| <= 2^15` +and `|w| <= 2^15 - 1`, so `|h| < 2^15 + 4096·2^15 = 2^27 + 2^15`; no `i32` +overflow is possible, enforced by the weight constructor, not by wrapping. + +Routes (lab route G, `examples/u64x64/nnue.rs`; no public type, no `src/` edit): +- G-A oracle (test file only): every one of the 4,096 cells read with + `(word >> r) & 1`, sums in `i64`. +- G-B refresh: walk set bits (`trailing_zeros`), scalar `i32` adds. +- G-C update: `d = old ^ new`, `on = d & new`, `off = d & old`; add `on` + rows, subtract `off` rows. +- G-D refresh and update with `I32x16::from_i16_slice` + `Add`/`Sub` + (existing facade, no new primitive). +- Bound entry points take `fixture::Bound`; an update additionally refuses two + frames from different sources, shapes or row orders. Versions may differ: + an update is between versions. + +Predictions and kill conditions: +- P1 exact: G-B, G-C, G-D equal G-A on every single-cell tile (4,096), empty, + full, and 200 random tiles at densities 1/64, 1/4, 1/2, 3/4. Kill: any + mismatch. +- P2 update chains: 1,000 random toggles applied incrementally equal a fresh + refresh after every step; toggling back to the start returns the start + accumulator exactly. Kill: any mismatch. +- P3 no allocation inside refresh or update (counting allocator). Kill: any. +- P4 cost: refresh scales with set bits, update with changed bits. On a + half-full tile, a 1-bit update is at least 100× cheaper than a refresh and + an 8-bit update at least 20×. Kill: update not at least 5× cheaper than + refresh at 8 changed bits. +- P5 G-D refresh at least 2× faster than G-B on a half-full tile (AVX-512). + Kill: G-D slower than G-B. +- P6 multiplicity: a Boolean tile cannot carry repeated edges; a bag of + duplicate (k, r) edges gives `Σ c·w`, which the tile path does not equal. + This is a counterexample to pin, not a defect to fix. + ## 2026-11-14 — RESULT: power sums and extrema of a `u8` lane from per-code counts (pre-registered below) Functions: `masked_code_counts_u8`, `code_power_sums_u8` (`CodePowerSums`), `masked_first_row_of_code_u8`. diff --git a/Cargo.toml b/Cargo.toml index 4a73e0ab..33437a18 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -100,6 +100,11 @@ name = "u64x64" path = "examples/u64x64/main.rs" required-features = ["std"] +[[example]] +name = "u64x64_nnue" +path = "examples/u64x64/nnue_main.rs" +required-features = ["std"] + [[example]] name = "cpu_guard_probe" required-features = ["std"] diff --git a/examples/u64x64/nnue.rs b/examples/u64x64/nnue.rs new file mode 100644 index 00000000..34898020 --- /dev/null +++ b/examples/u64x64/nnue.rs @@ -0,0 +1,365 @@ +//! D-U64X64-NNUE-1 lab route G: an NNUE-style weighted accumulator over a +//! bound 64x64 Boolean tile. +//! +//! The tile is presence only: word `k` bit `r` set means cell `(k, r)` is in +//! the relation. A bit carries no sign and no count. Each cell owns a weight +//! row `w[k][r]` of `H = 16` signed `i16`s; the accumulator is `H` `i32`s: +//! `h = bias + Σ_{(k, r) set} w[k][r]`. +//! +//! Exact by bound, not by wrapping: [`CellWeights::new`] refuses `|bias| > 2^15` +//! and any weight equal to `i16::MIN`, so `|h| <= 2^15 + 4096 · (2^15 - 1)`, +//! which is below `2^28`. +//! +//! - [`refresh`] walks set bits with `trailing_zeros`; its work scales with +//! the set bits, not with 4,096. +//! - [`update`] takes `old ^ new`, adds the rows that turned on and subtracts +//! the rows that turned off; its work scales with the changed bits. It is +//! correct only when `acc` is the accumulator of `old`. +//! - `refresh_simd` / `update_simd` do the same with +//! `I32x16::from_i16_slice` and `Add` / `Sub`. +//! - [`refresh_bound`] / [`update_bound`] read `Source::present` through a +//! `fixture::Bound`. An update refuses two frames of different sources, +//! shapes or row orders; the versions may differ, because an update is +//! between versions. +//! +//! A Boolean tile is a set. It cannot hold two equal `(k, r)` edges, so a bag +//! of edges whose weights must count with multiplicity needs a count plane, +//! not this tile. +//! +//! Lab fixture only: no public type, no production caller. + +use crate::fixture::{BitTile, Bound, Refusal, Witness, F_PRESENT}; +use ndarray::simd::{I32x16, U64x8}; + +/// Accumulator width (one `I32x16`). +pub const H: usize = 16; +/// The accumulator: `H` exact `i32` sums. +pub type Acc = [i32; H]; +/// Largest admitted `|bias|`. +pub const BIAS_MAX: u32 = 1 << 15; + +/// One weight row per cell, plus a bias, admitted against the overflow bound. +pub struct CellWeights { + bias: Acc, + w: Box<[[[i16; H]; 64]]>, +} + +impl CellWeights { + /// `w[k][r]` is the row of cell `(k, r)`. Refuses a table that is not + /// 64 x 64 (`Shape`), a bias past `2^15` or a weight equal to `i16::MIN` + /// (`TooLarge`). + pub fn new(bias: Acc, w: Box<[[[i16; H]; 64]]>) -> Result { + if w.len() != 64 { + return Err(Refusal::Shape); + } + if bias.iter().any(|b| b.unsigned_abs() > BIAS_MAX) { + return Err(Refusal::TooLarge); + } + if w.iter().flatten().flatten().any(|&x| x == i16::MIN) { + return Err(Refusal::TooLarge); + } + Ok(CellWeights { bias, w }) + } + + pub fn bias(&self) -> Acc { + self.bias + } + + pub fn row(&self, k: usize, r: usize) -> &[i16; H] { + &self.w[k][r] + } +} + +#[inline(always)] +fn add_row(acc: &mut Acc, row: &[i16; H]) { + for j in 0..H { + acc[j] += i32::from(row[j]); + } +} + +#[inline(always)] +fn sub_row(acc: &mut Acc, row: &[i16; H]) { + for j in 0..H { + acc[j] -= i32::from(row[j]); + } +} + +/// `bias + Σ` of the rows of every set cell, scalar adds. +#[no_mangle] +#[inline(never)] +pub fn nnue_refresh(w: &CellWeights, tile: &BitTile) -> Acc { + let mut acc = w.bias; + for (k, &word) in tile.iter().enumerate() { + let mut m = word; + while m != 0 { + let r = m.trailing_zeros() as usize; + add_row(&mut acc, &w.w[k][r]); + m &= m - 1; + } + } + acc +} + +/// Move `acc` from the accumulator of `old` to that of `new`, scalar adds. +#[no_mangle] +#[inline(never)] +pub fn nnue_update(w: &CellWeights, acc: &mut Acc, old: &BitTile, new: &BitTile) { + for k in 0..64 { + let d = old[k] ^ new[k]; + if d == 0 { + continue; + } + let mut on = d & new[k]; + while on != 0 { + add_row(acc, &w.w[k][on.trailing_zeros() as usize]); + on &= on - 1; + } + let mut off = d & old[k]; + while off != 0 { + sub_row(acc, &w.w[k][off.trailing_zeros() as usize]); + off &= off - 1; + } + } +} + +/// [`nnue_refresh`] with one `I32x16` accumulator: each row is widened from +/// 16 `i16` with `from_i16_slice` and added. +#[no_mangle] +#[inline(never)] +pub fn nnue_refresh_simd(w: &CellWeights, tile: &BitTile) -> Acc { + let mut acc = I32x16::from_array(w.bias); + for (k, &word) in tile.iter().enumerate() { + let mut m = word; + while m != 0 { + acc += I32x16::from_i16_slice(&w.w[k][m.trailing_zeros() as usize]); + m &= m - 1; + } + } + acc.to_array() +} + +/// [`nnue_refresh_simd`] with two independent `I32x16` accumulators: +/// consecutive set bits of a word go to alternate accumulators, so two adds +/// are in flight instead of one dependent chain. The two are summed at the +/// end; the result is identical because integer addition is associative and +/// cannot overflow under the admitted bound. +#[no_mangle] +#[inline(never)] +pub fn nnue_refresh_simd2(w: &CellWeights, tile: &BitTile) -> Acc { + let mut a0 = I32x16::from_array(w.bias); + let mut a1 = I32x16::splat(0); + for (k, &word) in tile.iter().enumerate() { + let mut m = word; + while m != 0 { + a0 += I32x16::from_i16_slice(&w.w[k][m.trailing_zeros() as usize]); + m &= m - 1; + if m == 0 { + break; + } + a1 += I32x16::from_i16_slice(&w.w[k][m.trailing_zeros() as usize]); + m &= m - 1; + } + } + (a0 + a1).to_array() +} + +/// [`nnue_refresh_simd2`] with four accumulators, bits taken round-robin. +#[no_mangle] +#[inline(never)] +pub fn nnue_refresh_simd4(w: &CellWeights, tile: &BitTile) -> Acc { + let mut acc = [I32x16::from_array(w.bias), I32x16::splat(0), I32x16::splat(0), I32x16::splat(0)]; + for (k, &word) in tile.iter().enumerate() { + let mut m = word; + let mut lane = 0usize; + while m != 0 { + acc[lane & 3] += I32x16::from_i16_slice(&w.w[k][m.trailing_zeros() as usize]); + m &= m - 1; + lane += 1; + } + } + ((acc[0] + acc[1]) + (acc[2] + acc[3])).to_array() +} + +/// [`nnue_update`] with one `I32x16` accumulator. +#[no_mangle] +#[inline(never)] +pub fn nnue_update_simd(w: &CellWeights, acc: &mut Acc, old: &BitTile, new: &BitTile) { + let mut a = I32x16::from_array(*acc); + for k in 0..64 { + let d = old[k] ^ new[k]; + if d == 0 { + continue; + } + let mut on = d & new[k]; + while on != 0 { + a += I32x16::from_i16_slice(&w.w[k][on.trailing_zeros() as usize]); + on &= on - 1; + } + let mut off = d & old[k]; + while off != 0 { + a -= I32x16::from_i16_slice(&w.w[k][off.trailing_zeros() as usize]); + off &= off - 1; + } + } + *acc = a.to_array(); +} + +/// The weights transposed into bit planes: `p[b][k][j]` is a `u64` whose bit +/// `r` is bit `b` of `w[k][r][j]` read as two's complement. 16 planes x 64 +/// categories x `H` lanes x 8 bytes = 131,072 bytes, the same bytes as the +/// weights. Built once per weight set. +pub struct PlaneWeights { + bias: Acc, + p: Box<[[[u64; H]; 64]]>, +} + +impl PlaneWeights { + pub fn from(w: &CellWeights) -> Self { + let mut p = vec![[[0u64; H]; 64]; 16].into_boxed_slice(); + for b in 0..16 { + for k in 0..64 { + for j in 0..H { + let mut plane = 0u64; + for r in 0..64 { + let bit = (w.w[k][r][j] as u16 >> b) & 1; + plane |= u64::from(bit) << r; + } + p[b][k][j] = plane; + } + } + } + PlaneWeights { bias: w.bias, p } + } +} + +/// `h[j] = bias[j] + Σ_{b<15} 2^b n[b][j] − 2^15 n[15][j]`, the two's +/// complement weights of bit `b` (`b = 15` is the sign bit). Exact in `i64`; +/// the admitted bound puts the result in `i32`. +fn combine(bias: &Acc, n: &[[u64; H]; 16]) -> Acc { + let mut out = [0i32; H]; + for j in 0..H { + let mut h = i64::from(bias[j]); + for b in 0..15 { + h += (n[b][j] as i64) << b; + } + h -= (n[15][j] as i64) << 15; + out[j] = h as i32; + } + out +} + +/// Refresh by per-bit addressing: `n[b][j] = Σ_k popcount(tile[k] & +/// p[b][k][j])`, eight `j` per `U64x8`. No set bit is walked and no row is +/// gathered; every word of the tile is read, so the cost does not depend on +/// density. +#[no_mangle] +#[inline(never)] +pub fn nnue_refresh_planes(p: &PlaneWeights, tile: &BitTile) -> Acc { + let mut n = [[0u64; H]; 16]; + for b in 0..16 { + let mut c0 = U64x8::splat(0); + let mut c1 = U64x8::splat(0); + for k in 0..64 { + let t = U64x8::splat(tile[k]); + let row = &p.p[b][k]; + c0 += (t & U64x8::from_slice(&row[0..8])).popcnt(); + c1 += (t & U64x8::from_slice(&row[8..16])).popcnt(); + } + c0.copy_to_slice(&mut n[b][0..8]); + c1.copy_to_slice(&mut n[b][8..16]); + } + combine(&p.bias, &n) +} + +/// Carry-save adder over 8 lanes: `(sum, carry)` of three masks, the +/// `full_add_mask` law (`a ^ b ^ c`, majority) as one `ternlog` each. +#[inline(always)] +fn csa(a: U64x8, b: U64x8, c: U64x8) -> (U64x8, U64x8) { + (a.ternlog::<0x96>(b, c), a.ternlog::<0xE8>(b, c)) +} + +/// Σ popcount of 64 masks `tile[k] & row(k)` for one group of 8 lanes, as an +/// Abakus column counter: masks enter the ones column, carries move to the +/// adjacent column (twos, fours, eights, sixteens) by carry-save addition +/// (Harley-Seal over groups of 16), and each column is popcounted once. +#[inline(always)] +fn abakus_count(tile: &BitTile, rows: &[[u64; H]; 64], half: usize) -> U64x8 { + let z = U64x8::splat(0); + let x = |k: usize| U64x8::splat(tile[k]) & U64x8::from_slice(&rows[k][half * 8..half * 8 + 8]); + let (mut ones, mut twos, mut fours, mut eights) = (z, z, z, z); + let mut sixteens = z; + for g in 0..4 { + let k = g * 16; + let (o, ta) = csa(ones, x(k), x(k + 1)); + let (o, tb) = csa(o, x(k + 2), x(k + 3)); + let (t, fa) = csa(twos, ta, tb); + let (o, ta) = csa(o, x(k + 4), x(k + 5)); + let (o, tb) = csa(o, x(k + 6), x(k + 7)); + let (t, fb) = csa(t, ta, tb); + let (f, ea) = csa(fours, fa, fb); + let (o, ta) = csa(o, x(k + 8), x(k + 9)); + let (o, tb) = csa(o, x(k + 10), x(k + 11)); + let (t, fa) = csa(t, ta, tb); + let (o, ta) = csa(o, x(k + 12), x(k + 13)); + let (o, tb) = csa(o, x(k + 14), x(k + 15)); + let (t, fb) = csa(t, ta, tb); + let (f, eb) = csa(f, fa, fb); + let (e, s) = csa(eights, ea, eb); + ones = o; + twos = t; + fours = f; + eights = e; + sixteens += s.popcnt(); + } + let sh = |v: U64x8, by: u32| U64x8::from_array(v.to_array().map(|c| c << by)); + sh(sixteens, 4) + sh(eights.popcnt(), 3) + sh(fours.popcnt(), 2) + sh(twos.popcnt(), 1) + ones.popcnt() +} + +/// [`nnue_refresh_planes`] with the popcounts taken through the Abakus +/// column counter: about one popcount per 16 words instead of one per word. +#[no_mangle] +#[inline(never)] +pub fn nnue_refresh_abakus(p: &PlaneWeights, tile: &BitTile) -> Acc { + let mut n = [[0u64; H]; 16]; + for b in 0..16 { + abakus_count(tile, &p.p[b], 0).copy_to_slice(&mut n[b][0..8]); + abakus_count(tile, &p.p[b], 1).copy_to_slice(&mut n[b][8..16]); + } + combine(&p.bias, &n) +} + +/// The accumulator of a bound source's `present` tile. Refuses a frame +/// without the presence field. +pub fn refresh_bound(w: &CellWeights, b: &Bound<'_>) -> Result { + if b.witness.fields & F_PRESENT == 0 { + return Err(Refusal::Field); + } + Ok(nnue_refresh_simd(w, &b.src.present)) +} + +/// Two frames describe the same population: one source, one shape, one row +/// order. Versions are not compared. +fn same_population(a: &Witness, b: &Witness) -> Result<(), Refusal> { + if a.source_id != b.source_id { + return Err(Refusal::ForeignSource); + } + if a.rows != b.rows || a.cols != b.cols { + return Err(Refusal::Shape); + } + if a.row_order_hash != b.row_order_hash || a.row_order != b.row_order { + return Err(Refusal::RowOrder); + } + Ok(()) +} + +/// Move `acc` from `old`'s accumulator to `new`'s. Refuses frames of +/// different populations or without the presence field; on refusal `acc` is +/// untouched. +pub fn update_bound(w: &CellWeights, acc: &mut Acc, old: &Bound<'_>, new: &Bound<'_>) -> Result<(), Refusal> { + same_population(&old.witness, &new.witness)?; + if old.witness.fields & new.witness.fields & F_PRESENT == 0 { + return Err(Refusal::Field); + } + nnue_update_simd(w, acc, &old.src.present, &new.src.present); + Ok(()) +} diff --git a/examples/u64x64/nnue_main.rs b/examples/u64x64/nnue_main.rs new file mode 100644 index 00000000..1788cd6a --- /dev/null +++ b/examples/u64x64/nnue_main.rs @@ -0,0 +1,230 @@ +//! D-U64X64-NNUE-1 lab benchmark for route G (`nnue.rs`): full refresh +//! against incremental update, scalar against `I32x16`, on one bound +//! 64x64 tile. Exactness lives in `tests/u64x64_nnue.rs`; this binary only +//! re-checks parity once per workload before timing it. +//! +//! Run: `cargo run --release --example u64x64_nnue --features std`. +#![allow(dead_code)] +#![allow(clippy::needless_range_loop)] + +mod fixture; +mod harness; +mod nnue; + +use fixture::BitTile; +use harness::{assert_no_alloc, bb, measure, tier_line, timer_overhead}; +use nnue::*; + +#[global_allocator] +static A: harness::Counting = harness::Counting; + +fn xorshift(s: &mut u64) -> u64 { + *s ^= *s << 13; + *s ^= *s >> 7; + *s ^= *s << 17; + *s +} + +fn weights(seed: u64) -> CellWeights { + let mut s = seed | 1; + let mut w = vec![[[0i16; H]; 64]; 64].into_boxed_slice(); + for row in w.iter_mut().flatten().flatten() { + *row = ((xorshift(&mut s) % 65_535) as i32 - 32_767) as i16; + } + CellWeights::new([0; H], w).unwrap() +} + +fn tile(s: &mut u64, num: u64, den: u64) -> BitTile { + let mut t = [0u64; 64]; + for word in &mut t { + for r in 0..64 { + if xorshift(s) % den < num { + *word |= 1u64 << r; + } + } + } + t +} + +/// `n` distinct cells: scattered over the tile, or packed into word 17. +fn flips(s: &mut u64, n: usize, packed: bool) -> BitTile { + let mut t = [0u64; 64]; + if packed { + t[17] = if n == 64 { u64::MAX } else { (1u64 << n) - 1 }; + return t; + } + let mut placed = 0; + while placed < n { + let c = (xorshift(s) % 4096) as usize; + if t[c / 64] >> (c % 64) & 1 == 0 { + t[c / 64] |= 1u64 << (c % 64); + placed += 1; + } + } + t +} + +fn xor(a: &BitTile, b: &BitTile) -> BitTile { + let mut t = [0u64; 64]; + for k in 0..64 { + t[k] = a[k] ^ b[k]; + } + t +} + +fn popcount(t: &BitTile) -> u32 { + t.iter().map(|w| w.count_ones()).sum() +} + +const REPS: usize = 2_000; +const SAMPLES: usize = 31; + +fn main() { + println!("{}", tier_line()); + let oh = timer_overhead(SAMPLES); + println!("timer overhead: {:.2} ns per call", oh.median); + println!( + "resident: weights {} B (4,096 rows x {H} i16), tile 512 B, accumulator {} B; scratch 0 B", + 4096 * H * 2, + H * 4 + ); + let w = weights(0x9E37_79B9_7F4A_7C15); + let mut s = 0x1234_5678_9ABC_DEF1; + + let p = PlaneWeights::from(&w); + println!( + "\n## refresh (ns per tile, median of {SAMPLES} samples x {REPS} calls; the six variants interleaved per sample, order rotated)" + ); + println!( + "| tile | set bits | scalar walk | I32x16 x1 | I32x16 x2 | I32x16 x4 | planes U64x8 | Abakus U64x8 | x1 / planes | planes / Abakus |" + ); + println!("|---|---|---|---|---|---|---|---|---|---|"); + let mut half_refresh = (0.0, 0.0); + const V: usize = 6; + let run = |v: usize, t: &BitTile| -> Acc { + match v { + 0 => nnue_refresh(&w, t), + 1 => nnue_refresh_simd(&w, t), + 2 => nnue_refresh_simd2(&w, t), + 3 => nnue_refresh_simd4(&w, t), + 4 => nnue_refresh_planes(&p, t), + _ => nnue_refresh_abakus(&p, t), + } + }; + let time = |v: usize, t: &BitTile| -> f64 { + macro_rules! reps { + ($e:expr) => {{ + let t0 = std::time::Instant::now(); + for _ in 0..REPS { + bb($e); + } + t0.elapsed().as_nanos() as f64 / REPS as f64 + }}; + } + match v { + 0 => reps!(nnue_refresh(bb(&w), bb(t))), + 1 => reps!(nnue_refresh_simd(bb(&w), bb(t))), + 2 => reps!(nnue_refresh_simd2(bb(&w), bb(t))), + 3 => reps!(nnue_refresh_simd4(bb(&w), bb(t))), + 4 => reps!(nnue_refresh_planes(bb(&p), bb(t))), + _ => reps!(nnue_refresh_abakus(bb(&p), bb(t))), + } + }; + for (name, num, den) in + [("empty", 0, 1), ("1/64", 1, 64), ("1/4", 1, 4), ("1/2", 1, 2), ("3/4", 3, 4), ("full", 1, 1)] + { + let t = tile(&mut s, num, den); + for v in 1..V { + assert_eq!(run(0, &t), run(v, &t), "refresh parity, variant {v}"); + } + assert_no_alloc("refresh", || { + for v in 0..V { + bb(run(v, &t)); + } + }); + let mut samples = [[0f64; SAMPLES]; V]; + for sample in 0..SAMPLES { + for v in 0..V { + let v = (v + sample) % V; + samples[v][sample] = time(v, &t); + } + } + let med = samples.map(|x| harness::median(&x)); + if name == "1/2" { + half_refresh = (med[0], med[1]); + } + println!( + "| {name} | {} | {:.1} | {:.1} | {:.1} | {:.1} | {:.1} | {:.1} | {:.2} | {:.2} |", + popcount(&t), + med[0], + med[1], + med[2], + med[3], + med[4], + med[5], + med[1] / med[4], + med[4] / med[5] + ); + } + + println!("\n## update on a half-full tile (ns per update; one sample = {REPS} x (old->new, new->old), halved)"); + println!("| changed bits | placement | scalar | I32x16 | refresh / update (I32x16) |"); + println!("|---|---|---|---|---|"); + let base = tile(&mut s, 1, 2); + for (n, packed) in [(1, false), (8, false), (8, true), (64, false), (64, true)] { + let d = flips(&mut s, n, packed); + let next = xor(&base, &d); + let mut acc = nnue_refresh(&w, &base); + nnue_update_simd(&w, &mut acc, &base, &next); + assert_eq!(acc, nnue_refresh(&w, &next), "update parity"); + assert_no_alloc("update", || { + nnue_update(&w, &mut acc, &next, &base); + nnue_update_simd(&w, &mut acc, &base, &next); + }); + let mut a1 = nnue_refresh(&w, &base); + let a = measure( + REPS, + SAMPLES, + || {}, + || { + nnue_update(bb(&w), &mut a1, bb(&base), bb(&next)); + nnue_update(bb(&w), &mut a1, bb(&next), bb(&base)); + }, + ); + let mut a2 = nnue_refresh(&w, &base); + let b = measure( + REPS, + SAMPLES, + || {}, + || { + nnue_update_simd(bb(&w), &mut a2, bb(&base), bb(&next)); + nnue_update_simd(bb(&w), &mut a2, bb(&next), bb(&base)); + }, + ); + bb((a1, a2)); + let (us, ub) = (a.median / 2.0, b.median / 2.0); + println!( + "| {n} | {} | {us:.1} | {ub:.1} | {:.0} |", + if packed { "one word" } else { "scattered" }, + half_refresh.1 / ub + ); + } + + // one cell toggled over and over + let mut t = base; + let mut acc = nnue_refresh(&w, &t); + let r = measure( + REPS, + SAMPLES, + || {}, + || { + let mut next = t; + next[42] ^= 1u64 << 7; + nnue_update_simd(bb(&w), &mut acc, bb(&t), bb(&next)); + t = next; + }, + ); + assert_eq!(acc, nnue_refresh(&w, &t), "repeated toggle parity"); + println!("| 1 | same cell, repeated | - | {:.1} | {:.0} |", r.median, half_refresh.1 / r.median); + println!("\nhalf-tile refresh: scalar {:.1} ns, I32x16 {:.1} ns", half_refresh.0, half_refresh.1); +} diff --git a/tests/u64x64_nnue.rs b/tests/u64x64_nnue.rs new file mode 100644 index 00000000..f19b0848 --- /dev/null +++ b/tests/u64x64_nnue.rs @@ -0,0 +1,473 @@ +#![cfg(feature = "std")] +#![allow(dead_code)] +#![allow(clippy::needless_range_loop)] +//! D-U64X64-NNUE-1 exactness, refusals and allocation for lab route G +//! (`examples/u64x64/nnue.rs`), against an independent per-cell oracle. + +#[path = "../examples/u64x64/fixture.rs"] +mod fixture; +#[path = "../examples/u64x64/nnue.rs"] +mod nnue; + +use fixture::*; +use nnue::*; +use std::alloc::{GlobalAlloc, Layout, System}; +use std::cell::Cell; + +// ---------------------------------------------------------------- allocator + +/// Counts allocations per thread, so parallel tests do not see each other. +struct PerThread; + +thread_local! { + static ALLOCS: Cell = const { Cell::new(0) }; +} + +unsafe impl GlobalAlloc for PerThread { + unsafe fn alloc(&self, layout: Layout) -> *mut u8 { + ALLOCS.with(|c| c.set(c.get() + 1)); + // SAFETY: layout is passed through unchanged to System. + unsafe { System.alloc(layout) } + } + unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) { + // SAFETY: ptr/layout come from a matching System allocation. + unsafe { System.dealloc(ptr, layout) } + } + unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 { + ALLOCS.with(|c| c.set(c.get() + 1)); + // SAFETY: ptr/layout/new_size are passed through unchanged to System. + unsafe { System.realloc(ptr, layout, new_size) } + } +} + +#[global_allocator] +static A: PerThread = PerThread; + +fn allocs() -> usize { + ALLOCS.with(|c| c.get()) +} + +// ---------------------------------------------------------------- generators + +fn xorshift(s: &mut u64) -> u64 { + *s ^= *s << 13; + *s ^= *s >> 7; + *s ^= *s << 17; + *s +} + +/// CellWeights in the full admitted range `-(2^15 - 1) ..= 2^15 - 1`, bias in +/// `-2^15 ..= 2^15`. +fn weights(seed: u64) -> CellWeights { + let mut s = seed | 1; + let mut w = vec![[[0i16; H]; 64]; 64].into_boxed_slice(); + for k in 0..64 { + for r in 0..64 { + for j in 0..H { + let v = (xorshift(&mut s) % 65_535) as i32 - 32_767; + w[k][r][j] = v as i16; + } + } + } + let mut bias = [0i32; H]; + for b in &mut bias { + *b = (xorshift(&mut s) % 65_537) as i32 - 32_768; + } + CellWeights::new(bias, w).unwrap() +} + +/// Every weight equal to `v`, bias `b`. +fn uniform(v: i16, b: i32) -> CellWeights { + CellWeights::new([b; H], vec![[[v; H]; 64]; 64].into_boxed_slice()).unwrap() +} + +/// A tile where each cell is set with probability `num / den`. +fn tile(s: &mut u64, num: u64, den: u64) -> BitTile { + let mut t = [0u64; 64]; + for word in &mut t { + for r in 0..64 { + if xorshift(s) % den < num { + *word |= 1u64 << r; + } + } + } + t +} + +/// A mask of exactly `n` distinct random cells. +fn cells(s: &mut u64, n: usize) -> BitTile { + let mut t = [0u64; 64]; + let mut placed = 0; + while placed < n { + let c = (xorshift(s) % 4096) as usize; + if t[c / 64] >> (c % 64) & 1 == 0 { + t[c / 64] |= 1u64 << (c % 64); + placed += 1; + } + } + t +} + +fn xor(a: &BitTile, b: &BitTile) -> BitTile { + let mut t = [0u64; 64]; + for k in 0..64 { + t[k] = a[k] ^ b[k]; + } + t +} + +// ---------------------------------------------------------------- oracle + +/// Independent oracle: all 4,096 cells, one bit at a time, sums in `i64`. +/// No `trailing_zeros`, no XOR, no SIMD. +fn oracle(w: &CellWeights, t: &BitTile) -> [i64; H] { + let mut acc = [0i64; H]; + for j in 0..H { + acc[j] = i64::from(w.bias()[j]); + } + for k in 0..64 { + for r in 0..64 { + if (t[k] >> r) & 1 == 1 { + let row = w.row(k, r); + for j in 0..H { + acc[j] += i64::from(row[j]); + } + } + } + } + acc +} + +fn widen(a: &Acc) -> [i64; H] { + let mut out = [0i64; H]; + for j in 0..H { + out[j] = i64::from(a[j]); + } + out +} + +/// Every route on `t`: both refreshes, and both updates from the empty tile. +fn check_all(w: &CellWeights, t: &BitTile, what: &str) { + let want = oracle(w, t); + assert_eq!(widen(&nnue_refresh(w, t)), want, "{what}: refresh"); + assert_eq!(widen(&nnue_refresh_simd(w, t)), want, "{what}: refresh_simd"); + assert_eq!(widen(&nnue_refresh_simd2(w, t)), want, "{what}: refresh_simd2"); + assert_eq!(widen(&nnue_refresh_simd4(w, t)), want, "{what}: refresh_simd4"); + let empty = [0u64; 64]; + let mut a = w.bias(); + nnue_update(w, &mut a, &empty, t); + assert_eq!(widen(&a), want, "{what}: update from empty"); + let mut b = w.bias(); + nnue_update_simd(w, &mut b, &empty, t); + assert_eq!(widen(&b), want, "{what}: update_simd from empty"); +} + +// ---------------------------------------------------------------- P1 + +#[test] +fn every_single_cell_matches_the_oracle() { + let w = weights(0x9E37_79B9_7F4A_7C15); + let full = [u64::MAX; 64]; + for c in 0..4096 { + let mut t = [0u64; 64]; + t[c / 64] = 1u64 << (c % 64); + check_all(&w, &t, &format!("cell {c}")); + // removing the one cell from the full tile, both directions + let mut rest = full; + rest[c / 64] &= !(1u64 << (c % 64)); + let mut a = nnue_refresh(&w, &full); + nnue_update(&w, &mut a, &full, &rest); + assert_eq!(widen(&a), oracle(&w, &rest), "cell {c}: full minus one"); + nnue_update_simd(&w, &mut a, &rest, &full); + assert_eq!(widen(&a), oracle(&w, &full), "cell {c}: and back"); + } +} + +#[test] +fn empty_full_and_random_tiles_match_the_oracle() { + let w = weights(7); + check_all(&w, &[0u64; 64], "empty"); + check_all(&w, &[u64::MAX; 64], "full"); + let mut s = 0x1234_5678_9ABC_DEF1; + for (num, den) in [(1, 64), (1, 4), (1, 2), (3, 4)] { + for i in 0..50 { + let t = tile(&mut s, num, den); + check_all(&w, &t, &format!("density {num}/{den} #{i}")); + } + } +} + +/// The overflow bound is tight in both directions and still exact. +#[test] +fn the_extreme_admitted_weights_stay_exact() { + for (v, b) in [(i16::MAX, 1 << 15), (-i16::MAX, -(1 << 15))] { + let w = uniform(v, b); + let full = [u64::MAX; 64]; + let want = i64::from(b) + 4096 * i64::from(v); + assert!(want.unsigned_abs() < 1 << 28, "bound claimed in the module doc"); + assert_eq!(nnue_refresh(&w, &full), [want as i32; H]); + assert_eq!(nnue_refresh_simd(&w, &full), [want as i32; H]); + assert_eq!(nnue_refresh_simd2(&w, &full), [want as i32; H]); + assert_eq!(nnue_refresh_simd4(&w, &full), [want as i32; H]); + } +} + +#[test] +fn weights_outside_the_bound_are_refused() { + let mut w = vec![[[0i16; H]; 64]; 64].into_boxed_slice(); + w[17][33][5] = i16::MIN; + assert_eq!(CellWeights::new([0; H], w).err(), Some(Refusal::TooLarge)); + let ok = vec![[[0i16; H]; 64]; 64].into_boxed_slice(); + assert!(CellWeights::new([1 << 15; H], ok.clone()).is_ok()); + assert!(CellWeights::new([-(1 << 15); H], ok.clone()).is_ok()); + let mut bias = [0; H]; + bias[3] = (1 << 15) + 1; + assert_eq!(CellWeights::new(bias, ok).err(), Some(Refusal::TooLarge)); + let short = vec![[[0i16; H]; 64]; 63].into_boxed_slice(); + assert_eq!(CellWeights::new([0; H], short).err(), Some(Refusal::Shape)); +} + +// ---------------------------------------------------------------- P2 + +/// 1,000 updates of 1, 8 or 64 changed cells, mixed on and off, each checked +/// against a fresh refresh; then every change undone in reverse returns the +/// starting accumulator exactly. +#[test] +fn update_chains_match_a_fresh_refresh_and_undo_exactly() { + let w = weights(99); + let mut s = 0xDEAD_BEEF_CAFE_F00D; + let start = tile(&mut s, 1, 2); + let start_acc = nnue_refresh(&w, &start); + let mut cur = start; + let mut acc = start_acc; + let mut acc_simd = start_acc; + let mut history = Vec::new(); + let mut both_ways = 0; + for step in 0..1000 { + let n = [1, 8, 64][step % 3]; + let flip = cells(&mut s, n); + let next = xor(&cur, &flip); + if (0..64).any(|k| flip[k] & cur[k] != 0) && (0..64).any(|k| flip[k] & !cur[k] != 0) { + both_ways += 1; + } + nnue_update(&w, &mut acc, &cur, &next); + nnue_update_simd(&w, &mut acc_simd, &cur, &next); + let want = oracle(&w, &next); + assert_eq!(widen(&acc), want, "step {step}"); + assert_eq!(widen(&acc_simd), want, "step {step} simd"); + history.push(cur); + cur = next; + } + assert!(both_ways > 300, "updates must turn cells on and off together: {both_ways}"); + for prev in history.into_iter().rev() { + nnue_update(&w, &mut acc, &cur, &prev); + nnue_update_simd(&w, &mut acc_simd, &cur, &prev); + cur = prev; + } + assert_eq!(cur, start); + assert_eq!(acc, start_acc); + assert_eq!(acc_simd, start_acc); +} + +/// Toggling one cell twice is the identity; the same cell many times in a +/// row stays exact. +#[test] +fn repeated_toggles_of_one_cell_return_to_the_start() { + let w = weights(5); + let mut s = 11; + let t0 = tile(&mut s, 1, 4); + let a0 = nnue_refresh(&w, &t0); + let mut a = a0; + let mut t = t0; + for i in 0..101 { + let mut next = t; + next[42] ^= 1u64 << 7; + nnue_update(&w, &mut a, &t, &next); + t = next; + assert_eq!(widen(&a), oracle(&w, &t), "toggle {i}"); + } + assert_ne!(t, t0, "an odd number of toggles leaves the cell flipped"); + assert_ne!(a, a0); +} + +// ---------------------------------------------------------------- P3 + +#[test] +fn refresh_and_update_do_not_allocate() { + let w = weights(3); + let mut s = 21; + let old = tile(&mut s, 1, 2); + let new = tile(&mut s, 1, 2); + let mut acc = nnue_refresh(&w, &old); + let before = allocs(); + let a = nnue_refresh(&w, &new); + let b = nnue_refresh_simd(&w, &new); + nnue_update(&w, &mut acc, &old, &new); + nnue_update_simd(&w, &mut acc, &new, &old); + let after = allocs(); + assert_eq!(after, before, "allocations inside refresh or update"); + assert_eq!(a, b); + // the counter is live: an allocation in this thread moves it + let v = std::hint::black_box(vec![0u8; 64]); + assert!(allocs() > after, "the allocation counter must count"); + drop(v); +} + +// ---------------------------------------------------------------- frames + +fn source_with(id: u64, t: &BitTile) -> Source { + let mut s = Source::blank(id); + s.present = *t; + s +} + +#[test] +fn a_bound_frame_refreshes_and_updates_across_versions() { + let w = weights(8); + let mut seed = 31; + let old_src = source_with(4, &tile(&mut seed, 1, 2)); + let mut new_src = old_src.bumped(); + new_src.set_present(9, 9, !(old_src.present[9] >> 9 & 1 == 1)); + new_src.set_present(63, 63, !(old_src.present[63] >> 63 & 1 == 1)); + let old = bind(&old_src, &Expect::of(&old_src)).unwrap(); + let new = bind(&new_src, &Expect::of(&new_src)).unwrap(); + let mut acc = refresh_bound(&w, &old).unwrap(); + assert_eq!(widen(&acc), oracle(&w, &old_src.present)); + update_bound(&w, &mut acc, &old, &new).unwrap(); + assert_eq!(widen(&acc), oracle(&w, &new_src.present)); + // the old frame still binds to its own expectation; only a consumer + // expecting the old version is refused the new frame + assert!(bind(&old_src, &Expect::of(&old_src)).is_ok()); + assert_eq!(bind(&new_src, &Expect::of(&old_src)).err(), Some(Refusal::Stale)); +} + +#[test] +fn incompatible_frames_are_refused_and_leave_the_accumulator_untouched() { + let w = weights(9); + let mut seed = 41; + let a_src = source_with(1, &tile(&mut seed, 1, 2)); + let a = bind(&a_src, &Expect::of(&a_src)).unwrap(); + let start = refresh_bound(&w, &a).unwrap(); + + let foreign_src = source_with(2, &tile(&mut seed, 1, 2)); + let foreign = bind(&foreign_src, &Expect::of(&foreign_src)).unwrap(); + + let mut reordered_src = a_src.bumped(); + reordered_src.row_order.swap(0, 1); + let reordered = bind(&reordered_src, &Expect::of(&reordered_src)).unwrap(); + + let short_witness = Witness { rows: 63, ..a.witness }; + let short = Bound { + src: &a_src, + witness: short_witness, + }; + + let blind_src = a_src.without_field(F_PRESENT); + let blind = bind( + &blind_src, + &Expect { + fields: F_STOCK, + ..Expect::of(&blind_src) + }, + ) + .unwrap(); + + for (other, why) in [ + (&foreign, Refusal::ForeignSource), + (&reordered, Refusal::RowOrder), + (&short, Refusal::Shape), + (&blind, Refusal::Field), + ] { + let mut acc = start; + assert_eq!(update_bound(&w, &mut acc, &a, other), Err(why)); + assert_eq!(acc, start, "{why:?}: accumulator changed on refusal"); + } + assert_eq!(refresh_bound(&w, &blind), Err(Refusal::Field)); +} + +// ---------------------------------------------------------------- P6 + +/// A Boolean tile is a set. A bag of edges with a repeated `(k, r)` weighs +/// that cell once per edge; the tile weighs it once. Equal only without +/// repeats. +#[test] +fn a_tile_drops_multiplicity_that_a_bag_of_edges_keeps() { + let w = weights(12); + let bag_sum = |edges: &[(usize, usize)]| -> [i64; H] { + let mut acc = widen(&w.bias()); + for &(k, r) in edges { + for j in 0..H { + acc[j] += i64::from(w.row(k, r)[j]); + } + } + acc + }; + let to_tile = |edges: &[(usize, usize)]| -> BitTile { + let mut t = [0u64; 64]; + for &(k, r) in edges { + t[k] |= 1u64 << r; + } + t + }; + let distinct = [(0, 0), (5, 63), (63, 1)]; + assert_eq!(widen(&nnue_refresh(&w, &to_tile(&distinct))), bag_sum(&distinct)); + let repeated = [(0, 0), (5, 63), (5, 63), (63, 1)]; + assert_ne!( + widen(&nnue_refresh(&w, &to_tile(&repeated))), + bag_sum(&repeated), + "the tile must not be read as carrying the repeated edge" + ); + assert_eq!(to_tile(&repeated), to_tile(&distinct)); +} + +// ---------------------------------------------------------------- bit planes + +/// Both bit-plane routes against the oracle, planes built once per weight +/// set: every single cell, empty, full, random tiles, and the extreme +/// uniform weights (sign bit set and clear). +#[test] +fn plane_routes_match_the_oracle() { + let w = weights(0x51DE_C0DE); + let p = PlaneWeights::from(&w); + let check = |t: &BitTile, what: &str| { + let want = oracle(&w, t); + assert_eq!(widen(&nnue_refresh_planes(&p, t)), want, "{what}: planes"); + assert_eq!(widen(&nnue_refresh_abakus(&p, t)), want, "{what}: abakus"); + }; + for c in 0..4096 { + let mut t = [0u64; 64]; + t[c / 64] = 1u64 << (c % 64); + check(&t, &format!("cell {c}")); + } + check(&[0u64; 64], "empty"); + check(&[u64::MAX; 64], "full"); + let mut s = 0xFEED_FACE_0BAD_F00D; + for (num, den) in [(1, 64), (1, 4), (1, 2), (3, 4), (63, 64)] { + for i in 0..40 { + let t = tile(&mut s, num, den); + check(&t, &format!("density {num}/{den} #{i}")); + } + } + for (v, b) in [(i16::MAX, 1 << 15), (-i16::MAX, -(1 << 15)), (-1, 0), (1, -1)] { + let wu = uniform(v, b); + let pu = PlaneWeights::from(&wu); + let full = [u64::MAX; 64]; + let want = (i64::from(b) + 4096 * i64::from(v)) as i32; + assert_eq!(nnue_refresh_planes(&pu, &full), [want; H], "uniform {v}"); + assert_eq!(nnue_refresh_abakus(&pu, &full), [want; H], "uniform {v} abakus"); + } +} + +/// A column count that needs every Abakus column: 64 equal set words give +/// counts up to 64 per lane group (sixteens column reached four times). +#[test] +fn the_abakus_counter_reaches_its_top_column() { + let w = uniform(1, 0); + let p = PlaneWeights::from(&w); + let full = [u64::MAX; 64]; + // every lane j counts 4096 set bits at plane b = 0 + assert_eq!(nnue_refresh_abakus(&p, &full), [4096; H]); + let mut t = [0u64; 64]; + t[63] = 1; + assert_eq!(nnue_refresh_abakus(&p, &t), [1; H], "only the last word"); +}