diff --git a/.claude/knowledge/add-pm-probe.md b/.claude/knowledge/add-pm-probe.md index 7b800324..2649e0ff 100644 --- a/.claude/knowledge/add-pm-probe.md +++ b/.claude/knowledge/add-pm-probe.md @@ -84,10 +84,10 @@ never flipped (3); flipped only on zero magnitudes (4). AVX-512 (native), AVX2 (`config-v3`), AVX (`config-avx`, qemu SandyBridge), x86-64-v2 / scalar backend (`config-v2`, qemu Nehalem), NEON (aarch64 cross build, qemu), wasm32 +simd128 and wasm32 scalar (wasip1 under node's WASI). -CI runs the first five rows through `scripts/add-pm-backends.sh`, which fails -on zero executed tests. The wasm rows ran once by hand: the crate's -`criterion` dev-dependency does not build for `wasm32-wasip1`, so they were -built from a copy of the test file in a crate without dev-dependencies. +CI runs all seven rows through `scripts/add-pm-backends.sh`, which fails on +zero executed tests. The wasm rows (`wasm`, `wasm-scalar`) run the test +binary under node's WASI (`scripts/wasi-test-run.mjs`); `criterion`, which +does not build for `wasm32-wasip1`, is a non-wasm dev-dependency. ## Cost (ns per 64 lanes, best of 50, 4,096 blocks, L2-resident) @@ -128,8 +128,8 @@ the carry is the escape. Not adopted into `codec9` or the facade. - ~~Only addition is covered. Subtraction is addition with the polarity bit flipped on touched lanes (an untouched lane must stay untouched); not built.~~ Done: § Subtraction (the flip is on lanes with a magnitude, which keeps +0 too). -- Promote `add_pm` / `neg_pm` / `sub_pm` from this example to an experimental - `ndarray::hpc::abakus::pm` module (Codec9 keeps the representation), then - drop the lab copy in lance-graph `xlog-relcomp-probe`. -- wasm rows of `scripts/add-pm-backends.sh`: blocked on `criterion` not - building for `wasm32-wasip1`. +- Done: promoted to `ndarray::hpc::abakus::pm` (#433); the lance-graph lab + copy is gone (lance-graph #2090). +- Done: wasm rows of `scripts/add-pm-backends.sh` in CI. +- Done: `Codec9::encode_touched_checked` hands back the exact value past + ±255 (`Quantized9::Wide`), so input has the same escape as arithmetic. diff --git a/.claude/knowledge/dr512-epistemic-pm-invariant.md b/.claude/knowledge/dr512-epistemic-pm-invariant.md index e39960d6..120363f2 100644 --- a/.claude/knowledge/dr512-epistemic-pm-invariant.md +++ b/.claude/knowledge/dr512-epistemic-pm-invariant.md @@ -14,6 +14,20 @@ or DT64 production dispatch. | 1 | 0 | valid **+0** | | 1 | 1..255 | positive numeric value +1..+255 | +**What "DR512" names (DECISION, 2026-11-15).** The *representation*: 512 +counts codewords (511 values plus never touched). It does not count positions +or register bits, and it is unrelated to lance-graph's DR64/DR256 (position +counts) and to `dt64::dr` (addressing, which holds no value). The *arithmetic* +over these lanes is Abakus `pm` (`ndarray::hpc::abakus::pm`: `add_pm`, +`neg_pm`, `sub_pm`); call it that, not "DR512 arithmetic". Elsewhere, "DR512" +is always qualified ("DR512 lanes", "the DR512 codeword"). + +**Never touched is an identity in arithmetic and NaN after decoding.** +`add_pm(⊥, x) = x`, while `Codec9::decode(⊥)` is `NaN`, and NaN absorbs. So +`decode(add_pm(⊥, +5)) = 5`, but `decode(⊥) + decode(+5) = NaN`. Sum in the +lanes first, then decode. The difference is deliberate, and a test in +`ndarray::hpc::abakus::pm` pins it. + One u8 magnitude plus **one** presence bit per numeric row: 64 magnitudes + one u64 presence word = 72 bytes per 64 rows; 512 distinct codewords, exactly 511 signed numeric values and one diff --git a/.github/workflows/simd-matrix.yaml b/.github/workflows/simd-matrix.yaml index e621192e..0a485d66 100644 --- a/.github/workflows/simd-matrix.yaml +++ b/.github/workflows/simd-matrix.yaml @@ -411,6 +411,11 @@ jobs: run: bash scripts/masking-parity.sh wasm-scalar - name: masking parity (wasm, +simd128 +relaxed-simd) run: bash scripts/masking-parity.sh wasm-relaxed + - run: rustup target add wasm32-wasip1 + - name: add_pm / sub_pm probe tests (wasm32-wasip1, +simd128, node WASI) + run: bash scripts/add-pm-backends.sh wasm + - name: add_pm / sub_pm probe tests (wasm32-wasip1, scalar, node WASI) + run: bash scripts/add-pm-backends.sh wasm-scalar nightly: # The `core::simd` realization behind the opt-in `nightly-simd` feature. diff --git a/Cargo.toml b/Cargo.toml index 9f7f275e..eb9de081 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -395,6 +395,11 @@ quickcheck = { workspace = true } approx = { workspace = true, default-features = true } itertools = { workspace = true } ndarray-gen = { workspace = true } + +# Benches only. Not built for wasm32 (criterion does not compile there), so +# `cargo test --test --target wasm32-wasip1` builds the test it names +# (scripts/add-pm-backends.sh wasm, wasm-scalar). +[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies] criterion = { version = "0.5", features = ["html_reports"] } [[bench]] diff --git a/scripts/add-pm-backends.sh b/scripts/add-pm-backends.sh index 936ad214..88041f4d 100755 --- a/scripts/add-pm-backends.sh +++ b/scripts/add-pm-backends.sh @@ -7,10 +7,12 @@ # scripts/add-pm-backends.sh avx-qemu sandybridge build, qemu -cpu SandyBridge # scripts/add-pm-backends.sh v2-qemu x86-64-v2 build (scalar backend), qemu -cpu Nehalem # scripts/add-pm-backends.sh neon-qemu aarch64 cross build, qemu-aarch64 +# scripts/add-pm-backends.sh wasm wasm32-wasip1 +simd128 (simd_wasm), node WASI +# scripts/add-pm-backends.sh wasm-scalar wasm32-wasip1 without simd128 (scalar), node WASI # # A run that executes zero tests is a failure: the file is gated on `std`. set -euo pipefail -ARM="${1:?avx2|avx-qemu|v2-qemu|neon-qemu}" +ARM="${1:?avx2|avx-qemu|v2-qemu|neon-qemu|wasm|wasm-scalar}" export CARGO_PROFILE_DEV_DEBUG=0 CARGO_PROFILE_TEST_DEBUG=0 build() { # $1 = cargo config file or "", rest = test args; prints the test binary local cfg=(); [ -n "$1" ] && cfg=(--config "$1"); shift @@ -25,6 +27,14 @@ case "$ARM" in export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc bin=$(build "" --target aarch64-unknown-linux-gnu) run=(qemu-aarch64-static -L /usr/aarch64-linux-gnu "$bin") ;; + wasm|wasm-scalar) + # RUSTFLAGS selects the realization here, as in masking-parity.sh: with + # +simd128 simd.rs picks simd_wasm, without it the scalar backend. + flags=""; [ "$ARM" = wasm ] && flags="-C target-feature=+simd128" + bin=$(RUSTFLAGS="$flags" cargo test --release --features std --test add_pm --no-run \ + --target wasm32-wasip1 --message-format=json \ + | jq -r 'select(.executable != null and .target.name == "add_pm") | .executable') + run=(node scripts/wasi-test-run.mjs "$bin") ;; *) echo "unknown arm: $ARM" >&2; exit 2 ;; esac [ -n "$bin" ] || { echo "::error::no add_pm test binary built" >&2; exit 1; } diff --git a/scripts/wasi-test-run.mjs b/scripts/wasi-test-run.mjs new file mode 100644 index 00000000..8009c8ba --- /dev/null +++ b/scripts/wasi-test-run.mjs @@ -0,0 +1,11 @@ +// Runs a Rust test binary built for wasm32-wasip1 under node's WASI, single +// threaded (wasm32-wasip1 has no threads). Exit code: the test binary's. +// +// node scripts/wasi-test-run.mjs target/wasm32-wasip1/release/deps/add_pm-*.wasm +import { readFile } from 'node:fs/promises'; +import { WASI } from 'node:wasi'; + +const wasi = new WASI({ version: 'preview1', args: ['test', '--test-threads=1'], env: {}, preopens: {} }); +const module = await WebAssembly.compile(await readFile(process.argv[2])); +const instance = await WebAssembly.instantiate(module, wasi.getImportObject()); +process.exitCode = wasi.start(instance); diff --git a/src/hpc/abakus/pm.rs b/src/hpc/abakus/pm.rs index fc11c94e..58834a1a 100644 --- a/src/hpc/abakus/pm.rs +++ b/src/hpc/abakus/pm.rs @@ -20,13 +20,20 @@ //! [`PmSum::into_saturated_parts`], whose name says what they are. The caller //! applies the exact value of each carry lane through a wider path. //! +//! **Never touched is an identity here, and NaN after decoding.** +//! `add_pm(never_touched, x)` is `x`, but [`Codec9::decode`] turns never +//! touched into `NaN`, which absorbs: `decode(add_pm(⊥, +5))` is `5` while +//! `decode(⊥) + decode(+5)` is `NaN`. Add in the lanes, then decode. +//! +//! [`Codec9::decode`]: crate::hpc::codec9::Codec9::decode +//! //! 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)] +#[derive(Clone, Copy, Debug)] pub struct Pm { /// Magnitude per lane. pub mag: U8x64, @@ -34,6 +41,14 @@ pub struct Pm { pub pos: u64, } +// Compared by bytes, not derived: not every realization's `U8x64` is +// `PartialEq` (the `nightly-simd` one is not). +impl PartialEq for Pm { + fn eq(&self, other: &Self) -> bool { + self.pos == other.pos && self.mag.to_array() == other.mag.to_array() + } +} + impl Pm { /// Every lane never touched. pub fn untouched() -> Self { @@ -150,6 +165,24 @@ pub fn sub_pm(a: Pm, b: Pm) -> PmSum { mod tests { use super::*; + /// Never touched is the identity of `add_pm`, and NaN once decoded: the + /// order "add, then decode" is not the order "decode, then add". + #[test] + fn never_touched_is_an_identity_before_decode_and_nan_after() { + use crate::hpc::codec8::TiesEven; + use crate::hpc::codec9::{Codec9Runtime, EpiLane9}; + let c = Codec9Runtime::::new(1.0).unwrap(); + let five = c.encode_touched(5.0).unwrap(); + let sum = add_pm(block(&[None]), block(&[Some(5)])); + assert_eq!(sum.lane(0), PmLane::Exact(5)); + let (s, _) = sum.into_saturated_parts(); + let lane = EpiLane9::from_codeword(u16::from(s.mag.to_array()[0]) | (u16::from(s.pos & 1 == 1) << 8)).unwrap(); + assert_eq!(c.decode(lane), 5.0, "add, then decode"); + assert_eq!(lane, five); + let decoded_first = c.decode(EpiLane9::NEVER_TOUCHED) + c.decode(five); + assert!(decoded_first.is_nan(), "decode, then add"); + } + fn block(vals: &[Option]) -> Pm { let mut mag = [0u8; 64]; let mut pos = 0u64; diff --git a/src/hpc/codec9.rs b/src/hpc/codec9.rs index 0e22907c..bee0ecd8 100644 --- a/src/hpc/codec9.rs +++ b/src/hpc/codec9.rs @@ -133,6 +133,41 @@ pub enum Codec9Error { InvalidScale, /// Batch slices whose lengths do not describe the same lanes. LengthMismatch, + /// A checked encode whose quantized value lies outside `i64`. + OutOfRange, +} + +/// A touched value from a checked encode: a lane when its quantized +/// magnitude fits 255, or its exact quantized value when it does not. +/// +/// [`Codec9::encode_touched`] saturates at magnitude 255; the checked form +/// hands the value back instead, so a wide path (an exact escape) can carry +/// it, the way `abakus::pm` hands back a carry lane. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Quantized9 { + /// The lane, identical to what [`Codec9::encode_touched`] returns. + Lane(EpiLane9), + /// The exact quantized value, `|v| > 255`. + Wide(i64), +} + +/// The one checked encoder both scale forms call. +#[inline(always)] +fn encode_checked_with_scale(value: f32, scale: f32) -> Result { + if !value.is_finite() { + return Err(Codec9Error::NonFinite); + } + let quantized = R::round(value / scale); + if quantized.abs() <= 255.0 { + return encode_with_scale::(value, scale).map(Quantized9::Lane); + } + // -2^63 and 2^63 are exact in f32; i64 holds [-2^63, 2^63). + const TWO_63: f32 = 9_223_372_036_854_775_808.0; + if (-TWO_63..TWO_63).contains(&quantized) { + Ok(Quantized9::Wide(quantized as i64)) + } else { + Err(Codec9Error::OutOfRange) + } } /// The one encoder both scale forms call. @@ -193,6 +228,15 @@ impl Codec9 { encode_with_scale::(value, C::SCALE) } + /// Encodes a touched finite value without saturating: a lane when the + /// quantized magnitude fits 255 (the same lane as + /// [`Self::encode_touched`]), otherwise the exact quantized value. + /// Refuses a value whose quantized form lies outside `i64`. + pub fn encode_touched_checked(value: f32) -> Result { + Self::assert_calibration(); + encode_checked_with_scale::(value, C::SCALE) + } + /// Decodes -0 into a floating NaN and all other codes using calibration. /// This is an explicit numeric view, not a permission or NULL decision. #[must_use] @@ -247,6 +291,12 @@ impl Codec9Runtime { encode_with_scale::(value, self.scale) } + /// Encodes one touched finite value without saturating; see + /// [`Codec9::encode_touched_checked`]. + pub fn encode_touched_checked(&self, value: f32) -> Result { + encode_checked_with_scale::(value, self.scale) + } + /// Decodes one lane; never-touched becomes NaN. #[must_use] pub fn decode(&self, lane: EpiLane9) -> f32 { @@ -313,6 +363,37 @@ mod tests { type Even = Codec9; type Away = Codec9; + /// Within ±255 the checked encoder returns exactly the lane the + /// saturating one does, the -0.49999 → +0 rule included. + #[test] + fn checked_encode_matches_encode_touched_within_range() { + let mut v = -255.4f32; + while v <= 255.4 { + assert_eq!(Even::encode_touched_checked(v), Even::encode_touched(v).map(Quantized9::Lane), "{v}"); + assert_eq!(Away::encode_touched_checked(v), Away::encode_touched(v).map(Quantized9::Lane), "{v}"); + v += 0.1; + } + let zero = Even::encode_touched_checked(-0.499_99).unwrap(); + assert_eq!(zero, Quantized9::Lane(EpiLane9::from_codeword(0x100).unwrap()), "-0.49999 is +0"); + } + + /// Past ±255 it hands back the exact quantized value where the saturating + /// encoder clamps; outside i64 it refuses. + #[test] + fn checked_encode_escapes_instead_of_saturating() { + assert_eq!(Even::encode_touched(300.0).unwrap().value(), Some(255), "saturates"); + assert_eq!(Even::encode_touched_checked(300.0), Ok(Quantized9::Wide(300))); + assert_eq!(Even::encode_touched_checked(-256.0), Ok(Quantized9::Wide(-256))); + assert_eq!(Even::encode_touched_checked(255.5), Ok(Quantized9::Wide(256)), "ties even"); + assert_eq!(Even::encode_touched_checked(-9_223_372_036_854_775_808.0), Ok(Quantized9::Wide(i64::MIN))); + assert_eq!(Even::encode_touched_checked(9_223_372_036_854_775_808.0), Err(Codec9Error::OutOfRange)); + assert_eq!(Even::encode_touched_checked(1e30), Err(Codec9Error::OutOfRange)); + assert_eq!(Even::encode_touched_checked(f32::NAN), Err(Codec9Error::NonFinite)); + let rt = Codec9Runtime::::new(0.5).unwrap(); + assert_eq!(rt.encode_touched_checked(200.0), Ok(Quantized9::Wide(400))); + assert_eq!(rt.encode_touched_checked(-0.2), Ok(Quantized9::Lane(EpiLane9::from_codeword(0x100).unwrap()))); + } + #[test] fn all_512_codewords_are_unique_and_absence_is_exactly_zero_and_zero() { let mut absent = 0usize;