Add strict high-precision linear quantizer arithmetic and power-of-two bound policy

linear_high_precision keeps both coordinates and the user bound in double,
rounds strict f32 metadata downward, and reserves reconstruction rounding so a
tight requested bound is no longer violated. Optional power_of_two_bound rounds
the resolved ABS/NOA/PREL half-bound down to a power of two. Both flags persist
in the existing 72-byte header, round-trip through TOML, and stay opt-in. Adds
the fzgmod-profile-quantizer-linear four-way comparison benchmark.

Author: skyler-ruiter

CHANGELOG.md

@@ -10,6 +10,7 @@ Version numbers follow [Semantic Versioning](https://semver.org/).
 ## [Unreleased] — 2.0.0
 
 ### Added
+- **Strict linear-Quantizer arithmetic and an optional SLEEK-style power-of-two bound policy.** `linear_high_precision` uses a precomputed double reciprocal on encode, direct integer-to-double reconstruction on decode, and an internal half-ULP reserve for arbitrary steps; `power_of_two_bound` rounds the resolved ABS/NOA/PREL half-bound downward (1x–2x tighter). Both flags persist in the existing 72-byte header by using previously-zero padding, round-trip through TOML, and remain opt-in. Added `fzgmod-profile-quantizer-linear` for the four-way float/double/power2 comparison.
 - **Explicit-ownership execution API on `Pipeline` — ownership is now expressed by the return type instead of by `void**` vs `void*` and by mutable pipeline state.** New backend-neutral value types in `include/pipeline/device_buffer.h` (`DeviceSpan`, `ConstDeviceSpan`, non-owning `BorrowedDeviceBuffer`, move-only `OwnedDeviceBuffer` that records its device and frees through the backend facade, never a hard-coded `cudaFree`), plus span wrappers `compress()`, `compressInto()`, `decompressBorrowed()`, `decompressOwned()`, `decompressInto()`, and `decompressIntoAsync()`. They delegate to the existing pointer overloads, so behavior is unchanged and nothing is deprecated; `decompressBorrowed()`/`decompressOwned()` deliberately ignore `setPoolManagedDecompOutput()` and restore the flag. Tests: `tests/pipeline/test_device_buffer.cpp` (8 cases: move-only/non-owning traits, borrow round-trip, byte-identical `compressInto`, owned-buffer reclamation, ownership independent of the pipeline flag, capacity failure, move/release). 53/53 ctest. Step 1-2 of `memory/public_api_evolution.md`.
 - Added `fzgmod-profile-huffman-throughput`, a direct-stage HostCoordinated/DeviceResident latency and throughput benchmark with cold/warm codebook cases, CUDA-event and host timing, multiple sizes/distributions, round-trip checks, deterministic archive comparison, and CSV output.
 - Added `HuffmanExecutionMode::DeviceResident`: cuSZ-compatible canonical tree/forward/reverse-book construction directly from device histograms, device-side partition scan and PHF assembly for PerBlock/Adaptive/Fixed books, safe range validation, device-side header parsing on decode, terminal fixed-book CUDA Graph support, and automatic exact-size readback when Huffman feeds a downstream stage.
@@ -21,6 +22,7 @@ Version numbers follow [Semantic Versioning](https://semver.org/).
 - Removed Huffman's experimental `Fine` encode mode, its public API and diagnostics, TOML/card option, documentation, profiling selection, and mode-specific tests; `HuffmanStage` now exposes only the supported cuSZ coarse-grained encoder.
 
 ### Fixed
+- **Tight linear quantization could still violate the bound after fixing integer overflow.** Float reciprocal multiplication selected adjacent bins, final f32 reconstruction consumed additional error, the inverse first cast signed codes to float—dropping low bits above 2^24—and the runtime user bound was narrowed to float before an f64 range multiplication. The strict path now keeps both coordinate directions and the user-bound parameter in double, rounds strict f32 metadata downward rather than loosening it, and reserves reconstruction rounding. A captured CESM FLNTC `rel_range=1e-7` case changed from a 1.744x miss to bit-exact reconstruction; an 18-cell CESM/HURR/NYX smoke matrix passes every requested bound.
 - **Linear quantization silently wrapped bins outside signed `TCode` range.** Tight NOA bounds on offset-valued fields can require indices much wider than int32 (S3D `N2` at `1e-6` needs roughly 3.3e10). The linear kernel now uses a guarded int64 rounding intermediate, records any signed-code overflow in device scratch, and `postStreamSync()` refuses the run with remediation guidance instead of producing a corrupt archive. Regression test: `QuantizerLinear.RefusesCodeOverflow`; rationale: `CN-QUANT-3`.
 - Docker image builds now retain `THIRD_PARTY.md` in the build context so the CMake install step can package the required third-party notices.
 - Installed packages now include the project `LICENSE` and `THIRD_PARTY.md`; synchronized all 30-stage documentation/catalog surfaces, completed newer-stage attribution, and corrected the cuSZ-Hi/SZx/ROIBIN-SZ license records.

docs/cards/fzgm-quantizer.json

@@ -60,6 +60,18 @@
       "type": "bool",
       "default": false,
       "description": "ABS/NOA: linear/no-outlier mode (cuSZp-style). Emits raw signed codes q=round(x/2·eb), no radius clamp, no outlier ports. Pair with LorenzoStage(setBlockSize) → AdaptiveBitpackStage."
+    },
+    {
+      "name": "linearHighPrecision",
+      "type": "bool",
+      "default": false,
+      "description": "Linear mode only: double coordinate and reconstruction arithmetic plus an internal rounding reserve for a strict TInput error bound."
+    },
+    {
+      "name": "powerOfTwoBound",
+      "type": "bool",
+      "default": false,
+      "description": "ABS/NOA/PREL: round the resolved absolute half-bound downward to a power of two (1x to 2x tighter than requested), following SLEEK's bound policy."
     }
   ],
 

