rns-engine 0.7.0__tar.gz → 0.9.0__tar.gz

rns_engine-0.9.0/CAPACITY_PLANNING.md

@@ -0,0 +1,178 @@
+# Exact GEMM Capacity Planning
+
+`rns_engine` keeps two different safety questions separate:
+
+1. **Local accumulator safety:** does each raw grouped digit-plane coefficient fit the native signed accumulator, such as INT32?
+2. **Global reconstruction safety:** after positional weights are applied, does the final wide result fit uniquely inside the RNS modulus product?
+
+A workload can pass the first test and fail the second. Version 0.8 provides exact integer-only receipts for both.
+
+## Local grouped-coefficient safety
+
+For positional digit planes,
+
+```text
+A = sum(A_i * radix**i)
+B = sum(B_j * radix**j)
+```
+
+raw coefficient `k` is:
+
+```text
+R_k = sum_{i+j=k} GEMM(A_i, B_j)
+```
+
+If the GEMM inner dimension is `K`, and plane entries obey magnitude bounds `L_i` and `R_j`, then:
+
+```text
+abs(R_k) <= sum_{i+j=k} K * L_i * R_j
+```
+
+Use:
+
+```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,
+)
+
+print(local.coefficient_pair_counts)
+print(local.coefficient_abs_bounds)
+print(local.max_abs_bound)
+print(local.minimum_signed_accumulator_bits)
+local.require_safe()
+```
+
+For eight full-magnitude INT8 planes at `K=5120`:
+
+```text
+largest grouped coefficient = 660,643,840
+minimum signed width        = 31 bits
+INT32 status                = safe
+```
+
+This proves the grouped Tensor Core or native INT32 outputs can remain exact locally.
+
+## Global RNS reconstruction safety
+
+The reconstructed operands obey:
+
+```text
+left_value_bound  = sum(L_i * radix**i)
+right_value_bound = sum(R_j * radix**j)
+```
+
+One final GEMM output obeys:
+
+```text
+abs(C) <= K * left_value_bound * right_value_bound + addend_bound
+```
+
+A symmetric signed interval `[-bound, bound]` requires modulus:
+
+```text
+minimum_modulus = 2 * bound + 1
+```
+
+Use:
+
+```python
+wide = rns.plan_digit_plane_gemm_capacity(
+    inner_dimension=5120,
+    radix=128,
+    left_digit_abs_bounds=[127] * 8,
+    right_digit_abs_bounds=[127] * 8,
+)
+
+print(wide.max_abs_bound)
+print(wide.capacity.minimum_required_modulus)
+print(wide.capacity.required_modulus_bits)
+print(wide.capacity.additional_bits_required)
+print(wide.current_unique)
+```
+
+For eight full radix-128 planes per operand:
+
+```text
+operand magnitude bound     = 128**8 - 1
+required signed modulus     = 126 bits
+current additional deficit  = 71 product bits
+current four-rail result    = modular-only in the worst case
+```
+
+So the same workload is locally INT32-safe but not globally unique in the current four-rail RNS range.
+
+## Proposed additional rails
+
+Candidate CRT moduli can be tested explicitly:
+
+```python
+base = rns.plan_digit_plane_gemm_capacity(
+    5120,
+    128,
+    [127] * 8,
+    [127] * 8,
+)
+
+candidate = base.capacity.minimum_single_coprime_modulus
+
+expanded = rns.plan_digit_plane_gemm_capacity(
+    5120,
+    128,
+    [127] * 8,
+    [127] * 8,
+    additional_moduli=[candidate],
+)
+
+expanded.require_unique()
+```
+
+Every proposed modulus must be greater than one and coprime with the existing modulus product and every earlier candidate.
+
+`minimum_single_coprime_modulus` answers only the mathematical capacity question. It does **not** claim that the returned modulus is fast to reduce, appropriate for a GPU, or the best hardware rail. Reduction cost, storage width, vectorization, and reconstruction cost must be benchmarked separately.
+
+## General weighted-sum planning
+
+For arbitrary exact weighted partial bounds:
+
+```python
+plan = rns.plan_weighted_sum_capacity(
+    weights=[1, 128, 128**2],
+    term_abs_bounds=[100, 200, 300],
+    addend_abs_bound=7,
+)
+
+print(plan.max_abs_bound)
+print(plan.current_unique)
+print(plan.modulus_shortfall)
+```
+
+For a known result bound directly:
+
+```python
+plan = rns.plan_signed_capacity(max_abs_bound=10**30)
+print(plan.minimum_required_modulus)
+print(plan.additional_bits_required)
+```
+
+## What these receipts prove
+
+They prove conservative worst-case capacity from the supplied exact integer bounds. They can certify:
+
+- grouped coefficient safety for a chosen signed accumulator width;
+- the exact final-result magnitude bound;
+- whether the current RNS product gives unique signed reconstruction;
+- how much modulus product is missing;
+- whether explicit proposed CRT rails close that deficit lawfully.
+
+They do not prove:
+
+- that the supplied input bounds describe a real dataset tightly;
+- that a proposed modulus is computationally efficient;
+- GPU, CUDA, or Tensor Core speed;
+- that worst-case capacity is necessary for a narrower application distribution;
+- that adding rails is cheaper than chunking, rescaling, or changing the digit representation.

