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.
- rns_engine-0.11.0/G4_SERIES1_EVIDENCE.md +66 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/MANIFEST.in +1 -0
- rns_engine-0.11.0/PKG-INFO +481 -0
- rns_engine-0.11.0/README.md +455 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/pyproject.toml +24 -5
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/__init__.py +4 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_public_summary.json +87 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part01.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part02.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part03.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part04.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part05.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part06a.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part06b.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part07.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part08a.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part08b.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part09.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part10a.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part10b1.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part10b2.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part10b4.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part11.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part12a.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part12b.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part13.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part14a.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part14b.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part15a.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part15b.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part16a.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part16b.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17a.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b1.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b2a.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b2b1.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b2b2.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_replay.part17b2b3.b64 +1 -0
- rns_engine-0.11.0/src/rns_engine/data/g4s1_t4_runtime.json +104 -0
- rns_engine-0.11.0/src/rns_engine/g4_benchmark.py +525 -0
- rns_engine-0.11.0/src/rns_engine/g4_results.py +114 -0
- rns_engine-0.11.0/src/rns_engine.egg-info/PKG-INFO +481 -0
- rns_engine-0.11.0/src/rns_engine.egg-info/SOURCES.txt +83 -0
- rns_engine-0.11.0/src/rns_engine.egg-info/requires.txt +13 -0
- rns_engine-0.11.0/tests/test_g4_benchmark.py +31 -0
- rns_engine-0.11.0/tests/test_g4_results.py +42 -0
- rns_engine-0.11.0/tests/test_packaging.py +40 -0
- rns_engine-0.9.0/PKG-INFO +0 -565
- rns_engine-0.9.0/README.md +0 -542
- rns_engine-0.9.0/src/rns_engine.egg-info/PKG-INFO +0 -565
- rns_engine-0.9.0/src/rns_engine.egg-info/SOURCES.txt +0 -45
- rns_engine-0.9.0/src/rns_engine.egg-info/requires.txt +0 -5
- rns_engine-0.9.0/tests/test_packaging.py +0 -8
- {rns_engine-0.9.0 → rns_engine-0.11.0}/CAPACITY_PLANNING.md +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/CUDA_PARALLEL_LANES.md +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/LICENSE +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/PRE_CUDA_READINESS.md +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/benchmarks/weighted_int32_baseline.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/colab/T4_EXACT_GEMM_BRINGUP.ipynb +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/setup.cfg +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/setup.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/_core.cpp +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/_weighted.cpp +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/capacity.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/coefficients.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/cuda_contract.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/engine.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/exact_gemm.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/lane_plan.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/pre_cuda.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/rail_planning.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/signed.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/weighted.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine/wide.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine.egg-info/dependency_links.txt +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine.egg-info/entry_points.txt +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine.egg-info/not-zip-safe +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/src/rns_engine.egg-info/top_level.txt +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_capacity.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_coefficients.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_cuda_contract.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_exact_gemm.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_pre_cuda.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_pre_cuda_assets.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_rail_planning.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_rns.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_session.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_signed.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_weighted.py +0 -0
- {rns_engine-0.9.0 → rns_engine-0.11.0}/tests/test_weighted_benchmark.py +0 -0
- {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()`.
|
|
@@ -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
|