docs/config_file.md

@@ -171,6 +171,13 @@ example `setBlockSize(32)` is `block_size = 32`).
 | `SZp` | `SZpStage` | \ref stage_szp "SZpStage" |
 | `Merge` | `MergeStage` | \ref stage_merge "MergeStage" |
 | `ROIBinSplit` | `ROIBinSplitStage` | \ref stage_roibin_split "ROIBinSplitStage" |
+
+For a cuSZp-style `Quantizer` with a strict requested bound, set
+`linear_mode = true` and `linear_high_precision = true`. The optional
+`power_of_two_bound = true` rounds the resolved ABS/NOA/PREL absolute bound
+downward to a power of two; it is therefore a tighter, separately labelled
+rate-distortion configuration. See the Quantizer reference for constraints and
+effective-bound semantics.
 ---
 
 ## Complete Examples

docs/stages/quantizer.md

@@ -47,6 +47,8 @@ Using any other combination will result in a linker error. Most common: `Quantiz
 | `setOutlierThreshold(t)` | Force outliers | ABS/NOA only; `abs(x) >= t` -> outlier |
 | `setInplaceOutliers(enable)` | Embed outliers in codes | ABS/NOA only; see constraints below |
 | `setLinearMode(enable)` | Signed codes, no outliers | ABS/NOA only; cuSZp-style; see below |
+| `setLinearHighPrecision(enable)` | Strict linear coordinate arithmetic | Linear mode only; double forward/inverse arithmetic and rounding reserve |
+| `setPowerOfTwoBound(enable)` | Tighten uniform bound to a power of two | ABS/NOA/PREL; rounds down, so effective EB is 1x–2x tighter |
 | `setValueBase(v)` | Precomputed value range | NOA only; optional, see below |
 | `setDither(enable)` | Dithered ("_R"-style) reconstruction | ABS/NOA/REL; incompatible with linear/inplace modes; see below |
 | `setDitherSeed(seed)` | Seed for the dither offset | Persisted in the header; default 0 |
@@ -104,22 +106,22 @@ outlier mechanism at all**.
 
 ---
 
-## Linear / no-outlier mode (ABS/NOA only)
+## Linear / no-outlier mode (ABS/NOA/PREL only)
 
 `setLinearMode(true)` selects a cuSZp-style quantizer: each value is mapped to
 `q = round(x / (2 · eb))` and stored as two's-complement in `TCode`, with **no
 radius clamp, no outlier ports, no zigzag**. The forward kernel is a pure
-memory-bound map — the only atomic and the only divergent branch of the regular
-forward kernel (the outlier path) are removed — so it is strictly faster and is
-fully **graph-compatible** in ABS mode (no D2H, no outlier-count readback).
+memory-bound map: the outlier atomic and divergent branch of the regular forward
+kernel are removed. A four-byte overflow flag is read after execution, so linear
+mode is not CUDA-Graph compatible.
 
-Because there is no outlier fallback, a bin that overflows `TCode` simply wraps;
-**size TCode wide enough for the data** (use `uint32_t`). The codes are
+Because there is no outlier fallback, a bin outside signed `TCode` range is a
+hard error; **size TCode wide enough for the data** (use `uint32_t`). The codes are
 *declared* by the stage as the **signed** DataType (`UINT16→INT16`,
 `UINT32→INT32`) so they connect directly to a downstream `LorenzoStage<intN>`.
 
 Constraints (each throws at the first `compress()` if violated):
-- Valid only with `ABS` and `NOA` error-bound modes (not `REL`).
+- Valid only with uniform `ABS`, `NOA`, and `PREL` error-bound modes (not `REL`).
 - Mutually exclusive with `setInplaceOutliers(true)` and `setZigzagCodes(true)`.
 
 Intended front-end for the cuSZp-style modular pipeline:
@@ -129,11 +131,52 @@ auto* quant = p.addStage<QuantizerStage<float, uint32_t>>();
 quant->setErrorBound(1e-3f);
 quant->setErrorBoundMode(ErrorBoundMode::ABS);
 quant->setLinearMode(true);                 // signed INT32 codes, no outliers
+quant->setLinearHighPrecision(true);        // strict double-coordinate path
 auto* lrz = p.addStage<LorenzoStage<int32_t>>();
 // lrz->setBlockSize(32);                    // (7.2) block-local 1-D delta, cuSZp uses 32
 p.connect(lrz, quant, "codes");
 ```
 
