rns-engine 0.6.0__tar.gz → 0.8.0__tar.gz

{rns_engine-0.6.0/src/rns_engine.egg-info → rns_engine-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rns_engine
-Version: 0.6.0
+Version: 0.8.0
 Summary: Exact RNS engine with session/cache API.
 Author: Evan Wesley
 License-Expression: AGPL-3.0-only
@@ -194,7 +194,7 @@ out = session.decode_signed(session.add(a, b))
 
 ## Weighted INT32 partial accumulation
 
-Version 0.6 adds the first direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
+Version 0.7 introduced the fused direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
 
 Give the engine signed INT32 partial outputs with shape:
 
@@ -246,7 +246,7 @@ Important details:
 - `decode_modular()` always returns the canonical residue in `[0, M)`.
 - Empty term sets produce an exact zero result.
 
-The current implementation is an evidence-first baseline. Python schedules terms, while each per-element encode, scalar-weight multiply, and rail addition runs through the compiled native kernels. It is **not yet one fused C++ weighted-accumulation kernel**, and no fused-kernel speed claim is made.
+The implementation uses one fused native `_weighted` call to read signed INT32 partials, collect exact per-term magnitude bounds, apply positional weights modulo `M`, and accumulate all four rails. The pre-fusion staged encode → scale → add body remains available internally as an exact reference for A/B tests. Local AVX2 diagnostics measured roughly 2.1×–2.9× speedup at one million outputs and larger gains on tiny many-term cases; those figures are hardware-specific CPU evidence, not CUDA, Tensor Core, or universal performance claims.
 
 A precomputed receipt can also be created without materializing partial arrays:
 
@@ -260,6 +260,45 @@ certificate.require_unique()
 
 ---
 
+## Exact GEMM capacity planning
+
+Version 0.8 separates two different safety questions that must not be conflated:
+
+1. Does each grouped raw digit-plane coefficient fit the native signed accumulator?
+2. Does the final radix-weighted result fit uniquely inside the global RNS modulus product?
+
+```python
+import rns_engine as rns
+
+local = rns.plan_grouped_coefficient_capacity(
+    inner_dimension=5120,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+    accumulator_bits=32,
+)
+
+global_plan = rns.plan_digit_plane_gemm_capacity(
+    inner_dimension=5120,
+    radix=128,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+)
+
+assert local.max_abs_bound == 660_643_840
+assert local.safe
+assert local.minimum_signed_accumulator_bits == 31
+
+assert global_plan.capacity.required_modulus_bits == 126
+assert global_plan.capacity.additional_bits_required == 71
+assert not global_plan.current_unique
+```
+
+That workload is locally safe in INT32 but globally modular-only in the current four-rail range. The planner can also validate explicit proposed CRT moduli and rejects candidates that are not pairwise coprime with the existing product.
+
+See [`CAPACITY_PLANNING.md`](CAPACITY_PLANNING.md) for the exact laws, examples, and limits of what the receipts prove.
+
+---
+
 ## Core API
 
 ### Rail operations
@@ -285,6 +324,16 @@ certificate.require_unique()
 - `WeightedInt32Result.decode_signed(require_unique=True)`
 - `WeightedInt32Result.decode_modular()`
 
+### Capacity planning
+
+- `plan_signed_capacity(max_abs_bound, additional_moduli=())`
+- `plan_weighted_sum_capacity(weights, term_abs_bounds, addend_abs_bound=0, additional_moduli=())`
+- `plan_digit_plane_gemm_capacity(inner_dimension, radix, left_digit_abs_bounds, right_digit_abs_bounds, ...)`
+- `plan_grouped_coefficient_capacity(inner_dimension, left_digit_abs_bounds, right_digit_abs_bounds, accumulator_bits=32)`
+- `SignedCapacityPlan`
+- `DigitPlaneGemmCapacityPlan`
+- `GroupedCoefficientCapacityPlan`
+
 ### Scalar-broadcast encoded operations
 
 - `mul_u64(...)`
@@ -359,7 +408,7 @@ Workload: `affine_repeat_u64_io(x, 1_000_003, 7, iterations=1000)`
 - OpenMP with one thread: **82.80 billion ops/sec**
 - OpenMP with two threads: **94.86 billion ops/sec**
 
-These measurements cover the existing affine kernels, not the new weighted INT32 orchestration path.
+These measurements cover the existing affine kernels, not weighted INT32 reconstruction or the pure-Python capacity planners.
 
 ---
 
@@ -404,12 +453,15 @@ rns.HAS_AVX2
 
 ## Current release
 
-### v0.6.0
+### v0.8.0
 
-- weighted signed INT32 partial accumulation
-- exact arbitrary-precision positional weights
-- per-term magnitude receipts and strict no-wrap certification
-- canonical modular and uniqueness-gated signed decode paths
+- exact local grouped-coefficient accumulator planning
+- exact global digit-plane GEMM RNS-capacity planning
+- strict separation between local INT32 safety and global signed uniqueness
+- candidate CRT-modulus validation with pairwise-coprime enforcement
+- exact modulus shortfall and additional-bit receipts
+- fused native weighted signed INT32 partial accumulation
+- arbitrary-precision positional weights and no-wrap certificates
 - canonical centered signed encoding and decoding
 - exact dot-product and GEMM output-bound receipts
 - `SignedSession` high-level API

{rns_engine-0.6.0 → rns_engine-0.8.0}/README.md

@@ -171,7 +171,7 @@ out = session.decode_signed(session.add(a, b))
 
 ## Weighted INT32 partial accumulation
 
-Version 0.6 adds the first direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
+Version 0.7 introduced the fused direct bridge for digit-plane, chunked-GEMM, and Tensor Core pipelines.
 
 Give the engine signed INT32 partial outputs with shape:
 
@@ -223,7 +223,7 @@ Important details:
 - `decode_modular()` always returns the canonical residue in `[0, M)`.
 - Empty term sets produce an exact zero result.
 
-The current implementation is an evidence-first baseline. Python schedules terms, while each per-element encode, scalar-weight multiply, and rail addition runs through the compiled native kernels. It is **not yet one fused C++ weighted-accumulation kernel**, and no fused-kernel speed claim is made.
+The implementation uses one fused native `_weighted` call to read signed INT32 partials, collect exact per-term magnitude bounds, apply positional weights modulo `M`, and accumulate all four rails. The pre-fusion staged encode → scale → add body remains available internally as an exact reference for A/B tests. Local AVX2 diagnostics measured roughly 2.1×–2.9× speedup at one million outputs and larger gains on tiny many-term cases; those figures are hardware-specific CPU evidence, not CUDA, Tensor Core, or universal performance claims.
 
 A precomputed receipt can also be created without materializing partial arrays:
 
@@ -237,6 +237,45 @@ certificate.require_unique()
 
 ---
 
+## Exact GEMM capacity planning
+
+Version 0.8 separates two different safety questions that must not be conflated:
+
+1. Does each grouped raw digit-plane coefficient fit the native signed accumulator?
+2. Does the final radix-weighted result fit uniquely inside the global RNS modulus product?
+
+```python
+import rns_engine as rns
+
+local = rns.plan_grouped_coefficient_capacity(
+    inner_dimension=5120,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+    accumulator_bits=32,
+)
+
+global_plan = rns.plan_digit_plane_gemm_capacity(
+    inner_dimension=5120,
+    radix=128,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+)
+
+assert local.max_abs_bound == 660_643_840
+assert local.safe
+assert local.minimum_signed_accumulator_bits == 31
+
+assert global_plan.capacity.required_modulus_bits == 126
+assert global_plan.capacity.additional_bits_required == 71
+assert not global_plan.current_unique
+```
+
+That workload is locally safe in INT32 but globally modular-only in the current four-rail range. The planner can also validate explicit proposed CRT moduli and rejects candidates that are not pairwise coprime with the existing product.
+
+See [`CAPACITY_PLANNING.md`](CAPACITY_PLANNING.md) for the exact laws, examples, and limits of what the receipts prove.
+
+---
+
 ## Core API
 
 ### Rail operations
@@ -262,6 +301,16 @@ certificate.require_unique()
 - `WeightedInt32Result.decode_signed(require_unique=True)`
 - `WeightedInt32Result.decode_modular()`
 
+### Capacity planning
+
+- `plan_signed_capacity(max_abs_bound, additional_moduli=())`
+- `plan_weighted_sum_capacity(weights, term_abs_bounds, addend_abs_bound=0, additional_moduli=())`
+- `plan_digit_plane_gemm_capacity(inner_dimension, radix, left_digit_abs_bounds, right_digit_abs_bounds, ...)`
+- `plan_grouped_coefficient_capacity(inner_dimension, left_digit_abs_bounds, right_digit_abs_bounds, accumulator_bits=32)`
+- `SignedCapacityPlan`
+- `DigitPlaneGemmCapacityPlan`
+- `GroupedCoefficientCapacityPlan`
+
 ### Scalar-broadcast encoded operations
 
 - `mul_u64(...)`
@@ -336,7 +385,7 @@ Workload: `affine_repeat_u64_io(x, 1_000_003, 7, iterations=1000)`
 - OpenMP with one thread: **82.80 billion ops/sec**
 - OpenMP with two threads: **94.86 billion ops/sec**
 
-These measurements cover the existing affine kernels, not the new weighted INT32 orchestration path.
+These measurements cover the existing affine kernels, not weighted INT32 reconstruction or the pure-Python capacity planners.
 
 ---
 
@@ -381,12 +430,15 @@ rns.HAS_AVX2
 
 ## Current release
 
-### v0.6.0
+### v0.8.0
 
-- weighted signed INT32 partial accumulation
-- exact arbitrary-precision positional weights
-- per-term magnitude receipts and strict no-wrap certification
-- canonical modular and uniqueness-gated signed decode paths
+- exact local grouped-coefficient accumulator planning
+- exact global digit-plane GEMM RNS-capacity planning
+- strict separation between local INT32 safety and global signed uniqueness
+- candidate CRT-modulus validation with pairwise-coprime enforcement
+- exact modulus shortfall and additional-bit receipts
+- fused native weighted signed INT32 partial accumulation
+- arbitrary-precision positional weights and no-wrap certificates
 - canonical centered signed encoding and decoding
 - exact dot-product and GEMM output-bound receipts
 - `SignedSession` high-level API

{rns_engine-0.6.0 → rns_engine-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rns_engine"
-version = "0.6.0"
+version = "0.8.0"
 description = "Exact RNS engine with session/cache API."
 readme = "README.md"
 requires-python = ">=3.10"

{rns_engine-0.6.0 → rns_engine-0.8.0}/setup.py

@@ -39,19 +39,27 @@ def get_link_args():
     return []
 
 
-ext = Extension(
-    "rns_engine._core",
-    sources=["src/rns_engine/_core.cpp"],
-    include_dirs=[pybind11.get_include(), np.get_include()],
-    extra_compile_args=get_compile_args(),
-    extra_link_args=get_link_args(),
-    language="c++",
+def native_extension(name, source):
+    return Extension(
+        name,
+        sources=[source],
+        include_dirs=[pybind11.get_include(), np.get_include()],
+        extra_compile_args=get_compile_args(),
+        extra_link_args=get_link_args(),
+        language="c++",
+    )
+
+
+ext = native_extension("rns_engine._core", "src/rns_engine/_core.cpp")
+weighted_ext = native_extension(
+    "rns_engine._weighted",
+    "src/rns_engine/_weighted.cpp",
 )
 
 # Project metadata and package discovery live in pyproject.toml. Keeping them
 # out of setup.py prevents the two build entry points from drifting apart.
 setup(
-    ext_modules=[ext],
+    ext_modules=[ext, weighted_ext],
     include_package_data=True,
     zip_safe=False,
 )

{rns_engine-0.6.0 → rns_engine-0.8.0}/src/rns_engine/__init__.py

@@ -57,6 +57,17 @@ from .weighted import (
     accumulate_weighted_int32,
     certify_weighted_sum_bound,
 )
+from .capacity import (
+    DigitPlaneGemmCapacityPlan,
+    SignedCapacityPlan,
+    plan_digit_plane_gemm_capacity,
+    plan_signed_capacity,
+    plan_weighted_sum_capacity,
+)
+from .coefficients import (
+    GroupedCoefficientCapacityPlan,
+    plan_grouped_coefficient_capacity,
+)
 
 try:
     __version__ = _distribution_version("rns_engine")
@@ -83,6 +94,10 @@ __all__ = [
     "EncodedArray", "SessionCache", "Session", "SignedSession",
     "SignedRangeCertificate", "certify_signed_bound", "certify_signed_dot_bound",
     "WeightedInt32Result", "accumulate_weighted_int32", "certify_weighted_sum_bound",
+    "SignedCapacityPlan", "DigitPlaneGemmCapacityPlan",
+    "GroupedCoefficientCapacityPlan",
+    "plan_signed_capacity", "plan_weighted_sum_capacity",
+    "plan_digit_plane_gemm_capacity", "plan_grouped_coefficient_capacity",
     "info",
 ]
 
@@ -96,3 +111,4 @@ def info():
     print(f"  AVX2          : {'yes' if HAS_AVX2 else 'no'}")
     print("  Core APIs     : add/sub/mul/fma + raw/omp/auto scalar-broadcast family")
     print("  Bridge APIs   : weighted signed INT32 accumulation with range receipts")
+    print("  Planning APIs : local coefficient safety + global digit-plane RNS capacity")

rns_engine-0.8.0/src/rns_engine/_weighted.cpp

@@ -0,0 +1,141 @@
+#include <pybind11/pybind11.h>
+#include <pybind11/numpy.h>
+#include <stdint.h>
+#include <stdexcept>
+#include <string>
+#include <cstring>
+
+namespace py = pybind11;
+
+using arr_i32 = py::array_t<int32_t, py::array::c_style>;
+using arr16 = py::array_t<uint16_t, py::array::c_style>;
+using arr32 = py::array_t<uint32_t, py::array::c_style>;
+using arr64 = py::array_t<uint64_t, py::array::c_style | py::array::forcecast>;
+
+static constexpr uint32_t M0      = 127;
+static constexpr uint32_t M1      = 8191;
+static constexpr uint32_t M2      = 65536;
+static constexpr uint32_t M3      = 524287;
+static constexpr uint32_t M3_MASK = 0x7FFFFu;
+static constexpr uint64_t BM      = (uint64_t)M0 * M1 * M2 * M3;
+
+static int64_t require_1d_len(const py::array& a, const char* name) {
+    if (a.ndim() != 1) {
+        throw std::invalid_argument(std::string(name) + " must be a 1D array");
+    }
+    return (int64_t)a.shape(0);
+}
+
+static inline uint16_t r127s(uint32_t x) {
+    x = (x & 0x7F) + (x >> 7);
+    x = (x & 0x7F) + (x >> 7);
+    return x >= M0 ? x - M0 : (uint16_t)x;
+}
+
+static inline uint16_t r8191s(uint32_t x) {
+    x = (x & 0x1FFF) + (x >> 13);
+    x = (x & 0x1FFF) + (x >> 13);
+    return x >= M1 ? x - M1 : (uint16_t)x;
+}
+
+static inline uint32_t fma524287s(uint32_t a, uint32_t b, uint32_t c) {
+    uint64_t x = (uint64_t)a * b + c;
+    x = (x & M3_MASK) + (x >> 19);
+    x = (x & M3_MASK) + (x >> 19);
+    x = (x & M3_MASK) + (x >> 19);
+    uint32_t r = (uint32_t)x;
+    return r >= M3 ? (r - M3) : r;
+}
+
+static inline uint32_t mod524287_u64(uint64_t x) {
+    x = (x & M3_MASK) + (x >> 19);
+    x = (x & M3_MASK) + (x >> 19);
+    x = (x & M3_MASK) + (x >> 19);
+    uint32_t r = (uint32_t)x;
+    return r >= M3 ? (r - M3) : r;
+}
+
+py::tuple weighted_int32(const arr_i32& partials, const arr64& weights) {
+    if (partials.ndim() != 2) {
+        throw std::invalid_argument("partials must be a 2D int32 array");
+    }
+
+    const int64_t terms = (int64_t)partials.shape(0);
+    const int64_t n = (int64_t)partials.shape(1);
+    const int64_t weight_count = require_1d_len(weights, "weights");
+    if (weight_count != terms) {
+        throw std::invalid_argument(
+            "weights length must match partial term count (" +
+            std::to_string(weight_count) + " != " + std::to_string(terms) + ")");
+    }
+
+    arr16 o0({n}), o1({n}), o2({n});
+    arr32 o3({n});
+    arr64 bounds({terms});
+
+    uint16_t* p0 = o0.mutable_data();
+    uint16_t* p1 = o1.mutable_data();
+    uint16_t* p2 = o2.mutable_data();
+    uint32_t* p3 = o3.mutable_data();
+    uint64_t* pb = bounds.mutable_data();
+
+    if (n > 0) {
+        std::memset(p0, 0, (size_t)n * sizeof(uint16_t));
+        std::memset(p1, 0, (size_t)n * sizeof(uint16_t));
+        std::memset(p2, 0, (size_t)n * sizeof(uint16_t));
+        std::memset(p3, 0, (size_t)n * sizeof(uint32_t));
+    }
+    if (terms > 0) {
+        std::memset(pb, 0, (size_t)terms * sizeof(uint64_t));
+    }
+
+    const int32_t* x = partials.data();
+    const uint64_t* w = weights.data();
+
+    {
+        py::gil_scoped_release release;
+        for (int64_t term = 0; term < terms; ++term) {
+            const uint64_t weight = w[term] % BM;
+            const uint16_t w0 = (uint16_t)(weight % M0);
+            const uint16_t w1 = (uint16_t)(weight % M1);
+            const uint16_t w2 = (uint16_t)weight;
+            const uint32_t w3 = mod524287_u64(weight);
+            const int32_t* row = x + term * n;
+            uint64_t max_abs = 0;
+
+            for (int64_t i = 0; i < n; ++i) {
+                const int32_t signed_value = row[i];
+                const uint64_t magnitude = signed_value < 0
+                    ? (uint64_t)(-(int64_t)signed_value)
+                    : (uint64_t)signed_value;
+                if (magnitude > max_abs) max_abs = magnitude;
+
+                if (weight == 0) continue;
+
+                const uint64_t canonical = signed_value < 0
+                    ? (uint64_t)((int64_t)BM + (int64_t)signed_value)
+                    : (uint64_t)signed_value;
+                const uint16_t x0 = (uint16_t)(canonical % M0);
+                const uint16_t x1 = (uint16_t)(canonical % M1);
+                const uint16_t x2 = (uint16_t)canonical;
+                const uint32_t x3 = mod524287_u64(canonical);
+
+                p0[i] = r127s((uint32_t)p0[i] + (uint32_t)x0 * w0);
+                p1[i] = r8191s((uint32_t)p1[i] + (uint32_t)x1 * w1);
+                p2[i] = (uint16_t)((uint32_t)p2[i] + (uint32_t)x2 * w2);
+                p3[i] = fma524287s(x3, w3, p3[i]);
+            }
+            pb[term] = max_abs;
+        }
+    }
+
+    return py::make_tuple(o0, o1, o2, o3, bounds);
+}
+
+PYBIND11_MODULE(_weighted, m) {
+    m.doc() = "Fused weighted signed INT32 accumulation for rns_engine.";
+    m.def(
+        "weighted_int32",
+        &weighted_int32,
+        "Fused signed int32 weighting and four-rail accumulation with per-term bounds.");
+}