rns_engine-0.9.0/CUDA_PARALLEL_LANES.md

@@ -0,0 +1,100 @@
+# Parallel Learning Lanes for CUDA Rail and Kernel Search
+
+The CUDA search uses a shared-prior / bounded-divergence / teaching-boundary architecture.
+
+## Shared prior
+
+Every lane receives the same immutable evidence body:
+
+- identical input matrices and exact shared scales;
+- identical radix-128 digit planes;
+- identical required grouped INT32 outputs;
+- identical seven-rail residue targets;
+- identical direct Python-big-integer answer;
+- identical capacity and no-wrap receipts;
+- identical warmup count and measurement protocol.
+
+No lane may redefine correctness.
+
+## Independent lanes
+
+Initial lanes should differ in one controlled design choice:
+
+- `lane-smallest-product`: extra Mersenne exponents `(11, 29, 31)`;
+- `lane-balanced`: extra Mersenne exponents `(23, 24, 25)`;
+- reduction-kernel variants inside each lawful profile;
+- reconstruction ordering variants;
+- grouped-coefficient launch/packing variants.
+
+Inside one benchmark epoch, lanes may tune independently. Their outputs remain comparable because the shared fixture and proof laws are frozen.
+
+## Hard-law firewall
+
+Before performance evidence is accepted, every lane must pass:
+
+1. exact grouped-partial equality;
+2. exact residue equality on every rail;
+3. exact centered reconstruction;
+4. pairwise coprimality;
+5. local INT32 safety;
+6. global signed uniqueness;
+7. deterministic fixture identity.
+
+A fast failing lane has no score. GCD is not learned or approximated.
+
+## Teaching boundary
+
+At a fixed trial boundary:
+
+- pool lawful integer evidence: failure counts, bytes moved, launch counts, register-spill counts, and completed output counts;
+- preserve timing samples with their provenance rather than averaging incompatible runs blindly;
+- select one coherent kernel/configuration body as the next teacher;
+- retain alternate lawful bodies in an archive to prevent premature monoculture.
+
+The first deterministic selection tuple is:
+
+```text
+(correctness_failures,
+ validation_failures,
+ median_elapsed_ns,
+ bytes_moved,
+ launch_count,
+ lane_id)
+```
+
+Correctness and validation fields must both be zero before timing matters. `lane_id` is the fixed tie-break.
+
+## Epoch rule
+
+An epoch is a fixed number of completed repetitions on a fixed matrix shape, never wall-clock duration. This keeps work membership reproducible even though elapsed time is measured.
+
+Suggested initial epoch:
+
+```text
+5 warmups + 21 measured repetitions per shape/profile
+```
+
+The next shared prior contains the winning complete kernel body plus pooled benchmark evidence. It does not average coupled CUDA source, register layouts, or launch strategies into a synthetic kernel that no lane tested.
+
+## What can merge and what must be selected
+
+Merge lawfully:
+
+- exact pass/fail counts;
+- operation counts;
+- byte counts;
+- launch counts;
+- fixture hashes;
+- hardware metadata;
+- independent timing samples with provenance.
+
+Select coherently:
+
+- CUDA kernel source;
+- tile shape;
+- register layout;
+- reduction strategy;
+- reconstruction order;
+- rail profile.
+
+The rule is: merge evidence; select a complete executable body.

