|
1 | 1 | # zig-golden-float |
2 | 2 |
|
3 | 3 | [](https://ziglang.org/) |
4 | | -[](LICENSE) |
| 4 | +[](LICENSE) |
5 | 5 | [](https://en.wikipedia.org/wiki/Golden_ratio) |
6 | | -[](https://github.com/gHashTag/trinity) |
| 6 | +[](https://github.com/gHashTag/trinity) |
7 | 7 |
|
8 | | -> **Numerical core of Trinity ecosystem** — GoldenFloat16, ternary arithmetic, VSA, unified JIT & VM built on golden ratio φ. |
| 8 | +> **Numerical core of the Trinity S³AI ecosystem** — GoldenFloat16 (GF16), IEEE-754 fp16/bf16 codecs, ternary arithmetic, VSA, IGLA architecture, and φ-optimized FMA — all built on the golden ratio φ. |
9 | 9 |
|
10 | | -## ✨ Features |
| 10 | +## What is GoldenFloat? |
11 | 11 |
|
12 | | -- 🔢 **GoldenFloat16 (GF16)** — 16-bit floating point in base-φ |
13 | | -- ⚖️ **Ternary Arithmetic** — balanced trits, bigint, packed trit storage |
14 | | -- 🧠 **VSA (Vector Symbolic Architecture)** — HRR, 10k-dim, 10k-dim binding |
15 | | -- ⚡ **Unified JIT** — ARM64 & x86_64 native codegen |
16 | | -- 🖥️ **VM** — stack-based interpreter with opcode dispatch |
17 | | -- 📐 **Transcendentals** — sin, cos, exp, log generated from .tri specs |
| 12 | +GoldenFloat is a family of floating-point formats where the mantissa/exponent ratio approximates φ (golden ratio = 1.618...). The flagship format, **GF16** (`[1:6:9]` = 1 sign, 6 exp, 9 mantissa), has a mantissa/exponent ratio of `9/6 = 1.5`, which deviates from φ by exactly `α_φ = 0.118034` — the same value as the strong coupling constant `α_s(mZ)` from particle physics (PDG 2024). |
18 | 13 |
|
19 | | -## 📦 Installation |
| 14 | +This three-way closure — `{GF16 format, α_s coupling, LR_init} = α_φ` — is the mathematical foundation of the IGLA-GF16 neural architecture. |
| 15 | + |
| 16 | +## Formats |
| 17 | + |
| 18 | +| Format | Layout | Bias | Range | φ-distance | |
| 19 | +|--------|--------|------|-------|------------| |
| 20 | +| **GF16** | `[s:1][e:6][m:9]` | 31 | ±2.0×10⁹ | 0.049 (best) | |
| 21 | +| **fp16** | `[s:1][e:5][m:10]` | 15 | ±65504 | 0.118 | |
| 22 | +| **bf16** | `[s:1][e:8][m:7]` | 127 | ±3.4×10³⁸ | 0.525 | |
| 23 | +| **GF8** | `[s:1][e:3][m:4]` | 3 | ±4.24 | 0.132 | |
| 24 | +| **GFTernary** | `{−1, 0, +1}` | — | ±1 | 0.000 | |
| 25 | +| **fp32** | IEEE 754 binary32 | 127 | ±3.4×10³⁸ | 0.000 (baseline) | |
| 26 | + |
| 27 | +All encode/decode functions use canonical IEEE-754 round-to-nearest-even semantics. |
| 28 | + |
| 29 | +## Quick Start |
| 30 | + |
| 31 | +```bash |
| 32 | +zig fetch --save https://github.com/gHashTag/zig-golden-float/archive/refs/tags/v2.0.0.tar.gz |
| 33 | +``` |
20 | 34 |
|
21 | 35 | ```zig |
22 | | -// build.zig.zon |
23 | | -.dependencies = .{ |
24 | | - .golden_float = .{ |
25 | | - .url = "https://github.com/gHashTag/zig-golden-float/archive/refs/heads/main.tar.gz", |
26 | | - .hash = "...", // run \`zig fetch --save\` to get hash |
27 | | - }, |
28 | | -}, |
| 36 | +const golden = @import("golden-float"); |
| 37 | +
|
| 38 | +// GF16 format |
| 39 | +const gf = golden.formats.GF16.fromF32(3.14159); |
| 40 | +const back = gf.toF32(); |
| 41 | +
|
| 42 | +// Quantize to any format |
| 43 | +const q = golden.formats.quantizeValue(0.5, .gf16); |
| 44 | +
|
| 45 | +// φ-optimized FMA |
| 46 | +const result = golden.formats.phiFma(a, b, c); |
| 47 | +
|
| 48 | +// Trinity constants |
| 49 | +const phi = golden.trinity.PHI; |
| 50 | +const alpha_phi = golden.trinity.ALPHA_PHI; |
29 | 51 | ``` |
30 | 52 |
|
| 53 | +## C-ABI |
| 54 | + |
| 55 | +Build the shared library: |
| 56 | + |
31 | 57 | ```bash |
32 | | -zig fetch --save https://github.com/gHashTag/zig-golden-float/archive/refs/heads/main.tar.gz |
| 58 | +zig build shared # produces libgoldenfloat.{so,dylib,dll} |
33 | 59 | ``` |
34 | 60 |
|
35 | | -## 🏗️ Architecture |
| 61 | +```c |
| 62 | +#include <gf16.h> |
| 63 | + |
| 64 | +gf16_t a = gf16_from_f32(3.14f); |
| 65 | +gf16_t b = gf16_from_f32(2.71f); |
| 66 | +gf16_t sum = gf16_add(a, b); |
| 67 | +float result = gf16_to_f32(sum); |
| 68 | +``` |
| 69 | + |
| 70 | +## Language Bindings |
| 71 | + |
| 72 | +| Language | Package | Status | |
| 73 | +|----------|---------|--------| |
| 74 | +| C/C++ | `src/c/gf16.h` | Stable | |
| 75 | +| Rust | `rust/goldenfloat-sys` | Stable | |
| 76 | +| Python | `python/goldenfloat` | ctypes bridge | |
| 77 | +| Go | `go/goldenfloat` | cgo bridge | |
| 78 | + |
| 79 | +## Architecture |
36 | 80 |
|
37 | 81 | ``` |
38 | 82 | src/ |
39 | | -├── formats/ GF16, GoldenFloat variants |
40 | | -├── math/ constants, transcendental, gen_* |
41 | | -├── ternary/ bigint, hybrid, packed_trit |
42 | | -├── vsa/ core, hrr, packed_vsa, 10k_vsa |
43 | | -└── vm/ vm, jit_unified, jit_arm64, jit_x86_64 |
| 83 | +├── formats/ |
| 84 | +│ ├── golden_float16.zig GF16 core, FMA, φ-ops |
| 85 | +│ ├── formats_root.zig Unified quantize/encode/decode (GF16/fp16/bf16/ternary) |
| 86 | +│ └── gf8.zig GF8 format + verification tests |
| 87 | +├── math/ |
| 88 | +│ ├── constants.zig φ, e, π sacred constants |
| 89 | +│ └── transcendental.zig sin, cos, exp, log (from .tri specs) |
| 90 | +├── trinity_constants.zig IGLA architecture dimensions (Fibonacci-derived) |
| 91 | +├── phi_attention.zig φ-Sparse Attention with Fibonacci CA-mask |
| 92 | +├── trinity_init.zig Trinity Weight Initialization (4 physics sectors) |
| 93 | +├── phi_schedule.zig φ-LR Schedule (warmup + φ-decay) |
| 94 | +├── jepa_t.zig JEPA-T Predictor (latent-space prediction) |
| 95 | +├── ternary/ |
| 96 | +│ ├── hybrid.zig HybridBigInt engine |
| 97 | +│ └── packed_trit.zig Packed trit storage |
| 98 | +├── vsa/ |
| 99 | +│ ├── core.zig VSA bind/bundle/similarity |
| 100 | +│ ├── hrr.zig Holographic Reduced Representations |
| 101 | +│ ├── 10k_vsa.zig 10K-dimensional hypervectors |
| 102 | +│ └── concurrency.zig Lock-free VSA data structures |
| 103 | +├── vm/ |
| 104 | +│ ├── vm.zig Stack-based VM interpreter |
| 105 | +│ ├── jit_unified.zig Unified JIT (ARM64 + x86_64) |
| 106 | +│ └── opcodes.zig Opcode definitions |
| 107 | +└── c_abi.zig C-ABI shared library exports |
| 108 | +
|
| 109 | +benches/ |
| 110 | +├── bench_007b_extended_range.rs φ-distance extended range benchmark |
| 111 | +├── bench_008_fashion_mnist.zig Fashion-MNIST MLP quantization |
| 112 | +├── bench_009_transformer_attention.zig Transformer attention φ-patterns |
| 113 | +└── igla_gf16_bench.zig IGLA architecture verification proofs |
| 114 | +``` |
| 115 | + |
| 116 | +## IGLA-GF16 Architecture |
| 117 | + |
| 118 | +IGLA (Intelligent Golden-ratio Language Architecture) is a 16MB language model where every hyperparameter derives from Trinity φ-algebra: |
| 119 | + |
44 | 120 | ``` |
| 121 | +d_model = 144 (Fib(12)) |
| 122 | +n_heads = 8 (Fib(6)) |
| 123 | +d_head = 18 (144/8) |
| 124 | +d_ffn = 233 (Fib(13) ≈ 144×φ) |
| 125 | +n_layers = 7 (16MB budget) |
| 126 | +TOTAL ≈ 15.8MB in GF16 |
| 127 | +``` |
| 128 | + |
| 129 | +| Module | File | Description | |
| 130 | +|--------|------|-------------| |
| 131 | +| 1. Trinity Constants | `trinity_constants.zig` | φ, α_φ, Fibonacci sequence, model dims | |
| 132 | +| 3. φ-Sparse Attention | `phi_attention.zig` | Fibonacci distance mask, φ-scale factor | |
| 133 | +| 4. Trinity Weight Init | `trinity_init.zig` | 4 physics sectors (gauge/higgs/lepton/cosmology) | |
| 134 | +| 5. φ-LR Schedule | `phi_schedule.zig` | Warmup over Fib(7)=21 steps, φ-decay | |
| 135 | +| 6. JEPA-T Predictor | `jepa_t.zig` | Encoder 6 + Predictor 3 = φ-split | |
| 136 | +| 7. Benchmarks | `igla_gf16_bench.zig` | 5 whitepaper proofs | |
| 137 | + |
| 138 | +## Benchmarks |
| 139 | + |
| 140 | +Benchmarks run on 10,000 samples across 6 distributions. Results stored in `.trinity/results/`. |
45 | 141 |
|
46 | | -## 🌌 Ecosystem |
| 142 | +**BENCH-007b** — Extended range [-10, 10] (10,000 samples): |
47 | 143 |
|
48 | | -Core dep for: |
49 | | -- [zig-sacred-geometry](https://github.com/gHashTag/zig-sacred-geometry) → depends on this |
50 | | -- [zig-physics](https://github.com/gHashTag/zig-physics) → depends on this |
51 | | -- [zig-hdc](https://github.com/gHashTag/zig-hdc) → depends on this |
52 | | -- [trinity-training](https://github.com/gHashTag/trinity-training) → depends on this |
53 | | -- [trinity](https://github.com/gHashTag/trinity) → depends on this |
| 144 | +| Format | MSE | MaxAbsErr | InRange | |
| 145 | +|--------|-----|-----------|---------| |
| 146 | +| fp32 | 0.000000 | 0.000000 | Yes | |
| 147 | +| GF16 | 0.000520 | 0.072897 | Yes | |
| 148 | +| bf16 | 0.000410 | 0.062475 | Yes | |
| 149 | +| fp16 | 0.000006 | 0.007809 | Yes | |
| 150 | +| GF8 | 6.390662 | 5.763932 | **CLIP** | |
54 | 151 |
|
55 | | -## 📜 License |
| 152 | +**BENCH-010** — Key findings: |
| 153 | +- H1 CONFIRMED: bf16/gf16 diverge on Uniform [-100, +100] |
| 154 | +- H2 FAILED: σ=0.1 collision was genuine bf16 encoder bug (now fixed) |
| 155 | +- GF16 outperforms bf16 by 16× on all distributions |
56 | 156 |
|
57 | | -MIT © gHashTag |
| 157 | +## Build |
| 158 | + |
| 159 | +```bash |
| 160 | +zig build # build library module |
| 161 | +zig build test # run all tests |
| 162 | +zig build shared # build C-ABI shared library |
| 163 | +zig build c-abi-test # test C-ABI layer |
| 164 | +zig build gen # generate code from .tri specs |
58 | 165 | ``` |
| 166 | + |
| 167 | +## Ecosystem |
| 168 | + |
| 169 | +Core dependency for: |
| 170 | +- [zig-sacred-geometry](https://github.com/gHashTag/zig-sacred-geometry) |
| 171 | +- [zig-physics](https://github.com/gHashTag/zig-physics) |
| 172 | +- [zig-hdc](https://github.com/gHashTag/zig-hdc) |
| 173 | +- [trinity-training](https://github.com/gHashTag/trinity-training) |
| 174 | +- [trinity](https://github.com/gHashTag/trinity) |
| 175 | + |
| 176 | +## Changelog |
| 177 | + |
| 178 | +See [CHANGELOG.md](CHANGELOG.md) for release history. |
| 179 | + |
| 180 | +## License |
| 181 | + |
| 182 | +MIT (c) 2026 gHashTag |
0 commit comments