+### Strict coordinate and reconstruction arithmetic
+
+`setLinearHighPrecision(true)` evaluates `x / (2*abs_eb)` with a precomputed
+double reciprocal and a double multiply. Decode likewise converts the signed
+integer code directly to double before multiplying; converting it to float first
+loses low bits when `|q| > 2^24`. For arbitrary uniform steps, the stage scans
+the field magnitude and tightens its internal half-step by the worst-case
+half-ULP of the final `TInput` reconstruction. The serialized effective bound is
+used by decode, while the requested bound remains the external validity target.
+The runtime user-bound parameter is retained as double even for an f32 stage, so
+an f64 range calculation is not first perturbed by a float metadata conversion;
+strict f32 bounds are rounded downward if their representation would loosen the
+TOML value.
+
+This accurate path is not eligible for the float-only warp-register fusion.
+On an H100 direct-stage NOA benchmark over 67,108,864 floats, its median forward
+time was 0.3794 ms versus 0.3752 ms for float coordinates (707.5 versus
+715.4 GB/s, 1.1% slower). The maximum error changed from 1.030x to 0.992x of
+the request. The benchmark is `fzgmod-profile-quantizer-linear`.
+
+`setPowerOfTwoBound(true)` first resolves ABS/NOA/PREL normally and then rounds
+the absolute half-bound down to the nearest power of two. Thus the effective
+bound is never looser and is between 1x and 2x tighter. This policy follows the
+bound adjustment described by SLEEK: binary scaling becomes an exponent shift,
+avoiding general multiplication/division rounding. It is a distinct rate-
+distortion arm: comparisons must report the effective bound because tighter
+quantization can reduce compression ratio.
+
+Reference: Brandon Burtchell et al., “SLEEK: An Efficient and Highly Parallel
+GPU Lossy Compressor,” IPDPS 2026, Section III-A,
+https://userweb.cs.txstate.edu/~burtscher/papers/ipdps26.pdf.
+
+TOML:
+
+```toml
+linear_mode = true
+linear_high_precision = true
+power_of_two_bound = false  # true selects the separate tighter-bound arm
+```
+
 ---
 
 ## Error bound modes
@@ -144,8 +187,9 @@ p.connect(lrz, quant, "codes");
 | `NOA` | `abs(error) / value_range ≤ eb` | Scales ABS by the data range |
 | `REL` | `abs(error) / abs(x_orig) ≤ eb` | Ratio of error to original value |
 
-**Precision.** ABS and NOA quantize, compare, and reconstruct in `TInput`, so a
-`double` field gets a `double` bound. REL is float32 internally (its log2/exp2
+**Precision.** The default ABS and NOA paths quantize, compare, and reconstruct
+in `TInput`; linear mode can opt into the strict double-coordinate path above.
+REL is float32 internally (its log2/exp2
 approximations are single-precision) and does not currently benefit from
 `TInput = double`.
 
@@ -154,8 +198,10 @@ which for a field whose range is small next to its offset can fall below what
 `TInput` itself can resolve at that magnitude — the input's own round-trip through
 `TInput` then exceeds the bound, so no compressor could honour it. The stage compares
 `abs_eb` against `epsilon(TInput) * max(abs(data))` and throws rather than emitting a
-stream that decodes cleanly into out-of-bound values. Use a wider input type, a looser
-bound, or `ABS` with an explicit bound.
+stream that decodes cleanly into out-of-bound values. The legacy path retains a
+conservative spacing check; strict arbitrary-step linear mode instead reserves the
+exact half-ULP reconstruction budget and refuses only when that budget consumes the
+bound. Use a wider input type, a looser bound, or the power-of-two policy.
 
 **REL mode details:**
 <!-- - Encodes magnitude in log2 space (PFPL), then reconstructs `x_hat` from the log bin. -->