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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. rns_engine-0.11.0/G4_SERIES1_EVIDENCE.md +66 -0
  2. {rns_engine-0.9.0 → rns_engine-0.11.0}/MANIFEST.in +1 -0
  3. rns_engine-0.11.0/PKG-INFO +481 -0
  4. rns_engine-0.11.0/README.md +455 -0
  5. {rns_engine-0.9.0 → rns_engine-0.11.0}/pyproject.toml +24 -5
  6. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/__init__.py +4 -0
  7. rns_engine-0.11.0/src/rns_engine/data/g4s1_public_summary.json +87 -0
  8. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part01.b64 +1 -0
  9. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part02.b64 +1 -0
  10. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part03.b64 +1 -0
  11. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part04.b64 +1 -0
  12. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part05.b64 +1 -0
  13. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part06a.b64 +1 -0
  14. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part06b.b64 +1 -0
  15. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part07.b64 +1 -0
  16. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part08a.b64 +1 -0
  17. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part08b.b64 +1 -0
  18. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part09.b64 +1 -0
  19. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part10a.b64 +1 -0
  20. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part10b1.b64 +1 -0
  21. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part10b2.b64 +1 -0
  22. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part10b4.b64 +1 -0
  23. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part11.b64 +1 -0
  24. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part12a.b64 +1 -0
  25. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part12b.b64 +1 -0
  26. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part13.b64 +1 -0
  27. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part14a.b64 +1 -0
  28. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part14b.b64 +1 -0
  29. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part15a.b64 +1 -0
  30. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part15b.b64 +1 -0
  31. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part16a.b64 +1 -0
  32. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part16b.b64 +1 -0
  33. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17a.b64 +1 -0
  34. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b1.b64 +1 -0
  35. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b2a.b64 +1 -0
  36. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b2b1.b64 +1 -0
  37. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b2b2.b64 +1 -0
  38. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b2b3.b64 +1 -0
  39. rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_runtime.json +104 -0
  40. rns_engine-0.11.0/src/rns_engine/g4_benchmark.py +525 -0
  41. rns_engine-0.11.0/src/rns_engine/g4_results.py +114 -0
  42. rns_engine-0.11.0/src/rns_engine.egg-info/PKG-INFO +481 -0
  43. rns_engine-0.11.0/src/rns_engine.egg-info/SOURCES.txt +83 -0
  44. rns_engine-0.11.0/src/rns_engine.egg-info/requires.txt +13 -0
  45. rns_engine-0.11.0/tests/test_g4_benchmark.py +31 -0
  46. rns_engine-0.11.0/tests/test_g4_results.py +42 -0
  47. rns_engine-0.11.0/tests/test_packaging.py +40 -0
  48. rns_engine-0.9.0/PKG-INFO +0 -565
  49. rns_engine-0.9.0/README.md +0 -542
  50. rns_engine-0.9.0/src/rns_engine.egg-info/PKG-INFO +0 -565
  51. rns_engine-0.9.0/src/rns_engine.egg-info/SOURCES.txt +0 -45
  52. rns_engine-0.9.0/src/rns_engine.egg-info/requires.txt +0 -5
  53. rns_engine-0.9.0/tests/test_packaging.py +0 -8
  54. {rns_engine-0.9.0 → rns_engine-0.11.0}/CAPACITY_PLANNING.md +0 -0
  55. {rns_engine-0.9.0 → rns_engine-0.11.0}/CUDA_PARALLEL_LANES.md +0 -0
  56. {rns_engine-0.9.0 → rns_engine-0.11.0}/LICENSE +0 -0
  57. {rns_engine-0.9.0 → rns_engine-0.11.0}/PRE_CUDA_READINESS.md +0 -0
  58. {rns_engine-0.9.0 → rns_engine-0.11.0}/benchmarks/weighted_int32_baseline.py +0 -0
  59. {rns_engine-0.9.0 → rns_engine-0.11.0}/colab/T4_EXACT_GEMM_BRINGUP.ipynb +0 -0
  60. {rns_engine-0.9.0 → rns_engine-0.11.0}/setup.cfg +0 -0
  61. {rns_engine-0.9.0 → rns_engine-0.11.0}/setup.py +0 -0
  62. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/_core.cpp +0 -0
  63. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/_weighted.cpp +0 -0
  64. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/capacity.py +0 -0
  65. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/coefficients.py +0 -0
  66. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/cuda_contract.py +0 -0
  67. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/engine.py +0 -0
  68. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/exact_gemm.py +0 -0
  69. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/lane_plan.py +0 -0
  70. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/pre_cuda.py +0 -0
  71. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/rail_planning.py +0 -0
  72. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/signed.py +0 -0
  73. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/weighted.py +0 -0
  74. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/wide.py +0 -0
  75. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine.egg-info/dependency_links.txt +0 -0
  76. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine.egg-info/entry_points.txt +0 -0
  77. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine.egg-info/not-zip-safe +0 -0
  78. {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine.egg-info/top_level.txt +0 -0
  79. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_capacity.py +0 -0
  80. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_coefficients.py +0 -0
  81. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_cuda_contract.py +0 -0
  82. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_exact_gemm.py +0 -0
  83. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_pre_cuda.py +0 -0
  84. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_pre_cuda_assets.py +0 -0
  85. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_rail_planning.py +0 -0
  86. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_rns.py +0 -0
  87. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_session.py +0 -0
  88. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_signed.py +0 -0
  89. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_weighted.py +0 -0
  90. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_weighted_benchmark.py +0 -0
  91. {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_wide.py +0 -0
@@ -0,0 +1,66 @@
1
+ # G4 Series 1 — Frozen Tesla T4 Evidence
2
+
3
+ G4 Series 1 is frozen. This public layer exposes the frozen headline benchmark evidence plus a replay-only Tesla T4 runtime.
4
+
5
+ ## Two separate frozen claims
6
+
7
+ ### Exact integer clean sweep
8
+
9
+ On the frozen `T4GL-1024-v1` suite, the final decision record contains:
10
+
11
+ - 1,024 declared GEMM shapes
12
+ - 938 exact integer wins
13
+ - 86 NVIDIA floating wins
14
+ - 91.60% exact-win coverage
15
+ - exact replay passed before and after timing on all 1,024 shapes
16
+ - Tesla T4, compute capability 7.5
17
+
18
+ The floating landscape uses FP16-input cuBLASLt configurations; the retained accumulation mode may be FP16 or FP32 for a given shape. This is a resident-data kernel benchmark.
19
+
20
+ ### Dynamic exact-rational campaign
21
+
22
+ The separately frozen G416 campaign records:
23
+
24
+ - 1,024 evaluated shapes
25
+ - 870 certified exact-rational wins
26
+ - 154 unresolved shapes at archive freeze
27
+ - 84.96% certified exact-rational coverage
28
+ - 31 paired timing blocks for every certified winner
29
+ - actual non-integer inputs for every certified winner
30
+ - range proof passed for every certified winner
31
+ - FP16 value-set proof passed for every certified winner
32
+
33
+ **Do not conflate the two percentages.** `938/1024` is the frozen exact-integer clean-sweep result. `870/1024` is the separately certified dynamic exact-rational result.
34
+
35
+ ## Python API
36
+
37
+ ```python
38
+ import rns_engine as rns
39
+
40
+ rns.g4_results()
41
+ rns.g4_results("integer")
42
+ rns.g4_results("rational")
43
+
44
+ # Tesla T4 only
45
+ rns.g4_benchmark("quick")
46
+ rns.g4_benchmark("standard")
47
+ rns.g4_benchmark("full")
48
+ ```
49
+
50
+ `g4_results()` reports the frozen headline evidence. `g4_benchmark()` physically replays the **dynamic exact-rational** comparison on a Tesla T4 and re-applies the frozen 31-paired-block certification rule. It does not run G4 search.
51
+
52
+ ## Replay-config provenance boundary
53
+
54
+ Most full rational configs are preserved directly by the frozen work artifacts. Where the frozen result row retained the winner identity but omitted physical fields such as padding or stage ID, the one-time private build enumerated every full frozen candidate matching that retained identity. The public replay selects only within that identity class before measurement and does not claim which omitted member was historical. No timing-based historical config guess is permitted.
55
+
56
+ For floating cuBLASLt baselines, Series 1 originally retained the opaque algorithm object returned by `cublasLtMatmulAlgoGetHeuristic`. The public replay therefore re-queries that same heuristic API on the frozen T4 descriptor/padding context and accepts only returned algorithms whose visible identity and workspace match the archived option. It does not attempt to reconstruct NVIDIA's opaque algorithm object from visible fields with `cublasLtMatmulAlgoInit`.
57
+
58
+ The resulting provenance counts are stored in `g4s1_t4_runtime.json` and included in benchmark output.
59
+
60
+ ## Packaged public evidence/runtime
61
+
62
+ - `g4s1_public_summary.json` — the two frozen headline claims and provenance metadata.
63
+ - `g4s1_t4_runtime.json` — Tesla T4 runtime integrity, hardware boundary, config provenance, and the ordered replay-payload manifest.
64
+ - `g4s1_t4_replay.part*.b64` — chunked Base64/XZ representation of the stripped replay executable. Every chunk is hashed individually; after reassembly the combined payload is hashed again; after decoding and decompression the executable must match SHA-256 `addce9d253b67f18944d558894e0d2e3273a9bd8de5c78f969bbc6bc5e763a66` or `g4_benchmark()` refuses to run.
65
+
66
+ The detailed G4 search machinery is not needed to reproduce the public replay result. The public package contains the evidence and runtime required by `g4_results()` and `g4_benchmark()`.
@@ -3,6 +3,7 @@ include README.md
3
3
  include CAPACITY_PLANNING.md
4
4
  include PRE_CUDA_READINESS.md
5
5
  include CUDA_PARALLEL_LANES.md
6
+ include G4_SERIES1_EVIDENCE.md
6
7
  recursive-include benchmarks *.py
7
8
  recursive-include colab *.ipynb
8
9
  recursive-include tests *.py
@@ -0,0 +1,481 @@
1
+ Metadata-Version: 2.4
2
+ Name: rns_engine
3
+ Version: 0.11.0
4
+ Summary: Exact RNS engine with session/cache API.
5
+ Author: Evan Wesley
6
+ License-Expression: AGPL-3.0-only
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Programming Language :: Python :: 3 :: Only
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: Programming Language :: Python :: 3.14
14
+ Classifier: Programming Language :: C++
15
+ Classifier: Operating System :: OS Independent
16
+ Requires-Python: <3.15,>=3.10
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: numpy>=1.23
20
+ Provides-Extra: test
21
+ Requires-Dist: pytest; extra == "test"
22
+ Requires-Dist: tomli>=1; python_version < "3.11" and extra == "test"
23
+ Requires-Dist: numpy==2.2.6; python_version < "3.14" and extra == "test"
24
+ Requires-Dist: numpy==2.4.5; python_version >= "3.14" and extra == "test"
25
+ Dynamic: license-file
26
+
27
+ # rns_engine
28
+
29
+ **Exact arithmetic without the usual speed-or-accuracy tradeoff.**
30
+
31
+ We tested two separate exact-arithmetic systems **directly against NVIDIA's own optimized cuBLASLt FP16-input GEMM implementation** on the same class of NVIDIA Tesla T4 GPU across **1,024 different matrix-multiplication shapes**.
32
+
33
+ The tests were run on **standard Tesla T4 hardware provided through Google Colab** — publicly available commodity cloud hardware, not a custom GPU, private lab rig, or specially modified machine.
34
+
35
+ | Exact arithmetic tested | Faster than NVIDIA | Win rate |
36
+ |---|---:|---:|
37
+ | **Exact integer GEMM** | **938 / 1,024 shapes** | **91.60%** |
38
+ | **Exact rational GEMM** | **870 / 1,024 shapes** | **84.96%** |
39
+
40
+ These are **two separate results**. The integer benchmark and rational benchmark were run and scored independently.
41
+
42
+ For the rational result, we also built a separate public replay runtime and reran all 1,024 shapes from scratch on a standard Google Colab Tesla T4:
43
+
44
+ - **1,024 / 1,024** exact rational calculations reproduced the correct mathematical result.
45
+ - **834 / 1,024** were faster than NVIDIA's FP16 implementation on the fresh replay.
46
+ - **114 / 1,024** were slower than NVIDIA's FP16 implementation.
47
+ - **76 / 1,024** were statistical ties.
48
+
49
+ In both cases, we squared our exact arithmetic directly against **NVIDIA's own optimized FP16 GEMM implementation on the same publicly available Tesla T4 hardware** — and won the speed comparison across the large majority of the tested matrix sizes, **without accepting the usual tradeoff between speed and accuracy. You can have both.**
50
+
51
+ > **Exact** describes correctness. **Win** describes speed. A shape can remain mathematically exact even when NVIDIA wins the timing comparison.
52
+
53
+ ---
54
+
55
+ ## Reproduce the evidence yourself
56
+
57
+ Install the package:
58
+
59
+ ```bash
60
+ pip install -U rns_engine
61
+ ```
62
+
63
+ Show the frozen Series 1 evidence without requiring a GPU:
64
+
65
+ ```python
66
+ import rns_engine as rns
67
+
68
+ rns.g4_results()
69
+ rns.g4_results("integer")
70
+ rns.g4_results("rational")
71
+ ```
72
+
73
+ On a **Tesla T4 / compute capability 7.5**, physically rerun the exact-rational comparison:
74
+
75
+ ```python
76
+ import rns_engine as rns
77
+
78
+ rns.g4_benchmark("quick") # 24 shapes
79
+ rns.g4_benchmark("standard") # 128 shapes
80
+ rns.g4_benchmark("full") # all 1,024 shapes
81
+ ```
82
+
83
+ `g4_benchmark()` is deliberately fail-closed. Series 1 is frozen to the Tesla T4; running on a different GPU would be a different benchmark.
84
+
85
+ The live benchmark is **replay-only**: it reruns the frozen Series 1 implementations rather than performing a new G4 search.
86
+
87
+ See [`G4_SERIES1_EVIDENCE.md`](G4_SERIES1_EVIDENCE.md) for the benchmark protocol, claim boundaries, and replay provenance.
88
+
89
+ ---
90
+
91
+ ## What is G4?
92
+
93
+ G4 is the autonomous optimization/research system that discovered the benchmarked implementations.
94
+
95
+ This repository exposes the **results and a reproducible replay runtime**.
96
+
97
+ ---
98
+
99
+ ## What `rns_engine` is
100
+
101
+ `rns_engine` is a Python/C++ toolkit for exact arithmetic built around Residue Number Systems (RNS), signed range certificates, exact reconstruction, and low-precision hardware pipelines.
102
+
103
+ The package includes:
104
+
105
+ - exact unsigned and centered-signed integer arithmetic;
106
+ - no-wrap range certificates;
107
+ - fused weighted reconstruction of signed INT32 partials;
108
+ - exact shared-scale rational GEMM reference tools;
109
+ - local and global GEMM capacity planning;
110
+ - multi-rail exact reconstruction tools;
111
+ - Tensor-Core / CUDA integration contracts and fixtures;
112
+ - frozen G4 Series 1 benchmark evidence and Tesla T4 replay.
113
+
114
+ The core idea is simple: perform arithmetic across independent modular rails, then reconstruct the exact result when the declared range proves that the answer is unique.
115
+
116
+ ---
117
+
118
+ ## Install
119
+
120
+ ```bash
121
+ pip install rns_engine
122
+ ```
123
+
124
+ Supported Python versions: **3.10–3.14**.
125
+
126
+ Prebuilt wheels are available for supported Linux x86-64, macOS Intel/Apple silicon, and Windows x64 Python targets.
127
+
128
+ ---
129
+
130
+ ## Quick start: exact integer arithmetic
131
+
132
+ ```python
133
+ import numpy as np
134
+ import rns_engine as rns
135
+
136
+ x = np.array([123456789, 999999999], dtype=np.uint64)
137
+ y = np.array([987654321, 111111111], dtype=np.uint64)
138
+
139
+ ex = rns.encode(x)
140
+ ey = rns.encode(y)
141
+
142
+ exact_add = rns.decode(*rns.add(*ex, *ey))
143
+ exact_mul = rns.decode(*rns.mul(*ex, *ey))
144
+ ```
145
+
146
+ You can remain in residue space across multiple operations and decode once:
147
+
148
+ ```python
149
+ s1 = rns.add(*ex, *ey)
150
+ s2 = rns.mul(*s1, *ey)
151
+ s3 = rns.sub(*s2, *ex)
152
+ out = rns.decode(*s3)
153
+ ```
154
+
155
+ For repeated work, use a session:
156
+
157
+ ```python
158
+ session = rns.Session(cache_capacity=32)
159
+ encoded = session.encode(x)
160
+ result = session.mul(session.add(encoded, encoded), encoded)
161
+ out = session.decode(result)
162
+ ```
163
+
164
+ ---
165
+
166
+ ## Signed exact arithmetic and no-wrap certificates
167
+
168
+ ```python
169
+ import numpy as np
170
+ import rns_engine as rns
171
+
172
+ values = np.array([-5, 0, 7], dtype=np.int64)
173
+ rails = rns.encode_signed(values)
174
+ round_trip = rns.decode_signed(*rails)
175
+
176
+ assert np.array_equal(round_trip, values)
177
+ ```
178
+
179
+ `encode_signed(...)` rejects values outside the supported centered range instead of silently wrapping them.
180
+
181
+ For a mathematical result to be uniquely recoverable as a signed value, you also need an independent bound proving:
182
+
183
+ ```text
184
+ |result| < M / 2
185
+ ```
186
+
187
+ Use a range certificate:
188
+
189
+ ```python
190
+ certificate = rns.certify_signed_bound(max_abs_bound=1_000_000)
191
+ certificate.require_unique()
192
+
193
+ print(certificate.headroom)
194
+ ```
195
+
196
+ For a signed dot product or one GEMM output entry:
197
+
198
+ ```python
199
+ certificate = rns.certify_signed_dot_bound(
200
+ inner_dimension=5120,
201
+ left_abs_bound=127,
202
+ right_abs_bound=127,
203
+ )
204
+
205
+ certificate.require_unique()
206
+ ```
207
+
208
+ The conservative bound is:
209
+
210
+ ```text
211
+ output bound
212
+ =
213
+ inner dimension × left bound × right bound + addend bound
214
+ ```
215
+
216
+ `decode_signed()` gives the centered representative. **It does not, by itself, prove that an unknown mathematical result did not wrap.** Use the range-certificate APIs when uniqueness matters.
217
+
218
+ ---
219
+
220
+ ## Exact rational GEMM reference path
221
+
222
+ `rns_engine` includes shared-scale exact matrix objects and a correctness-first wide-RNS reference path:
223
+
224
+ ```python
225
+ import numpy as np
226
+ import rns_engine as rns
227
+
228
+ left = rns.SharedScaleMatrix(
229
+ np.array([[2**40 + 3, -17], [29, 2**35 - 5]], dtype=object),
230
+ scale=6,
231
+ )
232
+
233
+ right = rns.SharedScaleMatrix(
234
+ np.array([[31, -(2**30) + 9], [2**33 + 1, 43]], dtype=object),
235
+ scale=35,
236
+ )
237
+
238
+ receipt = rns.exact_shared_scale_gemm(
239
+ left,
240
+ right,
241
+ config=rns.WideRNSConfig.balanced_seven_rail(),
242
+ left_plane_count=8,
243
+ right_plane_count=8,
244
+ )
245
+
246
+ assert receipt.exact_match
247
+ assert receipt.output_scale == 210
248
+ result = receipt.as_matrix()
249
+ ```
250
+
251
+ The public G4 T4 benchmark is a **frozen replay artifact** for the Series 1 exact-rational discoveries; it is not a general-purpose CUDA backend for arbitrary `rns_engine` operations.
252
+
253
+ ---
254
+
255
+ ## Tensor-Core / INT32 partial reconstruction
256
+
257
+ For digit-plane, chunked-GEMM, and Tensor-Core pipelines, `rns_engine` can fuse signed INT32 partial outputs with exact positional weights:
258
+
259
+ ```python
260
+ import numpy as np
261
+ import rns_engine as rns
262
+
263
+ partials = np.array(
264
+ [
265
+ [[1, -2], [3, -4]],
266
+ [[5, 6], [-7, -8]],
267
+ [[-9, 10], [11, -12]],
268
+ ],
269
+ dtype=np.int32,
270
+ )
271
+
272
+ receipt = rns.accumulate_weighted_int32(
273
+ partials,
274
+ weights=[1, -3, 8],
275
+ require_unique=True,
276
+ )
277
+
278
+ exact = receipt.decode_signed()
279
+ ```
280
+
281
+ The conservative bound is:
282
+
283
+ ```text
284
+ max_abs_bound
285
+ =
286
+ sum(abs(weight[t]) × max_abs(partial[t]))
287
+ ```
288
+
289
+ The proof receipt retains the original arbitrary-precision weights while execution uses lawful residues modulo the RNS product.
290
+
291
+ ---
292
+
293
+ ## GEMM capacity planning
294
+
295
+ Two safety questions must remain separate:
296
+
297
+ 1. Does each raw grouped coefficient fit the native signed accumulator?
298
+ 2. Does the final weighted result fit uniquely inside the global RNS modulus product?
299
+
300
+ ```python
301
+ import rns_engine as rns
302
+
303
+ local = rns.plan_grouped_coefficient_capacity(
304
+ inner_dimension=5120,
305
+ left_digit_abs_bounds=[127] * 8,
306
+ right_digit_abs_bounds=[127] * 8,
307
+ accumulator_bits=32,
308
+ )
309
+
310
+ global_plan = rns.plan_digit_plane_gemm_capacity(
311
+ inner_dimension=5120,
312
+ radix=128,
313
+ left_digit_abs_bounds=[127] * 8,
314
+ right_digit_abs_bounds=[127] * 8,
315
+ )
316
+
317
+ print(local.safe)
318
+ print(global_plan.current_unique)
319
+ ```
320
+
321
+ See [`CAPACITY_PLANNING.md`](CAPACITY_PLANNING.md) for the exact laws and limits.
322
+
323
+ ---
324
+
325
+ ## How the core four-rail engine works
326
+
327
+ The default engine decomposes values across four coprime rails:
328
+
329
+ ```text
330
+ 127
331
+ 8191
332
+ 65536
333
+ 524287
334
+ ```
335
+
336
+ Their product is:
337
+
338
+ ```text
339
+ M = 35,742,890,181,197,824
340
+ ```
341
+
342
+ Unsigned reconstruction lives in:
343
+
344
+ ```text
345
+ [0, M)
346
+ ```
347
+
348
+ The centered signed interpretation is:
349
+
350
+ ```text
351
+ [-17,871,445,090,598,912,
352
+ 17,871,445,090,598,911]
353
+ ```
354
+
355
+ Arithmetic runs independently on the rails and reconstructs the canonical value with CRT/Garner-style reconstruction.
356
+
357
+ For wider exact GEMM work, the package also contains correctness-first seven-rail reference configurations and capacity-planning tools.
358
+
359
+ ---
360
+
361
+ ## API at a glance
362
+
363
+ ### Core arithmetic
364
+
365
+ ```text
366
+ encode / decode
367
+ encode_signed / decode_signed
368
+ add / sub / mul / div_ / fma
369
+ affine_repeat
370
+ Session / SignedSession
371
+ ```
372
+
373
+ ### Proof and range tools
374
+
375
+ ```text
376
+ certify_signed_bound
377
+ certify_signed_dot_bound
378
+ certify_weighted_sum_bound
379
+ plan_signed_capacity
380
+ plan_weighted_sum_capacity
381
+ plan_digit_plane_gemm_capacity
382
+ plan_grouped_coefficient_capacity
383
+ ```
384
+
385
+ ### Exact GEMM / wide reference tools
386
+
387
+ ```text
388
+ WideRNSConfig
389
+ SharedScaleMatrix
390
+ exact_integer_matmul
391
+ exact_shared_scale_gemm
392
+ decompose_signed_radix
393
+ reconstruct_signed_radix
394
+ grouped_plane_gemm
395
+ reconstruct_grouped_partials
396
+ accumulate_weighted_int32_wide
397
+ ```
398
+
399
+ ### CUDA / backend verification
400
+
401
+ ```text
402
+ CudaGemmFixture
403
+ ExactPipelineBackend
404
+ CpuExactPipelineBackend
405
+ build_cuda_gemm_fixture
406
+ verify_backend
407
+ run_pre_cuda_readiness
408
+ ```
409
+
410
+ ### G4 evidence and reproduction
411
+
412
+ ```text
413
+ g4_results
414
+ g4_benchmark
415
+ ```
416
+
417
+ Use `rns.info()` for the installed engine's current range, moduli, version, and native capability summary.
418
+
419
+ ---
420
+
421
+ ## Scope and limitations
422
+
423
+ The benchmark claims in this repository are intentionally narrow and reproducible:
424
+
425
+ - **G4 Series 1 is a Tesla T4 benchmark.** Results on another GPU are a different experiment.
426
+ - The reported scores cover the declared **1,024 GEMM shapes**, not every possible matrix size.
427
+ - The **integer and rational results are separate benchmarks** and should not be combined into one percentage.
428
+ - `g4_benchmark()` replays frozen discoveries; it does not rerun G4's search process.
429
+ - Fresh timing classifications can move with clocks, driver state, and normal measurement noise. Mathematical exactness must not move.
430
+ - Exact signed reconstruction requires an independently valid range bound; modular correctness alone does not prove no wrap.
431
+ - The public Series 1 replay runtime is a benchmark artifact, not a general CUDA implementation of every `rns_engine` API.
432
+
433
+ ### Division
434
+
435
+ Division requires the divisor to be invertible on every default rail:
436
+
437
+ - `b % 127 != 0`
438
+ - `b % 8191 != 0`
439
+ - `b` must be odd for modulus `65536`
440
+ - `b % 524287 != 0`
441
+
442
+ ---
443
+
444
+ ## Additional technical documentation
445
+
446
+ - [`G4_SERIES1_EVIDENCE.md`](G4_SERIES1_EVIDENCE.md) — frozen G4 evidence, replay protocol, and privacy boundary
447
+ - [`CAPACITY_PLANNING.md`](CAPACITY_PLANNING.md) — local/global exactness and accumulator capacity
448
+ - [`PRE_CUDA_READINESS.md`](PRE_CUDA_READINESS.md) — correctness oracle and CUDA integration contract
449
+ - [`CUDA_PARALLEL_LANES.md`](CUDA_PARALLEL_LANES.md) — parallel rail planning
450
+ - [`colab/T4_EXACT_GEMM_BRINGUP.ipynb`](colab/T4_EXACT_GEMM_BRINGUP.ipynb) — earlier CUDA bring-up fixture
451
+
452
+ ---
453
+
454
+ ## Build from source
455
+
456
+ ```bash
457
+ git clone https://github.com/playfularchitect/rns_engine.git
458
+ cd rns_engine
459
+ pip install -e .
460
+ python -m pytest tests/ -v
461
+ ```
462
+
463
+ Requirements:
464
+
465
+ - Python 3.10–3.14
466
+ - C++17 compiler
467
+ - build dependencies declared in `pyproject.toml`
468
+
469
+ The release workflow builds and tests supported wheels across Linux, macOS, and Windows.
470
+
471
+ ---
472
+
473
+ ## License
474
+
475
+ **AGPL-3.0-only**
476
+
477
+ If this software is used in a network service, the AGPL requires modified source to be made available to users. Commercial licensing for proprietary or closed-source use is available.
478
+
479
+ Inquiries: `ewesley541@gmail.com`
480
+
481
+ Copyright 2026 Evan Wesley