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
18 changes: 9 additions & 9 deletions .claude/knowledge/add-pm-probe.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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.
14 changes: 14 additions & 0 deletions .claude/knowledge/dr512-epistemic-pm-invariant.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions .github/workflows/simd-matrix.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 5 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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 <name> --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]]
Expand Down
12 changes: 11 additions & 1 deletion scripts/add-pm-backends.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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; }
Expand Down
11 changes: 11 additions & 0 deletions scripts/wasi-test-run.mjs
Original file line number Diff line number Diff line change
@@ -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);
35 changes: 34 additions & 1 deletion src/hpc/abakus/pm.rs
Original file line number Diff line number Diff line change
Expand Up @@ -20,20 +20,35 @@
//! [`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,
/// Polarity per lane; with a zero magnitude, the presence bit.
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 {
Expand Down Expand Up @@ -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::<TiesEven>::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<i16>]) -> Pm {
let mut mag = [0u8; 64];
let mut pos = 0u64;
Expand Down
81 changes: 81 additions & 0 deletions src/hpc/codec9.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<R: NearestRounding9>(value: f32, scale: f32) -> Result<Quantized9, Codec9Error> {
if !value.is_finite() {
return Err(Codec9Error::NonFinite);
}
let quantized = R::round(value / scale);
if quantized.abs() <= 255.0 {
return encode_with_scale::<R>(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.
Expand Down Expand Up @@ -193,6 +228,15 @@ impl<R: NearestRounding9, C: Calibration> Codec9<R, C> {
encode_with_scale::<R>(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<Quantized9, Codec9Error> {
Self::assert_calibration();
encode_checked_with_scale::<R>(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]
Expand Down Expand Up @@ -247,6 +291,12 @@ impl<R: NearestRounding9> Codec9Runtime<R> {
encode_with_scale::<R>(value, self.scale)
}

/// Encodes one touched finite value without saturating; see
/// [`Codec9::encode_touched_checked`].
pub fn encode_touched_checked(&self, value: f32) -> Result<Quantized9, Codec9Error> {
encode_checked_with_scale::<R>(value, self.scale)
}

/// Decodes one lane; never-touched becomes NaN.
#[must_use]
pub fn decode(&self, lane: EpiLane9) -> f32 {
Expand Down Expand Up @@ -313,6 +363,37 @@ mod tests {
type Even = Codec9<TiesEven, Unit>;
type Away = Codec9<TiesAway, Unit>;

/// 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::<TiesEven>::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;
Expand Down
Loading