From 4b9184761c211c849f5be99cd140a6e544b00559 Mon Sep 17 00:00:00 2001 From: Trinity Agent Date: Fri, 22 May 2026 11:21:28 +0000 Subject: [PATCH] wave-23: import ring-096 Quantization (GF16 codec + ternary + Format enum) (Closes #733) - ring-096-rust: GF16 codec + ternary quantization + Format enum mirroring specs/numeric/formats.t27 byte-for-byte - 641 LOC, 42 tests, all green on Rust 1.83.0 - Cross-kernel anchor #8: quantization_phi_identity routes phi^2 + 1/phi^2 = 3 through GF16 codec via pow_u64 + f32_to_gf16 + gf16_to_f32 - LOC correction: claimed 464 -> actual 641 (R5-HONEST) Closes #733 --- README.md | 2 + docs/NOW.md | 19 +- rings/COMPILE_STATUS.md | 49 ++- rings/ring-096-rust/.gitignore | 1 + rings/ring-096-rust/Cargo.toml | 9 + rings/ring-096-rust/README.md | 51 +++ rings/ring-096-rust/src/lib.rs | 641 +++++++++++++++++++++++++++++++++ 7 files changed, 761 insertions(+), 11 deletions(-) create mode 100644 rings/ring-096-rust/.gitignore create mode 100644 rings/ring-096-rust/Cargo.toml create mode 100644 rings/ring-096-rust/README.md create mode 100644 rings/ring-096-rust/src/lib.rs diff --git a/README.md b/README.md index 2ca68e983b..660b366570 100644 --- a/README.md +++ b/README.md @@ -597,4 +597,6 @@ MIT **Wave 22 (2026-05-22):** phi-Adam optimizer import — [`rings/ring-095-rust`](rings/ring-095-rust) lands the eighth honestly-authored Wave-11 crate (808 LOC, 25 tests). Mirrors `specs/ml/optimizer/{adam, adamw}.t27`: spec constants byte-for-byte (`DEFAULT_LEARNING_RATE=1e-3`, `DEFAULT_BETA1=0.9`, `DEFAULT_BETA2=0.999`, `DEFAULT_WEIGHT_DECAY=0.01`, `DEFAULT_EPSILON=1e-8`, `PHI_BETA1 = 0.9/phi ~= 0.556`, `PHI_BETA2 = 0.999/phi ~= 0.617`); `AdamWConfig` with `defaults()` (classic AdamW) and `phi_preset()` (phi-damped betas) constructors; caller-owned `AdamWState<'_>` (no allocation); spec-named helpers (`compute_bias_correction`, `update_first_moment`, `update_second_moment`, `apply_weight_decay`, `compute_update`); full `step()` orchestrator with decoupled weight decay, bias-corrected `lr_t = lr * sqrt(1 - beta2^t) / (1 - beta1^t)`, moment recurrences, AMSGrad max-of-v, and the parameter update. Private no_std math (`pow_u64`, `sqrt_newton`) bypasses libm. `phi_adam_phi_identity_via_betas` is the **seventh cross-kernel anchor test** in the project, routing `phi^2 + 1/phi^2 = 3` through the optimizer's `pow_u64` and through the phi-damped moment update `m_1 = (1 - 0.9/phi) * phi = phi - 0.9`. Wave-11 narrative claimed 659 LOC; honest measurement is 808 LOC. All 25 tests green on Rust 1.83.0. See [COMPILE_STATUS](rings/COMPILE_STATUS.md). +**Wave 23 (2026-05-22):** Quantization import — [`rings/ring-096-rust`](rings/ring-096-rust) lands the ninth honestly-authored Wave-11 crate (641 LOC, 42 tests). Mirrors `specs/numeric/formats.t27`: GF16 bit layout (`SIGN_MASK=0x8000`, `EXP_MASK=0x7E00`, `MANT_MASK=0x01FF`, `EXP_SHIFT=9`, `SIGN_SHIFT=15`, `BIAS=31`, `EXP_MAX=63`, `EXP_MIN=0`) byte-for-byte; full GF16 codec `gf16_to_f32` / `f32_to_gf16` (signed zero, denormals, normals, Inf, NaN, round-to-nearest with mantissa-overflow exponent carry); ternary quantization `f32_to_ternary` / `ternary_to_f32` with the spec's strict threshold `|x| > 0.5`; the `Format` enum (`Fp32`, `Fp16`, `Bf16`, `Gf16`, `Ternary`); `format_bytes`; and the `quantize_value` utility. A private `pow_u64` (fast exponentiation by squaring) replaces libm in `no_std`. `quantization_phi_identity` is the **eighth cross-kernel anchor test** in the project, routing `phi^2 + 1/phi^2 = 3` through the GF16 codec: it computes `phi^2` and `phi^-2` via `pow_u64`, encodes via `f32_to_gf16`, decodes via `gf16_to_f32`, and verifies the sum lies within GF16 mantissa tolerance of 3.0 (~0.03 absolute). Wave-11 narrative claimed 464 LOC; honest measurement is 641 LOC. All 42 tests green on Rust 1.83.0. See [COMPILE_STATUS](rings/COMPILE_STATUS.md). + **DOI:** [10.5281/zenodo.19456875](https://doi.org/10.5281/zenodo.19456875) \ No newline at end of file diff --git a/docs/NOW.md b/docs/NOW.md index fd136d9318..64808b56e9 100644 --- a/docs/NOW.md +++ b/docs/NOW.md @@ -2,7 +2,24 @@ Last updated: 2026-05-22 -## wave-22 -- phi-Adam optimizer import: ring-095-rust (this PR, Closes #731) +## wave-23 -- Quantization import: ring-096-rust (this PR, Closes #733) + +- **NEW** (rings-only, additive): `rings/ring-096-rust/` lands with `Cargo.toml` + `src/lib.rs` (641 LOC) + `README.md` + `.gitignore`. Zero edits under `gen/`, `coq/`, `trios-coq/`, `proofs/`, `bootstrap/`, `specs/`, `conformance/`, `architecture/`, root `Cargo.toml`, or any other crate. Doc-only updates to `rings/COMPILE_STATUS.md`, `README.md` (Wave 23 footer), and this file. +- **What ring-096 actually does:** Faithful Rust mirror of the realizable subset of `specs/numeric/formats.t27`. (a) GF16 bit-layout constants byte-for-byte: `SIGN_MASK = 0x8000`, `EXP_MASK = 0x7E00`, `MANT_MASK = 0x01FF`, `EXP_SHIFT = 9`, `SIGN_SHIFT = 15`, `BIAS = 31`, `EXP_MAX = 63`, `EXP_MIN = 0`. (b) `gf16_to_f32(x: u16) -> f64` decoder handling signed zero (e=0,m=0), denormals (e=0,m!=0 -> `(m/2^9) * 2^(1-bias)`), normals (e in (0, ExpMax) -> `(1 + m/2^9) * 2^(e-bias)`), positive/negative infinity (e=ExpMax,m=0), and NaN (e=ExpMax,m!=0). (c) `f32_to_gf16(a: f64) -> u16` encoder: signed-zero preserved, NaN -> 0x7F01, Inf -> 0x[7|F]E00, normal magnitude reduced by repeated *2 / *0.5 into [1, 2), mantissa = `(frac * 2^9) + 0.5` round-to-nearest, mantissa-overflow carries into the exponent, underflow into denormal range, overflow clamped to Inf encoding. (d) Ternary primitives: `f32_to_ternary` with the spec's strict threshold `|x| > 0.5` -> Pos/Neg, otherwise Zero; `ternary_to_f32` returns 1.0 / 0.0 / -1.0 exactly; `Trit::{Neg=-1, Zero=0, Pos=1}` enum with `to_i8` / `from_i8`. (e) `Format` enum mirrors the spec's `enum(u8)`: `Fp32`, `Fp16`, `Bf16`, `Gf16`, `Ternary`. (f) `format_bytes(Format) -> usize` returns 4 / 2 / 2 / 2 / 1. (g) `quantize_value(x, fmt)`: Fp32/Fp16/Bf16 are pass-through (codec width identical-or-wider than GF16; full IEEE 754 binary16/bf16 converters are out of scope here -- those belong to a later ring); Gf16 round-trips through encoder + decoder; Ternary round-trips through `f32_to_ternary` + `ternary_to_f32`. (h) `pow_u64(base, exp)` -- fast exponentiation by squaring with negative-exponent inversion, used for all 2^k computations and for the anchor identity. (i) `fabs_no_std`, `is_nan`, `is_inf` -- no-libm helpers. (j) `QuantError::{Overflow, Underflow, Nan}` (reserved for future encoders). (k) `identity_witness()` for the universal anchor (closed-form `phi^2 + 1/phi^2`). +- **GF16 round-trip semantics:** encoder uses iterative magnitude normalization (multiplicative ladder) instead of `frexp`, bounded by `EXP_MAX = 63` from above and `0` from below, so the loop terminates in <= 63 iterations for any finite input. Mantissa rounding can promote the next-exponent boundary; the encoder handles this by clearing mantissa to 0 and incrementing exponent (with overflow-to-Inf check). The local roundtrip test `f32_to_gf16_roundtrip_normal_values` verifies relative error < 1% for the values {1.5, 2.0, 0.5, -1.5, 100.0, -100.0, 0.125}. +- **Ternary boundary semantics:** the spec defines the threshold as strict `|x| > 0.5`, which means `0.5` and `-0.5` quantize to `Zero`, not `Pos` / `Neg`. This is the boundary tested by `ternary_at_threshold_is_zero` and is symmetric (`ternary_symmetry` verifies `q(+0.7) = -q(-0.7)` after round-trip). +- **no_std math:** the spec uses arbitrary 2^k computations and float arithmetic; the crate replaces libm with `pow_u64` (fast exponentiation, integer exponent) plus pure-arithmetic `fabs_no_std` / `is_nan` / `is_inf`. The crate is `#![no_std]` and `#![deny(warnings)]`. +- **No new spec (L6 CEILING + L2 GENERATION):** every constant, every formula, the Format enum's variant set and ordering, the ternary threshold value, and the byte sizes follow `specs/numeric/formats.t27` byte-for-byte. The spec wraps decoded values in `gf16` (alias for a float); we use `f64` directly because the kernel semantics are identical and avoiding an extra wrapper keeps the ring crates independent (no inter-ring deps). No file under `specs/`, `coq/`, `proofs/`, `bootstrap/`, `gen/` is touched. +- **Tests (42, all green on first run):** spec constants (`const_sign_mask`, `const_exp_mask`, `const_mant_mask`, `const_exp_shift_sign_shift_bias`, `const_exp_max_min`); GF16 decode (`gf16_to_f32_zero_positive`, `gf16_to_f32_zero_negative`, `gf16_to_f32_denormal_positive`, `gf16_to_f32_one`, `gf16_to_f32_positive_inf`, `gf16_to_f32_negative_inf`, `gf16_to_f32_nan`); GF16 encode (`f32_to_gf16_zero_positive`, `f32_to_gf16_zero_negative`, `f32_to_gf16_one_roundtrip`, `f32_to_gf16_inf_positive`, `f32_to_gf16_inf_negative`, `f32_to_gf16_nan`, `f32_to_gf16_roundtrip_normal_values`); ternary (`ternary_positive`, `ternary_zero`, `ternary_negative`, `ternary_above_threshold`, `ternary_below_neg_threshold`, `ternary_at_threshold_is_zero`, `ternary_to_f32_roundtrip`, `ternary_symmetry`); Format (`format_bytes_fp32`, `format_bytes_fp16`, `format_bytes_bf16`, `format_bytes_gf16`, `format_bytes_ternary`); quantize_value (`quantize_value_fp32_preserves`, `quantize_value_ternary_above_threshold`, `quantize_value_ternary_below_neg_threshold`, `quantize_value_gf16_roundtrip`); Trit helpers (`trit_from_to_i8`); pow_u64 (`pow_u64_zero_exp`, `pow_u64_positive_exp`, `pow_u64_negative_exp`); identity witness (`identity_witness_value`); cross-kernel anchor (`quantization_phi_identity`). Zero bug-fix cycles needed -- the boundary semantics, mantissa-overflow carry, and Inf/NaN encoding all worked correctly on the first compile. +- **Eighth cross-kernel anchor test:** `quantization_phi_identity` is the eighth time `phi^2 + 1/phi^2 = 3` is exercised through actual numeric kernels (after Wave 15 `mac_dot_phi_identity`, Wave 16 `cpu_phi_identity_integer_projection`, Wave 18 `sr_quantize_phi_unbiased`, Wave 19 `attention_phi_identity_via_softmax_matmul`, Wave 20 `moe_phi_identity_via_gating_and_ffn`, Wave 21 `runtime_phi_identity_via_scheduler_credits`, Wave 22 `phi_adam_phi_identity_via_betas`). Construction: (1) compute `phi^2` and `phi^-2` via the crate's own `pow_u64` and verify the f64-precision sum is within 1e-9 of 3.0 (pre-codec identity). (2) Encode both values via `f32_to_gf16` -> u16, then decode via `gf16_to_f32` -> f64; verify the post-codec sum lies within GF16 mantissa tolerance of 3.0 (absolute < 0.03 against the 9-bit mantissa precision budget). (3) Run the same round-trip through the higher-level `quantize_value(x, Format::Gf16)` API and verify the same bound holds. This anchors the identity through the full codec stack, not just `pow_u64`. +- **R5-HONEST LOC observation:** the Wave-11 narrative quoted **464 LOC** for ring-096; the honest Wave-23 measurement is **641 LOC**. Pattern across the Wave-15..23 import series: 088 (961 -> 439), 089 (334 -> 635), 090 (2143 -> 547), 091 (409 -> 462), 092 (847 -> 760), 093 (668 -> 950), 094 (774 -> 1210), 095 (659 -> 808), 096 (464 -> 641). The honesty work is replacing guesses with measurements, in both directions. +- **R5-HONEST out of scope:** full IEEE 754 binary16 (`fp16`) / Brain Float (`bf16`) bit-level encoders -- their `quantize_value` paths are pass-through in this ring; they will arrive as a dedicated codec ring. INT4 / INT8 quantization (a separate sub-format space not present in `specs/numeric/formats.t27`). Strict rounding-mode controls beyond round-to-nearest. Quantization-aware training hooks (those belong in the optimizer ring, ring-095). +- **Compile semantics unchanged:** ring-096 lives outside `[workspace].members` (Wave-14 `exclude = [..., "rings"]` covers it automatically). `rings-rust.yml` discovers it via the matrix generator and runs `cargo check` + `cargo test`, both `continue-on-error: true`. The CI run triggered by this PR will be the first to exercise these 42 tests in public. +- **COMPILE_STATUS promotion:** ring-096 moves from `claimed-only` to `check` + `test`. The remaining 3 Wave-11 rings (ring-097, ring-098, ring-099) stay `claimed-only` and the section preamble is updated to reflect the new boundary. +- **L1 TRACEABILITY:** PR cites `Closes #733` in title and body; every commit message carries it. **L2 GENERATION:** zero edits under generated trees. **L3 PURITY:** ASCII source, English doc-comments. **L4 TESTABILITY:** 42 `#[test]`s. **L5 IDENTITY:** anchor exercised through `pow_u64`, the GF16 codec, and `quantize_value`. **L6 CEILING:** zero numeric kernel / spec changes; spec constants mirror existing spec byte-for-byte. **L7 UNITY:** no new `*.sh` -- all new files are `.toml`, `.rs`, `.md`, `.gitignore`. +- Closes #733 + +## wave-22 -- phi-Adam optimizer import: ring-095-rust (Closes #731) - **NEW** (rings-only, additive): `rings/ring-095-rust/` lands with `Cargo.toml` + `src/lib.rs` (808 LOC) + `README.md` + `.gitignore`. Zero edits under `gen/`, `coq/`, `trios-coq/`, `proofs/`, `bootstrap/`, `specs/`, `conformance/`, `architecture/`, root `Cargo.toml`, or any other crate. Doc-only updates to `rings/COMPILE_STATUS.md`, `README.md` (Wave 22 footer), and this file. - **What ring-095 actually does:** Faithful Rust mirror of the realizable subset of `specs/ml/optimizer/{adam, adamw}.t27`. AdamW (Loshchilov & Hutter 2019) with decoupled weight decay, plus AMSGrad (Reddi et al. 2018) variant, plus the spec's explicit **phi-Adam** branch with phi-damped betas. (a) Spec constants byte-for-byte: `DEFAULT_LEARNING_RATE = 1e-3`, `DEFAULT_BETA1 = 0.9`, `DEFAULT_BETA2 = 0.999`, `DEFAULT_WEIGHT_DECAY = 0.01`, `DEFAULT_EPSILON = 1e-8`, `DEFAULT_AMSGRAD = false`, `PHI_BETA1 = 0.9 / phi ~= 0.556`, `PHI_BETA2 = 0.999 / phi ~= 0.617`. (b) `AdamWConfig` with `defaults()` (classic AdamW), `phi_preset()` (phi-damped betas + use_phi_betas=true), `effective_beta1()` / `effective_beta2()` (honouring use_phi_betas), `is_valid()` (range check). (c) `AdamWState<'_>` -- caller-owned mutable references to `m`, `v`, optional `v_max` buffers; `AdamWState::init` zeroes all buffers and validates shape. (d) Helpers named after the spec: `compute_bias_correction`, `update_first_moment`, `update_second_moment`, `apply_weight_decay` (in-place), `compute_update`. (e) `step()` orchestrator: increments `state.step`, computes `bc1 = 1 - beta1^t`, `bc2 = 1 - beta2^t`, `lr_t = lr * sqrt(bc2) / bc1`, applies decoupled weight decay if `weight_decay > 0`, then for each parameter: updates moments, optionally tracks AMSGrad `v_max`, computes `lr_t * m / (sqrt(v_or_vmax) + epsilon)`, subtracts from parameter, accumulates squared updates for `step_norm`. Returns `StepResult { step_norm, lr_t, step }`. (f) `pow_u64` -- fast exponentiation, used for `pow(beta, t)`. (g) `sqrt_newton` -- Newton-Raphson square root with relative-tolerance early exit. (h) `OptimError::{ShapeMismatch, InvalidConfig}`. (i) `identity_witness()` for the universal anchor. diff --git a/rings/COMPILE_STATUS.md b/rings/COMPILE_STATUS.md index d4fac8333d..704d479c76 100644 --- a/rings/COMPILE_STATUS.md +++ b/rings/COMPILE_STATUS.md @@ -1,6 +1,6 @@ -# rings/ -- Living Compile Status (Wave 13 gate, Waves 14-22 promotions) +# rings/ -- Living Compile Status (Wave 13 gate, Waves 14-23 promotions) -> Last updated: 2026-05-22 (Wave 22) +> Last updated: 2026-05-22 (Wave 23) > Anchor: phi^2 + 1/phi^2 = 3 > CI workflow: [`.github/workflows/rings-rust.yml`](../.github/workflows/rings-rust.yml) > Toolchain: pinned via [`Dockerfile.rust`](../Dockerfile.rust) -- `rust:1.83-bookworm` @@ -228,20 +228,49 @@ this PR triggers. |--------------------|-----------------------------------|-----:|------:|-------------------| | `ring-095-rust` | phi-Adam optimizer (AdamW + phi) | 808 | 25 | `check` + `test` | -## Wave 11 -- ring-096..ring-099 (claimed-only, off-disk) +## Wave 23 import -- ring-096 (on disk, real) + +Wave 23 (2026-05-22, Closes #733) imports the **ninth** Wave-11 crate for real. +Locally verified on Rust 1.83.0: `cargo check` green, `cargo test --lib` +reports **42 passed, 0 failed** on the first run. Ring-096 mirrors +[`specs/numeric/formats.t27`](../specs/numeric/formats.t27) byte-for-byte: +GF16 bit layout (`SIGN_MASK = 0x8000`, `EXP_MASK = 0x7E00`, +`MANT_MASK = 0x01FF`, `EXP_SHIFT = 9`, `SIGN_SHIFT = 15`, `BIAS = 31`, +`EXP_MAX = 63`, `EXP_MIN = 0`); the GF16 codec `gf16_to_f32` / +`f32_to_gf16` (handles signed zero, denormals, normals, Inf, NaN, +round-to-nearest with mantissa-overflow exponent carry); ternary +quantization `f32_to_ternary` / `ternary_to_f32` with the spec's strict +threshold (`|x| > 0.5`); the `Format` enum (`Fp32`, `Fp16`, `Bf16`, +`Gf16`, `Ternary`); `format_bytes`; and the `quantize_value` utility. +A private `pow_u64` (fast exponentiation by squaring) replaces libm in +`no_std`. The crate's `quantization_phi_identity` is the **eighth +cross-kernel anchor test** in the project (after ring-088, ring-089, +ring-091, ring-092, ring-093, ring-094, ring-095), routing +`phi^2 + 1/phi^2 = 3` through the GF16 codec: it computes `phi^2` and +`phi^-2` via `pow_u64`, encodes each via `f32_to_gf16`, decodes via +`gf16_to_f32`, and verifies the sum lies within GF16 mantissa tolerance +of 3.0 (~0.03 absolute). Earlier Wave-11 narrative claimed 464 LOC; +honest Wave-23 measurement is **641 LOC**. Promotion will be +re-confirmed by the green `rings-rust` workflow run this PR triggers. + +| Crate | Domain | LOC | Tests | Status | +|--------------------|-----------------------------------|-----:|------:|-------------------| +| `ring-096-rust` | Quantization (GF16 codec+ternary) | 641 | 42 | `check` + `test` | + +## Wave 11 -- ring-097..ring-099 (claimed-only, off-disk) Wave 11's narrative described 11 additional crates with ~ 8 969 LOC. Their -sources never reached this repository. Waves 15-22 acknowledge this +sources never reached this repository. Waves 15-23 acknowledge this honestly and have promoted `ring-088`, `ring-089`, `ring-090`, `ring-091`, -`ring-092`, `ring-093`, `ring-094`, and `ring-095` out of this table. The -rows below are **claimed-only** placeholders, *not* deliverables. They will -be promoted to `check` + `test` one ring at a time, each via its own PR -that carries real source + local verification (the Wave-15..22 template). -LOC numbers below are quotes from past narrative, not measurements. +`ring-092`, `ring-093`, `ring-094`, `ring-095`, and `ring-096` out of this +table. The rows below are **claimed-only** placeholders, *not* deliverables. +They will be promoted to `check` + `test` one ring at a time, each via its +own PR that carries real source + local verification (the Wave-15..23 +template). LOC numbers below are quotes from past narrative, not +measurements. | Crate | Domain | LOC (claimed) | Status | |--------------------|-----------------------------------|---------------:|----------------| -| `ring-096-rust` | Quantization | 464 | `claimed-only` | | `ring-097-rust` | Chain-of-Thought | 624 | `claimed-only` | | `ring-098-rust` | World Model | 920 | `claimed-only` | | `ring-099-rust` | Integration | 1127 | `claimed-only` | diff --git a/rings/ring-096-rust/.gitignore b/rings/ring-096-rust/.gitignore new file mode 100644 index 0000000000..03314f77b5 --- /dev/null +++ b/rings/ring-096-rust/.gitignore @@ -0,0 +1 @@ +Cargo.lock diff --git a/rings/ring-096-rust/Cargo.toml b/rings/ring-096-rust/Cargo.toml new file mode 100644 index 0000000000..31b67a7388 --- /dev/null +++ b/rings/ring-096-rust/Cargo.toml @@ -0,0 +1,9 @@ +[package] +name = "ring-096-quantization" +version = "0.1.0" +edition = "2021" +description = "ring-096: Format quantization primitives (GF16 codec, ternary, Format enum) mirroring specs/numeric/formats.t27" +license = "Apache-2.0" + +[lib] +path = "src/lib.rs" diff --git a/rings/ring-096-rust/README.md b/rings/ring-096-rust/README.md new file mode 100644 index 0000000000..f2e01e5c9c --- /dev/null +++ b/rings/ring-096-rust/README.md @@ -0,0 +1,51 @@ +# ring-096-quantization + +Format quantization primitives — GF16 codec, ternary quantization, Format enum. + +Mirrors `specs/numeric/formats.t27` byte-for-byte. + +## Primitives + +- **GF16 bit layout**: `SIGN_MASK=0x8000`, `EXP_MASK=0x7E00`, `MANT_MASK=0x01FF`, `BIAS=31` +- **`gf16_to_f32(u16) -> f64`** — decode: handles signed zero, denormals, normals, Inf, NaN +- **`f32_to_gf16(f64) -> u16`** — encode (round-to-nearest): handles signed zero, Inf, NaN, overflow, underflow +- **`f32_to_ternary(f64) -> Trit`** — ternary quantization with threshold 0.5 +- **`ternary_to_f32(Trit) -> f64`** — convert ternary back to float +- **`Format` enum** — `Fp32`, `Fp16`, `Bf16`, `Gf16`, `Ternary` +- **`format_bytes(Format) -> usize`** — byte size lookup +- **`quantize_value(f64, Format) -> f64`** — generic quantization utility + +## no_std math + +Pure `no_std` — no `libm`. Internal helpers: +- `pow_u64` — fast integer exponentiation by squaring +- `fabs_no_std` — branch-based absolute value + +## Anchor #8 + +`quantization_phi_identity` routes the Trinity identity `phi^2 + 1/phi^2 = 3` through: +- `pow_u64(phi, 2)` and `pow_u64(phi, -2)` +- Encode both via `f32_to_gf16` +- Decode via `gf16_to_f32` +- Sum and verify ≈ 3.0 within GF16 mantissa tolerance (~0.03 absolute) + +## Build & test + +``` +cargo check +cargo test --lib +``` + +## Constitutional compliance + +- L1 TRACEABILITY — `Closes #733` +- L2 GENERATION — zero edits under `specs/`, `gen/`, `coq/` +- L3 PURITY — ASCII source, English doc-comments +- L4 TESTABILITY — `#[test]` blocks +- L5 IDENTITY — `phi^2 + 1/phi^2 = 3` exercised +- L6 CEILING — spec constants byte-for-byte +- L7 UNITY — no `*.sh` files + +--- + +`phi^2 + 1/phi^2 = 3` diff --git a/rings/ring-096-rust/src/lib.rs b/rings/ring-096-rust/src/lib.rs new file mode 100644 index 0000000000..a788dc5924 --- /dev/null +++ b/rings/ring-096-rust/src/lib.rs @@ -0,0 +1,641 @@ +// SPDX-License-Identifier: Apache-2.0 +// ring-096-rust: Format quantization primitives +// Mirrors specs/numeric/formats.t27 byte-for-byte. +// +// Identity anchor: phi^2 + 1/phi^2 = 3 | TRINITY +// +// Scope: +// - GF16 bit layout constants +// - gf16_to_f32 / f32_to_gf16 codec (decode/encode) +// - Ternary quantization (f32_to_ternary, ternary_to_f32) +// - Format enum + format_bytes + quantize_value utility +// +// no_std: no libm. All math via private helpers (pow_u64). + +#![no_std] +#![deny(warnings)] + +// ============================================================================ +// 1. GF16 Bit Layout Constants (byte-for-byte from specs/numeric/formats.t27) +// ============================================================================ +// +// GF16 layout: [S(1) E(6) M(9)] = [15:15][14:9][8:0] +// - Sign: bit 15 (0x8000) +// - Exponent: bits 14-9 (0x7E00), bias = 31 +// - Mantissa: bits 8-0 (0x01FF) +// Range: 2^-31 to 2^32 + +pub const SIGN_MASK: u16 = 0x8000; +pub const EXP_MASK: u16 = 0x7E00; +pub const MANT_MASK: u16 = 0x01FF; + +pub const EXP_SHIFT: u32 = 9; +pub const SIGN_SHIFT: u32 = 15; +pub const BIAS: i32 = 31; + +pub const EXP_MAX: u16 = 63; +pub const EXP_MIN: u16 = 0; + +/// Threshold for ternary quantization: |w| > 0.5 -> +/-1. +pub const TERNARY_THRESHOLD: f64 = 0.5; + +// ============================================================================ +// 2. Errors +// ============================================================================ + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum QuantError { + Overflow, + Underflow, + Nan, +} + +// ============================================================================ +// 3. Trit (ternary value) +// ============================================================================ + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Trit { + Neg = -1isize as isize, + Zero = 0, + Pos = 1, +} + +impl Trit { + pub fn to_i8(self) -> i8 { + match self { + Trit::Neg => -1, + Trit::Zero => 0, + Trit::Pos => 1, + } + } + + pub fn from_i8(v: i8) -> Trit { + if v > 0 { + Trit::Pos + } else if v < 0 { + Trit::Neg + } else { + Trit::Zero + } + } +} + +// ============================================================================ +// 4. Format enum +// ============================================================================ + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[repr(u8)] +pub enum Format { + Fp32 = 0, + Fp16 = 1, + Bf16 = 2, + Gf16 = 3, + Ternary = 4, +} + +/// Byte size for each format (spec-aligned). +pub fn format_bytes(fmt: Format) -> usize { + match fmt { + Format::Fp32 => 4, + Format::Fp16 => 2, + Format::Bf16 => 2, + Format::Gf16 => 2, + Format::Ternary => 1, + } +} + +// ============================================================================ +// 5. Private no_std math helpers +// ============================================================================ + +/// Fast integer exponentiation by squaring: base^exp. +/// Used for 2^k computations during GF16 encode/decode and anchor identity. +fn pow_u64(base: f64, exp: i32) -> f64 { + if exp == 0 { + return 1.0; + } + let (b, mut e) = if exp < 0 { + (1.0 / base, -exp as u32) + } else { + (base, exp as u32) + }; + let mut result = 1.0; + let mut acc = b; + while e > 0 { + if e & 1 == 1 { + result *= acc; + } + acc *= acc; + e >>= 1; + } + result +} + +/// |x| without core::num::Float. +fn fabs_no_std(x: f64) -> f64 { + if x < 0.0 { + -x + } else { + x + } +} + +/// Check NaN: x != x. +fn is_nan(x: f64) -> bool { + x != x +} + +/// Infinity sentinel via f64::INFINITY. +const INF: f64 = f64::INFINITY; +const NEG_INF: f64 = f64::NEG_INFINITY; + +fn is_inf(x: f64) -> bool { + x == INF || x == NEG_INF +} + +// ============================================================================ +// 6. GF16 codec +// ============================================================================ + +/// Decode GF16 (u16) to f64 (we use f64 as the canonical decoded value). +/// +/// Algorithm: +/// - Extract sign, exponent, mantissa. +/// - e=0, m=0 -> signed zero. +/// - e=0, m!=0 -> denormal: value = (-1)^s * (m/2^9) * 2^(1 - bias). +/// - e=EXP_MAX, m=0 -> +/- Inf. +/// - e=EXP_MAX, m!=0 -> NaN. +/// - Normal: value = (-1)^s * (1 + m/2^9) * 2^(e - bias). +pub fn gf16_to_f32(x: u16) -> f64 { + let s = (x & SIGN_MASK) >> SIGN_SHIFT; + let e = (x & EXP_MASK) >> EXP_SHIFT; + let m = x & MANT_MASK; + let sign = if s == 1 { -1.0_f64 } else { 1.0_f64 }; + + if e == EXP_MIN { + if m == 0 { + return sign * 0.0; + } + // Denormal: (-1)^s * (m / 2^9) * 2^(1 - bias) + let mantissa = m as f64 / pow_u64(2.0, EXP_SHIFT as i32); + return sign * mantissa * pow_u64(2.0, 1 - BIAS); + } + + if e == EXP_MAX { + if m == 0 { + return if s == 1 { NEG_INF } else { INF }; + } + return f64::NAN; + } + + // Normal: (-1)^s * (1 + m / 2^9) * 2^(e - bias) + let mantissa = 1.0 + (m as f64 / pow_u64(2.0, EXP_SHIFT as i32)); + sign * mantissa * pow_u64(2.0, e as i32 - BIAS) +} + +/// Encode f64 to GF16 (u16), round-to-nearest. +/// +/// Algorithm: +/// 1. Signed zero preserved. +/// 2. Inf / NaN special-cased (NaN -> 0x7F01). +/// 3. Decompose into sign + magnitude. +/// 4. Find e such that magnitude in [2^(e-bias), 2^(e-bias+1)). +/// 5. Mantissa = (mag / 2^(e - bias) - 1.0) * 2^9, round-to-nearest. +/// 6. Underflow -> 0 (with sign), overflow -> Inf. +pub fn f32_to_gf16(a: f64) -> u16 { + // Signed zero + if a == 0.0 { + // distinguish -0 from +0 + if a.is_sign_negative() { + return 0x8000; + } + return 0; + } + + // NaN + if is_nan(a) { + return 0x7F01; + } + + // Inf + if is_inf(a) { + return if a < 0.0 { 0xFE00 } else { 0x7E00 }; + } + + let sign: u16 = if a < 0.0 { 1 } else { 0 }; + let mag = fabs_no_std(a); + + // Find exponent e such that 2^(e - bias) <= mag < 2^(e - bias + 1) + // i.e. e - bias = floor(log2(mag)) + // Compute via repeated multiply/divide; bounded loop. + let mut e: i32 = BIAS; // unbiased = 0 -> mag in [1, 2) + let mut mantissa_norm = mag; + if mantissa_norm >= 1.0 { + while mantissa_norm >= 2.0 && (e as u16) < EXP_MAX - 1 { + mantissa_norm *= 0.5; + e += 1; + } + } else { + while mantissa_norm < 1.0 && e > 0 { + mantissa_norm *= 2.0; + e -= 1; + } + if mantissa_norm < 1.0 { + // Denormal range: encode as e=0 with mantissa bits scaled. + let denorm_mant_f = mantissa_norm * pow_u64(2.0, EXP_SHIFT as i32); + let mut denorm_mant = (denorm_mant_f + 0.5) as i32; + if denorm_mant < 0 { + denorm_mant = 0; + } + if denorm_mant > MANT_MASK as i32 { + denorm_mant = MANT_MASK as i32; + } + return (sign << SIGN_SHIFT) | (denorm_mant as u16 & MANT_MASK); + } + } + + // Overflow -> Inf + if e >= EXP_MAX as i32 { + return (sign << SIGN_SHIFT) | (EXP_MAX << EXP_SHIFT); + } + + // mantissa in [1, 2): subtract 1, scale by 2^9, round. + let frac = mantissa_norm - 1.0; + let mant_f = frac * pow_u64(2.0, EXP_SHIFT as i32); + let mut mant = (mant_f + 0.5) as i32; + + // Mantissa rounding could push to next exponent. + if mant >= (1i32 << EXP_SHIFT) { + mant = 0; + e += 1; + if e >= EXP_MAX as i32 { + return (sign << SIGN_SHIFT) | (EXP_MAX << EXP_SHIFT); + } + } + + let e_u16 = e as u16 & 0x3F; + (sign << SIGN_SHIFT) | (e_u16 << EXP_SHIFT) | (mant as u16 & MANT_MASK) +} + +// ============================================================================ +// 7. Ternary quantization +// ============================================================================ + +/// Quantize f64 to ternary using threshold 0.5. +pub fn f32_to_ternary(x: f64) -> Trit { + if x > TERNARY_THRESHOLD { + Trit::Pos + } else if x < -TERNARY_THRESHOLD { + Trit::Neg + } else { + Trit::Zero + } +} + +/// Convert ternary back to f64: -1, 0, +1. +pub fn ternary_to_f32(t: Trit) -> f64 { + match t { + Trit::Pos => 1.0, + Trit::Zero => 0.0, + Trit::Neg => -1.0, + } +} + +// ============================================================================ +// 8. quantize_value utility +// ============================================================================ + +/// Quantize an f64 to the target format. +/// +/// For Fp32 / Fp16 / Bf16 we model "preserve value within format precision" +/// by returning the original value (these formats are wider than GF16 in +/// practice and this crate's role is the codec; full IEEE 754 binary16/bf16 +/// converters are out of scope for ring-096). +/// +/// For Gf16: round-trip via GF16 codec. +/// For Ternary: round-trip via f32_to_ternary / ternary_to_f32. +pub fn quantize_value(x: f64, fmt: Format) -> f64 { + match fmt { + Format::Fp32 | Format::Fp16 | Format::Bf16 => x, + Format::Gf16 => gf16_to_f32(f32_to_gf16(x)), + Format::Ternary => ternary_to_f32(f32_to_ternary(x)), + } +} + +// ============================================================================ +// 9. Identity witness +// ============================================================================ + +/// Identity witness: returns 3.0 computed via phi^2 + 1/phi^2. +/// Trinity anchor present in every ring crate. +pub fn identity_witness() -> f64 { + // phi = (1 + sqrt(5)) / 2 + // Use a closed-form constant; integer-exact identity is asserted in + // anchor test through pow_u64 path (see test phi_identity_via_pow). + let phi: f64 = 1.618_033_988_749_894_8; + pow_u64(phi, 2) + pow_u64(phi, -2) +} + +// ============================================================================ +// 10. Tests +// ============================================================================ + +#[cfg(test)] +mod tests { + use super::*; + + // ---- Spec constants ---- + + #[test] + fn const_sign_mask() { + assert_eq!(SIGN_MASK, 0x8000); + } + + #[test] + fn const_exp_mask() { + assert_eq!(EXP_MASK, 0x7E00); + } + + #[test] + fn const_mant_mask() { + assert_eq!(MANT_MASK, 0x01FF); + } + + #[test] + fn const_exp_shift_sign_shift_bias() { + assert_eq!(EXP_SHIFT, 9); + assert_eq!(SIGN_SHIFT, 15); + assert_eq!(BIAS, 31); + } + + #[test] + fn const_exp_max_min() { + assert_eq!(EXP_MAX, 63); + assert_eq!(EXP_MIN, 0); + } + + // ---- GF16 -> f32 ---- + + #[test] + fn gf16_to_f32_zero_positive() { + assert_eq!(gf16_to_f32(0x0000), 0.0); + } + + #[test] + fn gf16_to_f32_zero_negative() { + let v = gf16_to_f32(0x8000); + assert_eq!(v, 0.0); + assert!(v.is_sign_negative()); + } + + #[test] + fn gf16_to_f32_denormal_positive() { + // e=0, m!=0 -> small positive + let v = gf16_to_f32(0x0080); + assert!(v > 0.0 && v < 1.0); + } + + #[test] + fn gf16_to_f32_one() { + // 1.0 -> bias=31, m=0 -> raw = (31 << 9) = 0x3E00 + let v = gf16_to_f32(0x3E00); + assert!((v - 1.0).abs() < 1e-9); + } + + #[test] + fn gf16_to_f32_positive_inf() { + assert_eq!(gf16_to_f32(0x7E00), INF); + } + + #[test] + fn gf16_to_f32_negative_inf() { + assert_eq!(gf16_to_f32(0xFE00), NEG_INF); + } + + #[test] + fn gf16_to_f32_nan() { + let v = gf16_to_f32(0x7F01); + assert!(is_nan(v)); + } + + // ---- f32 -> GF16 ---- + + #[test] + fn f32_to_gf16_zero_positive() { + assert_eq!(f32_to_gf16(0.0), 0x0000); + } + + #[test] + fn f32_to_gf16_zero_negative() { + assert_eq!(f32_to_gf16(-0.0), 0x8000); + } + + #[test] + fn f32_to_gf16_one_roundtrip() { + let enc = f32_to_gf16(1.0); + let dec = gf16_to_f32(enc); + assert!((dec - 1.0).abs() < 0.01); + } + + #[test] + fn f32_to_gf16_inf_positive() { + assert_eq!(f32_to_gf16(INF), 0x7E00); + } + + #[test] + fn f32_to_gf16_inf_negative() { + assert_eq!(f32_to_gf16(NEG_INF), 0xFE00); + } + + #[test] + fn f32_to_gf16_nan() { + assert_eq!(f32_to_gf16(f64::NAN), 0x7F01); + } + + #[test] + fn f32_to_gf16_roundtrip_normal_values() { + // Roundtrip various normal values within 1% tolerance. + let values = [1.5_f64, 2.0, 0.5, -1.5, 100.0, -100.0, 0.125]; + for &v in &values { + let enc = f32_to_gf16(v); + let dec = gf16_to_f32(enc); + let err = fabs_no_std(dec - v) / fabs_no_std(v); + assert!(err < 0.01, "v={} dec={} rel_err={}", v, dec, err); + } + } + + // ---- Ternary ---- + + #[test] + fn ternary_positive() { + assert_eq!(f32_to_ternary(1.0), Trit::Pos); + } + + #[test] + fn ternary_zero() { + assert_eq!(f32_to_ternary(0.0), Trit::Zero); + } + + #[test] + fn ternary_negative() { + assert_eq!(f32_to_ternary(-1.0), Trit::Neg); + } + + #[test] + fn ternary_above_threshold() { + assert_eq!(f32_to_ternary(0.6), Trit::Pos); + } + + #[test] + fn ternary_below_neg_threshold() { + assert_eq!(f32_to_ternary(-0.6), Trit::Neg); + } + + #[test] + fn ternary_at_threshold_is_zero() { + // |x| == 0.5 -> zero (strict ">" in spec) + assert_eq!(f32_to_ternary(0.5), Trit::Zero); + assert_eq!(f32_to_ternary(-0.5), Trit::Zero); + } + + #[test] + fn ternary_to_f32_roundtrip() { + assert_eq!(ternary_to_f32(Trit::Pos), 1.0); + assert_eq!(ternary_to_f32(Trit::Zero), 0.0); + assert_eq!(ternary_to_f32(Trit::Neg), -1.0); + } + + #[test] + fn ternary_symmetry() { + let p = ternary_to_f32(f32_to_ternary(0.7)); + let n = ternary_to_f32(f32_to_ternary(-0.7)); + assert_eq!(p, -n); + } + + // ---- Format / format_bytes ---- + + #[test] + fn format_bytes_fp32() { + assert_eq!(format_bytes(Format::Fp32), 4); + } + + #[test] + fn format_bytes_fp16() { + assert_eq!(format_bytes(Format::Fp16), 2); + } + + #[test] + fn format_bytes_bf16() { + assert_eq!(format_bytes(Format::Bf16), 2); + } + + #[test] + fn format_bytes_gf16() { + assert_eq!(format_bytes(Format::Gf16), 2); + } + + #[test] + fn format_bytes_ternary() { + assert_eq!(format_bytes(Format::Ternary), 1); + } + + // ---- quantize_value ---- + + #[test] + fn quantize_value_fp32_preserves() { + assert_eq!(quantize_value(1.5, Format::Fp32), 1.5); + } + + #[test] + fn quantize_value_ternary_above_threshold() { + assert_eq!(quantize_value(1.5, Format::Ternary), 1.0); + } + + #[test] + fn quantize_value_ternary_below_neg_threshold() { + assert_eq!(quantize_value(-1.5, Format::Ternary), -1.0); + } + + #[test] + fn quantize_value_gf16_roundtrip() { + let v = quantize_value(1.5, Format::Gf16); + assert!((v - 1.5).abs() < 0.01); + } + + // ---- Trit helpers ---- + + #[test] + fn trit_from_to_i8() { + assert_eq!(Trit::from_i8(5).to_i8(), 1); + assert_eq!(Trit::from_i8(0).to_i8(), 0); + assert_eq!(Trit::from_i8(-3).to_i8(), -1); + } + + // ---- pow_u64 ---- + + #[test] + fn pow_u64_zero_exp() { + assert_eq!(pow_u64(7.0, 0), 1.0); + } + + #[test] + fn pow_u64_positive_exp() { + assert!((pow_u64(2.0, 10) - 1024.0).abs() < 1e-9); + } + + #[test] + fn pow_u64_negative_exp() { + assert!((pow_u64(2.0, -3) - 0.125).abs() < 1e-12); + } + + // ---- Identity witness ---- + + #[test] + fn identity_witness_value() { + let v = identity_witness(); + assert!((v - 3.0).abs() < 1e-9, "phi^2 + 1/phi^2 = {}, expected 3", v); + } + + // ---- Anchor #8: cross-kernel Trinity identity through quantization ---- + // + // Routes phi^2 + 1/phi^2 = 3 through the GF16 codec: + // 1. Encode phi^2 via f32_to_gf16 -> u16 + // 2. Encode 1/phi^2 via f32_to_gf16 -> u16 + // 3. Decode both back via gf16_to_f32 + // 4. Sum and check ~ 3.0 within GF16 tolerance. + // pow_u64 is also exercised for both exponents. + + #[test] + fn quantization_phi_identity() { + let phi: f64 = 1.618_033_988_749_894_8; + + // Exercise pow_u64 path for phi^2 and phi^-2. + let phi_sq = pow_u64(phi, 2); + let phi_inv_sq = pow_u64(phi, -2); + + // Pre-codec identity (mathematical truth) + let pre = phi_sq + phi_inv_sq; + assert!((pre - 3.0).abs() < 1e-9); + + // Round-trip through GF16 codec + let enc_a = f32_to_gf16(phi_sq); + let enc_b = f32_to_gf16(phi_inv_sq); + let dec_a = gf16_to_f32(enc_a); + let dec_b = gf16_to_f32(enc_b); + + let post = dec_a + dec_b; + // GF16 has ~9-bit mantissa: relative error budget ~0.2%. Allow 1% absolute. + assert!( + (post - 3.0).abs() < 0.03, + "phi-identity through GF16 codec: got {}, expected ~3.0", + post + ); + + // Also exercise quantize_value route + let q_a = quantize_value(phi_sq, Format::Gf16); + let q_b = quantize_value(phi_inv_sq, Format::Gf16); + assert!((q_a + q_b - 3.0).abs() < 0.03); + } +}