rns_engine-0.9.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE
+include README.md
+include CAPACITY_PLANNING.md
+include PRE_CUDA_READINESS.md
+include CUDA_PARALLEL_LANES.md
+recursive-include benchmarks *.py
+recursive-include colab *.ipynb
+recursive-include tests *.py

{rns_engine-0.7.0/src/rns_engine.egg-info → rns_engine-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rns_engine
-Version: 0.7.0
+Version: 0.9.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.7 provides the fused 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 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.
+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,103 @@ 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.
+
+---
+
+## Pre-CUDA exact shared-scale GEMM
+
+Version 0.9 adds the complete CPU-side oracle and integration contract for the future CUDA/T4 body. Before using GPU credits, run:
+
+```bash
+rns-pre-cuda --report readiness.json --fixture t4_fixture.json
+```
+
+A green receipt proves:
+
+- both seven-rail profiles are pairwise coprime and close the 126-bit target;
+- radix-128 signed digit planes round-trip exactly;
+- grouped plane GEMMs fit INT32 for the frozen witness;
+- weighted seven-rail reconstruction equals direct Python-big-integer GEMM;
+- shared rational scales multiply exactly with no denominator GEMM;
+- the portable CUDA fixture and full backend verifier agree.
+
+The future CUDA backend must implement both methods in the contract:
+
+```python
+class ExactPipelineBackend:
+    def grouped_partials(self, left_planes, right_planes):
+        ...  # INT8 Tensor Core / cuBLASLt grouped coefficients
+
+    def weighted_rails(self, grouped_partials, weights, moduli):
+        ...  # GPU seven-rail modular weighting and accumulation
+```
+
+The verifier refuses a backend that produces correct GEMM partials but silently falls back to CPU RNS. See [`PRE_CUDA_READINESS.md`](PRE_CUDA_READINESS.md), [`CUDA_PARALLEL_LANES.md`](CUDA_PARALLEL_LANES.md), and [`colab/T4_EXACT_GEMM_BRINGUP.ipynb`](colab/T4_EXACT_GEMM_BRINGUP.ipynb).
+
+```python
+import numpy as np
+import rns_engine as rns
+
+left = rns.SharedScaleMatrix(
+    np.array([[2**40 + 3, -17], [29, 2**35 - 5]], dtype=object),
+    scale=6,
+)
+right = rns.SharedScaleMatrix(
+    np.array([[31, -(2**30) + 9], [2**33 + 1, 43]], dtype=object),
+    scale=35,
+)
+
+receipt = rns.exact_shared_scale_gemm(
+    left,
+    right,
+    config=rns.WideRNSConfig.balanced_seven_rail(),
+    left_plane_count=8,
+    right_plane_count=8,
+)
+
+assert receipt.exact_match
+assert receipt.output_scale == 210
+result = receipt.as_matrix()
+```
+
+---
+
 ## Core API
 
 ### Rail operations
@@ -285,6 +382,41 @@ 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`
+
+### Wide reference and pre-CUDA APIs
+
+- `WideRNSConfig.current()`
+- `WideRNSConfig.smallest_product_seven_rail()`
+- `WideRNSConfig.balanced_seven_rail()`
+- `accumulate_weighted_int32_wide(...)`
+- `SharedScaleMatrix`
+- `exact_integer_matmul(...)`
+- `decompose_signed_radix(...)` / `reconstruct_signed_radix(...)`
+- `grouped_plane_gemm(...)` / `reconstruct_grouped_partials(...)`
+- `exact_shared_scale_gemm(...)`
+- `CudaGemmFixture`
+- `CpuExactPipelineBackend`
+- `build_cuda_gemm_fixture(...)`
+- `verify_backend(...)`
+- `run_pre_cuda_readiness()`
+- `build_default_pre_cuda_fixture()`
+
+### Parallel rail-lane planning
+
+- `build_parallel_rail_prior(capacity)`
+- `RailLearningLane`
+- `ParallelRailPrior`
+- `search_mersenne_rails_for_capacity(...)`
+
 ### Scalar-broadcast encoded operations
 
 - `mul_u64(...)`
@@ -359,7 +491,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,19 +536,23 @@ rns.HAS_AVX2
 
 ## Current release
 
-### v0.7.0
-
-- fused native weighted signed INT32 partial accumulation
-- one compiled pass for magnitude collection, positional weighting, and four-rail accumulation
-- staged reference body retained for exact fused-versus-staged A/B benchmarking
-- exact arbitrary-precision positional weights
-- per-term magnitude receipts and strict no-wrap certification
-- canonical modular and uniqueness-gated signed decode paths
-- canonical centered signed encoding and decoding
-- exact dot-product and GEMM output-bound receipts
-- `SignedSession` high-level API
-- four-rail native engine (`127 × 8191 × 65536 × 524287`)
-- AVX2, OpenMP, and auto-dispatch kernel families
+### v0.9.0
+
+- configurable correctness-first CRT oracle for arbitrary pairwise-coprime rails
+- two lawful seven-rail profiles closing the 126-bit eight-plane target
+- exact signed radix-128 decomposition and reconstruction
+- exact grouped digit-plane GEMM coefficients with strict INT32 overflow refusal
+- exact shared-scale rational GEMM with integer numerator and scale receipts
+- portable JSON CUDA fixture containing inputs, planes, partials, rails, and answer
+- full backend contract requiring both grouped partials and GPU rail accumulation
+- deterministic pre-CUDA readiness command and frozen witness
+- parallel rail-lane shared-prior plan with hard correctness firewall
+- Colab/T4 bring-up notebook with one isolated CUDA integration point
+- exact Mersenne rail-set search and local/global capacity planners
+- fused native four-rail weighted signed INT32 accumulation
+- canonical centered signed encoding and no-wrap certificates
+
+The seven-rail body in 0.9 is a CPU correctness oracle, not a native CUDA or production-speed wide RNS kernel.
 
 ---
 

rns_engine-0.9.0/PRE_CUDA_READINESS.md

@@ -0,0 +1,72 @@
+# Pre-CUDA Readiness Contract
+
+Do not spend GPU credits until this repository's complete CPU-side readiness gate passes:
+
+```bash
+rns-pre-cuda
+```
+
+The command emits one JSON receipt and exits nonzero if any required condition fails.
+
+## What must already be proven
+
+The gate verifies all of the following without CUDA:
+
+1. The eight-plane radix-128 target at `K=5120` needs a 126-bit signed modulus.
+2. The existing four rails are short by 71 product bits.
+3. Under a 31-bit-per-extra-rail ceiling, three added rails are mathematically necessary.
+4. Both retained seven-rail profiles are pairwise coprime and close the capacity deficit:
+   - smallest-product exponents `(11, 29, 31)`;
+   - balanced exponents `(23, 24, 25)`.
+5. Both profiles round-trip centered signed values, including their exact signed boundaries.
+6. Wide rail addition and multiplication agree with Python big integers.
+7. Signed radix-128 digit planes reconstruct their source integers exactly.
+8. Grouped plane GEMMs reconstruct the direct Python-big-integer GEMM exactly.
+9. Every grouped coefficient fits signed INT32 for the tested fixture.
+10. Shared-scale rational GEMM preserves the exact numerator and multiplies scale metadata exactly.
+11. The portable CUDA fixture survives a JSON round trip.
+12. A backend must reproduce both:
+    - grouped INT32 coefficient matrices;
+    - weighted seven-rail residues.
+13. Final centered reconstruction must equal the direct big-integer witness.
+
+## What remains for the T4
+
+Once the gate is green, the only intentionally missing body is the CUDA implementation of the backend contract:
+
+```python
+class ExactPipelineBackend:
+    def grouped_partials(left_planes, right_planes):
+        ...  # INT8 Tensor Core / cuBLASLt body
+
+    def weighted_rails(grouped_partials, weights, moduli):
+        ...  # CUDA modular weighting and seven-rail accumulation
+```
+
+The verifier, fixtures, scales, exact witnesses, range receipts, candidate rail profiles, and failure rules already exist.
+
+## What a green gate does not prove
+
+A green CPU gate does not prove:
+
+- T4 Tensor Core execution;
+- CUDA correctness;
+- GPU reduction efficiency;
+- FP16 parity or superiority;
+- that either candidate rail profile is the fastest GPU profile;
+- arbitrary per-element rational denominators.
+
+Those claims require the T4 run.
+
+## First T4 success condition
+
+The first GPU milestone is not speed. It is exact equivalence:
+
+```text
+CUDA grouped partials == CPU grouped partials
+CUDA seven rails       == CPU seven rails
+CUDA decoded numerator == direct Python integer GEMM
+CUDA output scale      == left scale * right scale
+```
+
+Only after that witness passes should timing begin.