zkf 0.9.0__tar.gz → 0.10.0.dev0__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 (130) hide show
  1. zkf-0.10.0.dev0/PKG-INFO +341 -0
  2. zkf-0.10.0.dev0/README.md +315 -0
  3. zkf-0.10.0.dev0/pyproject.toml +83 -0
  4. zkf-0.10.0.dev0/tests/test_absneg.py +43 -0
  5. zkf-0.10.0.dev0/tests/test_accuracy.py +393 -0
  6. zkf-0.10.0.dev0/tests/test_add.py +312 -0
  7. zkf-0.10.0.dev0/tests/test_cmp.py +130 -0
  8. zkf-0.10.0.dev0/tests/test_cordic.py +419 -0
  9. zkf-0.10.0.dev0/tests/test_divsqrt.py +346 -0
  10. zkf-0.10.0.dev0/tests/test_equivalence.py +61 -0
  11. zkf-0.10.0.dev0/tests/test_exp2.py +113 -0
  12. zkf-0.10.0.dev0/tests/test_fixed_to_float.py +190 -0
  13. zkf-0.10.0.dev0/tests/test_fma.py +290 -0
  14. zkf-0.10.0.dev0/tests/test_from_int.py +114 -0
  15. zkf-0.10.0.dev0/tests/test_hdl.py +53 -0
  16. zkf-0.10.0.dev0/tests/test_ilog2.py +57 -0
  17. zkf-0.10.0.dev0/tests/test_kernel.py +93 -0
  18. zkf-0.10.0.dev0/tests/test_log2.py +129 -0
  19. zkf-0.10.0.dev0/tests/test_models.py +355 -0
  20. zkf-0.10.0.dev0/tests/test_mul.py +263 -0
  21. zkf-0.10.0.dev0/tests/test_mul_ilog2.py +123 -0
  22. zkf-0.10.0.dev0/tests/test_pipe.py +13 -0
  23. zkf-0.10.0.dev0/tests/test_pmul.py +109 -0
  24. zkf-0.10.0.dev0/tests/test_properties.py +114 -0
  25. zkf-0.10.0.dev0/tests/test_reference.py +497 -0
  26. zkf-0.10.0.dev0/tests/test_resize.py +140 -0
  27. zkf-0.10.0.dev0/tests/test_rint.py +169 -0
  28. zkf-0.10.0.dev0/tests/test_structure.py +161 -0
  29. zkf-0.10.0.dev0/tests/test_synth.py +72 -0
  30. zkf-0.10.0.dev0/tests/test_table.py +102 -0
  31. zkf-0.10.0.dev0/zkf/__init__.py +33 -0
  32. zkf-0.10.0.dev0/zkf/__main__.py +59 -0
  33. zkf-0.10.0.dev0/zkf/_absneg.py +77 -0
  34. zkf-0.10.0.dev0/zkf/_add.py +322 -0
  35. zkf-0.10.0.dev0/zkf/_block.py +242 -0
  36. zkf-0.10.0.dev0/zkf/_cmp.py +132 -0
  37. zkf-0.10.0.dev0/zkf/_cordic.py +1864 -0
  38. zkf-0.10.0.dev0/zkf/_divsqrt.py +1012 -0
  39. zkf-0.10.0.dev0/zkf/_exp2.py +277 -0
  40. zkf-0.10.0.dev0/zkf/_finite.py +84 -0
  41. zkf-0.10.0.dev0/zkf/_fixed_to_float.py +147 -0
  42. zkf-0.10.0.dev0/zkf/_fma.py +205 -0
  43. zkf-0.10.0.dev0/zkf/_from_int.py +105 -0
  44. zkf-0.10.0.dev0/zkf/_ilog2.py +100 -0
  45. zkf-0.10.0.dev0/zkf/_log2.py +521 -0
  46. zkf-0.10.0.dev0/zkf/_mul.py +125 -0
  47. zkf-0.10.0.dev0/zkf/_mul_ilog2.py +159 -0
  48. zkf-0.10.0.dev0/zkf/_pack.py +210 -0
  49. zkf-0.10.0.dev0/zkf/_pipe.py +57 -0
  50. zkf-0.10.0.dev0/zkf/_pmul.py +246 -0
  51. zkf-0.10.0.dev0/zkf/_resize.py +95 -0
  52. zkf-0.10.0.dev0/zkf/_rint.py +228 -0
  53. zkf-0.10.0.dev0/zkf/_shift.py +232 -0
  54. zkf-0.10.0.dev0/zkf/_trans.py +706 -0
  55. zkf-0.10.0.dev0/zkf/_txn.py +71 -0
  56. zkf-0.10.0.dev0/zkf/_value.py +248 -0
  57. zkf-0.10.0.dev0/zkf.egg-info/PKG-INFO +341 -0
  58. zkf-0.10.0.dev0/zkf.egg-info/SOURCES.txt +62 -0
  59. zkf-0.10.0.dev0/zkf.egg-info/requires.txt +9 -0
  60. zkf-0.9.0/PKG-INFO +0 -349
  61. zkf-0.9.0/README.md +0 -323
  62. zkf-0.9.0/pyproject.toml +0 -67
  63. zkf-0.9.0/zkf/__init__.py +0 -35
  64. zkf-0.9.0/zkf/__main__.py +0 -41
  65. zkf-0.9.0/zkf/_format.py +0 -190
  66. zkf-0.9.0/zkf/_operators.py +0 -686
  67. zkf-0.9.0/zkf/_reference.py +0 -383
  68. zkf-0.9.0/zkf/_rtl.py +0 -43
  69. zkf-0.9.0/zkf/_tables/__init__.py +0 -1
  70. zkf-0.9.0/zkf/_tables/trans.py +0 -69
  71. zkf-0.9.0/zkf/_tables/trig.py +0 -48
  72. zkf-0.9.0/zkf/_value.py +0 -695
  73. zkf-0.9.0/zkf/oracle.py +0 -343
  74. zkf-0.9.0/zkf/rtl/_tables/_zkf_cordic_m16.v +0 -100
  75. zkf-0.9.0/zkf/rtl/_tables/_zkf_cordic_m18.v +0 -101
  76. zkf-0.9.0/zkf/rtl/_tables/_zkf_cordic_m24.v +0 -104
  77. zkf-0.9.0/zkf/rtl/_tables/_zkf_cordic_m27.v +0 -106
  78. zkf-0.9.0/zkf/rtl/_tables/_zkf_cordic_m32.v +0 -108
  79. zkf-0.9.0/zkf/rtl/_tables/_zkf_cordic_m36.v +0 -110
  80. zkf-0.9.0/zkf/rtl/_tables/_zkf_cordic_m48.v +0 -116
  81. zkf-0.9.0/zkf/rtl/_tables/_zkf_cordic_m53.v +0 -119
  82. zkf-0.9.0/zkf/rtl/_tables/_zkf_exp2_m16.v +0 -652
  83. zkf-0.9.0/zkf/rtl/_tables/_zkf_exp2_m18.v +0 -652
  84. zkf-0.9.0/zkf/rtl/_tables/_zkf_exp2_m24.v +0 -652
  85. zkf-0.9.0/zkf/rtl/_tables/_zkf_exp2_m27.v +0 -673
  86. zkf-0.9.0/zkf/rtl/_tables/_zkf_exp2_m32.v +0 -673
  87. zkf-0.9.0/zkf/rtl/_tables/_zkf_exp2_m36.v +0 -673
  88. zkf-0.9.0/zkf/rtl/_tables/_zkf_exp2_m48.v +0 -695
  89. zkf-0.9.0/zkf/rtl/_tables/_zkf_exp2_m53.v +0 -694
  90. zkf-0.9.0/zkf/rtl/_tables/_zkf_log2_m16.v +0 -639
  91. zkf-0.9.0/zkf/rtl/_tables/_zkf_log2_m18.v +0 -639
  92. zkf-0.9.0/zkf/rtl/_tables/_zkf_log2_m24.v +0 -639
  93. zkf-0.9.0/zkf/rtl/_tables/_zkf_log2_m27.v +0 -658
  94. zkf-0.9.0/zkf/rtl/_tables/_zkf_log2_m32.v +0 -677
  95. zkf-0.9.0/zkf/rtl/_tables/_zkf_log2_m36.v +0 -677
  96. zkf-0.9.0/zkf/rtl/_tables/_zkf_log2_m48.v +0 -698
  97. zkf-0.9.0/zkf/rtl/_tables/_zkf_log2_m53.v +0 -698
  98. zkf-0.9.0/zkf/rtl/_zkf_add_core.v +0 -157
  99. zkf-0.9.0/zkf/rtl/_zkf_cordic_core.v +0 -296
  100. zkf-0.9.0/zkf/rtl/_zkf_divsqrt_step.v +0 -107
  101. zkf-0.9.0/zkf/rtl/_zkf_fixed_to_float.v +0 -151
  102. zkf-0.9.0/zkf/rtl/_zkf_normshift.v +0 -211
  103. zkf-0.9.0/zkf/rtl/_zkf_pack.v +0 -252
  104. zkf-0.9.0/zkf/rtl/_zkf_pmul.v +0 -337
  105. zkf-0.9.0/zkf/rtl/_zkf_rshift_sticky.v +0 -196
  106. zkf-0.9.0/zkf/rtl/_zkf_txn.v +0 -60
  107. zkf-0.9.0/zkf/rtl/zkf_absneg.v +0 -49
  108. zkf-0.9.0/zkf/rtl/zkf_add.v +0 -111
  109. zkf-0.9.0/zkf/rtl/zkf_cmp.v +0 -80
  110. zkf-0.9.0/zkf/rtl/zkf_cordic.v +0 -876
  111. zkf-0.9.0/zkf/rtl/zkf_divsqrt.v +0 -514
  112. zkf-0.9.0/zkf/rtl/zkf_exp2.v +0 -322
  113. zkf-0.9.0/zkf/rtl/zkf_finite.v +0 -56
  114. zkf-0.9.0/zkf/rtl/zkf_fma.v +0 -151
  115. zkf-0.9.0/zkf/rtl/zkf_from_int.v +0 -120
  116. zkf-0.9.0/zkf/rtl/zkf_ilog2.v +0 -67
  117. zkf-0.9.0/zkf/rtl/zkf_log2.v +0 -459
  118. zkf-0.9.0/zkf/rtl/zkf_mul.v +0 -157
  119. zkf-0.9.0/zkf/rtl/zkf_mul_ilog2.v +0 -142
  120. zkf-0.9.0/zkf/rtl/zkf_pipe.v +0 -57
  121. zkf-0.9.0/zkf/rtl/zkf_resize.v +0 -191
  122. zkf-0.9.0/zkf/rtl/zkf_rint.v +0 -213
  123. zkf-0.9.0/zkf.egg-info/PKG-INFO +0 -349
  124. zkf-0.9.0/zkf.egg-info/SOURCES.txt +0 -69
  125. zkf-0.9.0/zkf.egg-info/requires.txt +0 -10
  126. {zkf-0.9.0 → zkf-0.10.0.dev0}/LICENSE +0 -0
  127. {zkf-0.9.0 → zkf-0.10.0.dev0}/setup.cfg +0 -0
  128. {zkf-0.9.0 → zkf-0.10.0.dev0}/zkf/py.typed +0 -0
  129. {zkf-0.9.0 → zkf-0.10.0.dev0}/zkf.egg-info/dependency_links.txt +0 -0
  130. {zkf-0.9.0 → zkf-0.10.0.dev0}/zkf.egg-info/top_level.txt +0 -0
@@ -0,0 +1,341 @@
1
+ Metadata-Version: 2.4
2
+ Name: zkf
3
+ Version: 0.10.0.dev0
4
+ Summary: Efficient floating-point engine RTL for controls & embedded following IEEE 754 sans NaN and subnormals
5
+ Author-email: Zubax Robotics <pavel.kirienko@zubax.com>
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Repository, https://github.com/Zubax/zkf
8
+ Keywords: fpga,hdl,verilog,floating point,rtl,dsp,hardware design
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
13
+ Classifier: Typing :: Typed
14
+ Requires-Python: >=3.14
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: amaranth[builtin-yosys]~=0.5
18
+ Requires-Dist: mpmath~=1.4
19
+ Provides-Extra: test
20
+ Requires-Dist: numpy~=2.4; extra == "test"
21
+ Requires-Dist: pytest~=9.0; extra == "test"
22
+ Requires-Dist: pytest-xdist~=3.2; extra == "test"
23
+ Requires-Dist: pytest-cov~=7.0; extra == "test"
24
+ Requires-Dist: mypy~=2.4; extra == "test"
25
+ Dynamic: license-file
26
+
27
+ # Zubax Kulibin floating point
28
+
29
+ [![PyPI](https://img.shields.io/pypi/v/zkf?logo=pypi&color=ffff00)](https://pypi.org/project/zkf/)
30
+ [![Forum](https://img.shields.io/discourse/https/forum.zubax.com/users.svg?logo=discourse&color=ff0000)](https://forum.zubax.com)
31
+
32
+ A small and FPGA-friendly floating point format that is similar to IEEE 754 but intentionally omits support for NaN,
33
+ subnormals, exceptions, and rounding modes other than round-to-nearest, ties-to-even (RNTE).
34
+ Only one canonical positive zero representation exists.
35
+
36
+ The bit layout is identical to IEEE 754: sign, exponent, and the significand with the MSb omitted.
37
+
38
+ See how ZKF beats other floating-point libraries in <https://zubax.github.io/fpga-floating-point-eval>.
39
+
40
+ ## Usage
41
+
42
+ Install: `pip install zkf`.
43
+ ZKF is written in Amaranth and can be integrated into Amaranth designs as well as emit ordinary portable Verilog.
44
+
45
+ ```python
46
+ import zkf
47
+
48
+ mul = zkf.Mul(zkf.ZkfFormat(8, 24), wmultiplier=18, stage_core_mul=2) # 8b exponent, 24b mantissa, 18b multipliers
49
+ mul.timing.latency # cycles from in_valid to out_valid
50
+ verilog = mul.compile() # generate Verilog source
51
+ component = mul.component() # or the Amaranth component, for an Amaranth design or its simulator
52
+ a, b = mul.fmt.encode(1.5), mul.fmt.encode(-2)
53
+ mul.evaluate(a, b) # what the hardware gives for these operands exactly
54
+ ```
55
+
56
+ Most operators are zero-bubble throughput-1 pipelines with the conventional `in_valid`/`out_valid` interface;
57
+ `zkf.Cordic` is FSM-based and adds the `in_ready`/`out_ready` handshake.
58
+ Every operator has a fixed data-independent latency, known from its configuration for each mode (see `.timing`).
59
+
60
+ The two main parameters are wexp and wman setting the bit width of the biased exponent and the significand;
61
+ the most significant bit of the significand is not stored, but there is a sign bit,
62
+ so the total bit width is simply `wfull=wexp+wman`.
63
+
64
+ ### Caveats
65
+
66
+ Some of the simple combinational operators may produce non-canonical outputs (namely, a negative zero);
67
+ this however does not affect compatibility with other operators since they always canonicalize inputs.
68
+
69
+ A Yosys script that runs `opt` after `proc` with no `opt_clean` between them stops at "Conflicting init values" on
70
+ some configurations; `attrmap -remove init` before `proc` avoids it.
71
+ This is mostly a Yosys quirk rather than a library issue.
72
+
73
+ Read as SystemVerilog (Icarus `-g2012`, which cocotb uses), the printed text needs a reset edge after time zero, or
74
+ its valid flags stay unknown; even then the angle of `zkf.Cordic`'s first vectoring is unknown. Read as Verilog-2005,
75
+ it shows neither.
76
+
77
+ ### Tuning knobs
78
+
79
+ Operators can be tuned for the target chip with register-stage knobs, all off by default:
80
+
81
+ - `stage_input` and `stage_output` -- input and output register stages shielding the operator's internal combinational
82
+ paths from external circuits.
83
+ When zero, internal combinational paths are exposed directly;
84
+ when greater than one, dummy stages are added which helps with retiming or when routing delays dominate.
85
+
86
+ - `stage_core` -- a set of the operator's own registers, e.g. `zkf.Add.CoreStages.SUM | zkf.Add.CoreStages.PACK`;
87
+ operators made of parts take one knob per part, such as the product's `stage_core_mul`.
88
+ The docstrings describe the knobs of each operator.
89
+
90
+ The `timing` property gives the latency and the initiation interval (II) of the chosen staging configuration.
91
+
92
+ Operators that multiply take `wmultiplier`, the operand width of the target's multipliers (16, 18 and 24 bits are
93
+ common in modern FPGAs; in the absence of hard DSP blocks any value will work).
94
+
95
+ `rom_attrs` and `mul_attrs` pass synthesis attributes to the lookup tables and to the products' operand registers,
96
+ e.g. `rom_attrs={"rom_style": "block"}`.
97
+
98
+ Use `zkf.Pipe` to delay your own control or sideband signals by an operator's latency so they land with its output.
99
+
100
+ ### Catalogue
101
+
102
+ II - initiation interval (cycles between accepting new inputs; 1 for zero-bubble pipelines).
103
+
104
+ | Class | II | Function | Remarks |
105
+ |-----------------|---------|-----------------------------------------------------------------------------------------------|-----------------------------|
106
+ | `zkf.AbsNeg` | 1 | Absolute value and negation. | Does not canonicalize |
107
+ | `zkf.Finite` | 1 | Finiteness flag, and ±∞ replaced by the nearest finite value. | Does not canonicalize |
108
+ | `zkf.Cmp` | 1 | Compare two values; also outputs their min and max. | Does not canonicalize |
109
+ | `zkf.Add` | 1 | `a + b`, also `a - b` when the sign bit of `b` is flipped. | |
110
+ | `zkf.Mul` | 1 | `a⋅b`. | |
111
+ | `zkf.MulIlog2` | 1 | `a⋅2^k` for signed integer k (ldexp/scalbn). | |
112
+ | `zkf.Ilog2` | 1 | Raw exponent minus bias; sign-invariant signed integer. | Flags zero, infinity, negative |
113
+ | `zkf.Fma` | 1 | `(a⋅b) + c` fused multiply-add, high precision, rounded once. | Larger than separate mul->add; non-finite handling follows mul->add.|
114
+ | `zkf.FromInt` | 1 | Cast signed two's-complement integer to float. | |
115
+ | `zkf.Resize` | 1 | Cast between different float formats. | |
116
+ | `zkf.Rint` | 1 | Round to integer, outputs both a float and a saturated integer. | RNTE/floor/ceil/trunc |
117
+ | `zkf.Divsqrt` | 1 | `a ÷ b` or `√a`; `error` iff /0 or domain error. | Correct rounding, 0.5 ULP |
118
+ | `zkf.Exp2` | 1 | `2^x` | Faithful rounding, see below|
119
+ | `zkf.Log2` | 1 | `log2(x)`; `domain_error` if `x<0`, `pole` if `x=0`. | Faithful rounding, see below|
120
+ | `zkf.Cordic` | latency | `sin(2π⋅x)`, `cos(2π⋅x)`, `quadrant`; or `atan2(y,x)` in turns ∈ (-0.5,0.5], `hypot(y,x)`. | Faithful rounding, see below|
121
+ | `zkf.Pipe` | 1 | Delay line of N register stages, W bits each. | No-op |
122
+
123
+ ### Derived functions
124
+
125
+ The basic modules available enable efficient computation of a large set of derived functions; examples follow.
126
+ Bare angle functions follow the usual radian convention; helpers suffixed `_turns` expose ZKF's native turn
127
+ representation.
128
+
129
+ sin_turns(x), cos_turns(x) = zkf.Cordic(x) ; rotation; x in turns
130
+ atan2_turns(y,x) = zkf.Cordic(y, x) ; vectoring; angle in turns ∈ (-0.5,0.5]
131
+ atan_turns(x) = atan2_turns(x, 1)
132
+
133
+ normalize_angle(x) = x - 2π⋅floor((x + π) / (2π)) ; [-π,+π)
134
+ normalize_angle_turns(t) = t - floor(t + 0.5) ; [-0.5,+0.5)
135
+
136
+ INV_TAU = 1 / (2π)
137
+ radians_to_turns(x) = x⋅INV_TAU
138
+
139
+ sin(x), cos(x) = sin_turns(radians_to_turns(x)), cos_turns(radians_to_turns(x))
140
+ atan2(y,x) = 2π⋅atan2_turns(y, x)
141
+
142
+ sqrt(x) = zkf.Divsqrt(x) ; correctly rounded 0.5 ULP
143
+ exp(x) = exp2(x⋅log2(e))
144
+ ln(x) = log2(x) / log2(e)
145
+ log10(x) = log2(x) / log2(10)
146
+ log_b(x) = log2(x) / log2(b) ; x>0, b>0, b≠1
147
+ pow(a,b) = exp2(b⋅log2(a)) ; real-valued identity for a>0
148
+ recip(x) = 1 / x
149
+ rsqrt(x) = exp2(log2(x)⋅-2^-1) ; x>0; avoids division
150
+ rsqrt(x) = sqrt(1 / x) ; x>0, 1/x normal; faithful, 0.85 ULP max at wman=18
151
+ cbrt(x) = sign(x)⋅exp2(log2(abs(x)) / 3)
152
+
153
+ tan(x) = sin(x) / cos(x)
154
+ atan(x) = atan2(x, 1)
155
+ asin(x) = atan2(x, sqrt(1 - x⋅x)) ; x ∈ [-1,+1]
156
+ acos(x) = atan2(sqrt(1 - x⋅x), x) ; x ∈ [-1,+1]
157
+ h = max(abs(x), abs(y))
158
+ hypot(x,y) = h⋅sqrt((x/h)⋅(x/h) + (y/h)⋅(y/h)) ; x, y finite; also see zkf.Cordic
159
+
160
+ min(a,b), max(a,b) = zkf.Cmp(a,b)
161
+ clamp(x, lo, hi) = min(max(x, lo), hi)
162
+ lerp(a,b,t) = fma(t, b - a, a)
163
+ deadzone(x,d) = sign(x)⋅max(abs(x) - d, 0)
164
+ smoothstep(t) = t⋅t⋅(3 - 2⋅t); where t is clamped to [0,1]
165
+
166
+ dot(a,b) = sum_i a[i]⋅b[i] ; use zkf.Fma chains
167
+ norm2(x) = dot(x, x)
168
+ norm(x) = sqrt(norm2(x))
169
+ normalize(x) = x⋅rsqrt(norm2(x) + ε)
170
+ distance(a,b) = norm(a - b)
171
+ distance_2d(a,b) = hypot(a.x - b.x, a.y - b.y)
172
+
173
+ db_power(x) = 10⋅log10(x) ; x>0
174
+ db_amplitude(x) = 20⋅log10(abs(x)) ; x≠0
175
+ power_from_db(x) = exp2(x⋅log2(10) / 10)
176
+ amp_from_db(x) = exp2(x⋅log2(10) / 20)
177
+
178
+ sinc(x) = sin(π⋅x) / (π⋅x) ; normalized, sinc(0)=1
179
+ rms(x) = sqrt(mean(x⋅x))
180
+ ema(y,x,a) = fma(a, x - y, y)
181
+
182
+ complex_abs(re,im) = hypot(re, im)
183
+ arg(re,im) = atan2(im, re)
184
+ arg_turns(re,im) = atan2_turns(im, re)
185
+ unit_complex(t) = (cos(t), sin(t)) ; principal counterpart of arg()
186
+ polar(r,t) = (r⋅cos(t), r⋅sin(t)) ; r≥0
187
+ complex_mul((ar,ai),(br,bi)) = (ar⋅br - ai⋅bi, ar⋅bi + ai⋅br)
188
+ rotate2(x,y,t) = (x⋅cos(t) - y⋅sin(t), x⋅sin(t) + y⋅cos(t))
189
+
190
+ relu(x) = max(x, 0)
191
+ leaky_relu(x) = x ≥ 0 ? x : α⋅x
192
+ hard_sigmoid(x) = clamp(α⋅x + β, 0, 1)
193
+ hard_swish(x) = x⋅hard_sigmoid(x)
194
+
195
+ sigmoid(x) = 1 / (1 + exp2(-x⋅log2(e)))
196
+ tanh(x) = 2⋅sigmoid(2⋅x) - 1
197
+ softplus(x) = max(x, 0) + log2(1 + exp2(-abs(x)⋅log2(e))) / log2(e)
198
+ silu(x) = x⋅sigmoid(x)
199
+
200
+ m = max_i x[i]
201
+ logsumexp(x[]) = m + log2(sum_i exp2((x[i] - m)⋅log2(e))) / log2(e)
202
+ softmax_i(x[]) = exp2((x[i] - m)⋅log2(e)) / sum_j exp2((x[j] - m)⋅log2(e))
203
+ layer_norm(x) = (x - mean(x))⋅rsqrt(var(x) + ε)
204
+
205
+ And so on.
206
+
207
+ Generic floating-point remainder/modulo computation is not included because the general solution requires iterative
208
+ range reduction which maps poorly onto fixed-latency FPGA cores; instead, one can build the iterative solver using
209
+ the existing basic operators: zkf.Fma, zkf.Divsqrt, etc.
210
+
211
+ ## Semantics
212
+
213
+ Differences from IEEE 754: no NaN, no subnormals (exponent 0 always encodes +0; finite magnitudes in `(0, min_normal/2)`
214
+ round to +0; magnitudes in `[min_normal/2, min_normal)` round to signed min_normal), no -0, no exceptions,
215
+ overflow produces ±∞.
216
+
217
+ Infinity cases that would be NaN in IEEE 754:
218
+
219
+ | Expression | Result |
220
+ |---------------------|--------------------------------|
221
+ | +∞ + -∞ | +0 |
222
+ | 0⋅±∞ | +0 |
223
+ | 0 ÷ 0 | +0 |
224
+ | ±∞ ÷ ±∞ | +0 |
225
+ | √x; x<0 | -inf |
226
+
227
+ Non-NaN infinity cases (same intent as IEEE 754):
228
+
229
+ | Expression | Result |
230
+ |---------------------|--------------------------------|
231
+ | finite≠0 ÷ 0 | ±∞ (sign = sign of dividend) |
232
+ | ±∞ ÷ 0 | ±∞ (sign = sign of dividend) |
233
+ | finite ÷ ±∞ | +0 |
234
+ | ±∞⋅±∞ | ±∞ (sign = signs XOR) |
235
+ | finite≠0⋅±∞ | ±∞ (sign = signs XOR) |
236
+
237
+ The subnormal round-to-nearest behavior is illustrated below, compared against the basic flush to zero for any value
238
+ below the min normal. The timing/area cost of both approaches is approximately equivalent while the rounding method
239
+ halves the worst-case error.
240
+
241
+ ZKF only has a single canonical zero representation -- the positive zero. However, it is not an error to pass a
242
+ negative zero as an operand; the sign bit of a zero operand is simply ignored. This relaxation enables simplification
243
+ of certain basic operators.
244
+
245
+ <img src="docs/zkf_underflow_rounding.svg">
246
+
247
+ ### Accuracy of the transcendental functions
248
+
249
+ The exp2 and log2 transcendentals deliver faithful rounding: every finite result is one of the two representable
250
+ values bracketing the exact result.
251
+
252
+ A result differs from round-to-nearest only near a midpoint between adjacent representable values.
253
+ `zkf.Cordic` carries the same faithful-rounding contract.
254
+
255
+ <img src="docs/zkf_transcendental_accuracy.svg">
256
+
257
+ **ATTENTION:** the lookup tables of `zkf.Exp2` and `zkf.Log2` must be mapped to ROM; if fabric usage or timing looks
258
+ unreasonable, check the synthesis settings first, and if necessary give `rom_attrs`.
259
+
260
+ ## Sizing the exponent and the significand (wexp/wman)
261
+
262
+ The library is mostly focused on formats with wman≥7 (that is, at least 7 significand bits including the hidden one),
263
+ which covers all commonly encountered standard float formats.
264
+ Narrower wman is supported where logic generalizes to narrower widths without special-casing (e.g., in simple algebra).
265
+ Certain complex operators may require a larger minimal width where special efforts are required to support narrow
266
+ formats (e.g., CORDIC).
267
+ To support narrow formats, the optimal solution could be to introduce alternative operator implementations
268
+ instead of extending the existing ones; the reason is that narrow formats could be more efficiently implemented via
269
+ precomputed lookup tables rather than deriving the answer through live computation.
270
+
271
+ wexp can be chosen freely within an operator's limits, while wman is sensitive to the chip's DSP capabilities and thus
272
+ requires careful selection to achieve best resource utilization.
273
+
274
+ |wman |≈ε (interval)| Description |
275
+ |-----|-------------|---------------------------------------------------------------------------------------------|
276
+ | 16 | 3.052e-05 | DSP tiles in Lattice iCE40 and similar |
277
+ | 18 | 7.629e-06 | Classic FPGA DSP width, very common: ECP5, PolarFire, Trion, many Intel modes, etc. |
278
+ | 24 | 1.192e-07 | IEEE 754 binary32; also fits Versal DSP58's 27x24 asymmetric multiplier side |
279
+ | 27 | 1.490e-08 | Intel/Altera variable-precision DSPs |
280
+ | 32 | 4.657e-10 | 2x16 |
281
+ | 36 | 2.910e-11 | 2x18 (very common) or native Intel/Altera 36x36-style variable-precision mode |
282
+ | 48 | 7.105e-15 | 2x24 or 3x16; with an 8-bit exponent amounts to 7 bytes exactly |
283
+ | 53 | 2.220e-16 | IEEE 754 binary64 |
284
+
285
+ Narrower wman is rarely practical for computation due to low precision and fast error accumulation,
286
+ although they can still be useful for storage/exchange. One notable exception is neural networks though.
287
+
288
+ ### wman=18
289
+
290
+ An FPGA-friendly format because modern DSP-enabled FPGAs often implement 18x18 bit multipliers, which means that a
291
+ narrower mantissa is unlikely to save much resources or nontrivially improve timings as long as hardware multipliers
292
+ are used.
293
+
294
+ One can stay within 24 bits total by choosing wexp=6:
295
+
296
+ wexp=6 wman=18 wfrac=17 wfull=24 bias=31
297
+ lowest = 1/1073741824 ≈ 9.313e-10
298
+ max = 0xFFFF_C000 ≈ 4.295e+09
299
+ ε = 1/131072 ≈ 7.629e-06
300
+
301
+ ### wman=36
302
+
303
+ Similar to the above, wman=36 is efficient on common FPGAs because it maps multiplication to four 18x18 DSP slices.
304
+ This is often a better fit for intermediate result representation to avoid error accumulation --
305
+ the precision lands halfway between IEEE 754 binary64 and binary32.
306
+
307
+ Usually, on an 18x18 DSP chip, going even a single bit higher causes f_max to tank dramatically while area explodes.
308
+ Thus this is likely to be the optimal choice for a large number of applications.
309
+
310
+ Using binary32-compatible exponent wexp=8, 44 bits total (5.5 bytes):
311
+
312
+ wexp=8 wman=36 wfrac=35 wfull=44 bias=127
313
+ lowest = 1/85070591730234615865843651857942052864 ≈ 1.175e-38
314
+ max = 0xFFFFFFFF_F0000000_00000000_00000000 ≈ 3.403e+38
315
+ ε = 1/34359738368 ≈ 2.910e-11
316
+
317
+ ### IEEE 754-like and other standard float formats
318
+
319
+ ZKF offers limited compatibility with IEEE 754 so while it can match the bit layout,
320
+ not all states are mappable between the formats.
321
+
322
+ - wexp=5 wman=11: IEEE 754 binary16-like
323
+ - wexp=8 wman=24: IEEE 754 binary32-like
324
+ - wexp=11 wman=53: IEEE 754 binary64-like
325
+
326
+ Common non-IEEE formats:
327
+
328
+ - wexp=7 wman=17: AMD/ATI fp24-like
329
+ - wexp=8 wman=8: bfloat16-like
330
+ - wexp=8 wman=11: NVIDIA TF32-like (19 bits)
331
+
332
+ ## TODO
333
+
334
+ Roughly ordered by severity.
335
+
336
+ - Pre-tuned stage sets per operator and format, measured per flow and chip and ordered by latency, so that a user takes
337
+ the first that closes; or an API that takes the clock and the speed grade and picks one (preferred).
338
+ Each set is judged by its worst placement; a timing model would not do, as the binding paths are often mostly routing.
339
+
340
+ - `wmultiplier` is one number, the narrower side of a rectangular multiplier: two of its slices can be one tile on the
341
+ chip (25x18, 27x18), so a grid register may cut nothing there.
@@ -0,0 +1,315 @@
1
+ # Zubax Kulibin floating point
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/zkf?logo=pypi&color=ffff00)](https://pypi.org/project/zkf/)
4
+ [![Forum](https://img.shields.io/discourse/https/forum.zubax.com/users.svg?logo=discourse&color=ff0000)](https://forum.zubax.com)
5
+
6
+ A small and FPGA-friendly floating point format that is similar to IEEE 754 but intentionally omits support for NaN,
7
+ subnormals, exceptions, and rounding modes other than round-to-nearest, ties-to-even (RNTE).
8
+ Only one canonical positive zero representation exists.
9
+
10
+ The bit layout is identical to IEEE 754: sign, exponent, and the significand with the MSb omitted.
11
+
12
+ See how ZKF beats other floating-point libraries in <https://zubax.github.io/fpga-floating-point-eval>.
13
+
14
+ ## Usage
15
+
16
+ Install: `pip install zkf`.
17
+ ZKF is written in Amaranth and can be integrated into Amaranth designs as well as emit ordinary portable Verilog.
18
+
19
+ ```python
20
+ import zkf
21
+
22
+ mul = zkf.Mul(zkf.ZkfFormat(8, 24), wmultiplier=18, stage_core_mul=2) # 8b exponent, 24b mantissa, 18b multipliers
23
+ mul.timing.latency # cycles from in_valid to out_valid
24
+ verilog = mul.compile() # generate Verilog source
25
+ component = mul.component() # or the Amaranth component, for an Amaranth design or its simulator
26
+ a, b = mul.fmt.encode(1.5), mul.fmt.encode(-2)
27
+ mul.evaluate(a, b) # what the hardware gives for these operands exactly
28
+ ```
29
+
30
+ Most operators are zero-bubble throughput-1 pipelines with the conventional `in_valid`/`out_valid` interface;
31
+ `zkf.Cordic` is FSM-based and adds the `in_ready`/`out_ready` handshake.
32
+ Every operator has a fixed data-independent latency, known from its configuration for each mode (see `.timing`).
33
+
34
+ The two main parameters are wexp and wman setting the bit width of the biased exponent and the significand;
35
+ the most significant bit of the significand is not stored, but there is a sign bit,
36
+ so the total bit width is simply `wfull=wexp+wman`.
37
+
38
+ ### Caveats
39
+
40
+ Some of the simple combinational operators may produce non-canonical outputs (namely, a negative zero);
41
+ this however does not affect compatibility with other operators since they always canonicalize inputs.
42
+
43
+ A Yosys script that runs `opt` after `proc` with no `opt_clean` between them stops at "Conflicting init values" on
44
+ some configurations; `attrmap -remove init` before `proc` avoids it.
45
+ This is mostly a Yosys quirk rather than a library issue.
46
+
47
+ Read as SystemVerilog (Icarus `-g2012`, which cocotb uses), the printed text needs a reset edge after time zero, or
48
+ its valid flags stay unknown; even then the angle of `zkf.Cordic`'s first vectoring is unknown. Read as Verilog-2005,
49
+ it shows neither.
50
+
51
+ ### Tuning knobs
52
+
53
+ Operators can be tuned for the target chip with register-stage knobs, all off by default:
54
+
55
+ - `stage_input` and `stage_output` -- input and output register stages shielding the operator's internal combinational
56
+ paths from external circuits.
57
+ When zero, internal combinational paths are exposed directly;
58
+ when greater than one, dummy stages are added which helps with retiming or when routing delays dominate.
59
+
60
+ - `stage_core` -- a set of the operator's own registers, e.g. `zkf.Add.CoreStages.SUM | zkf.Add.CoreStages.PACK`;
61
+ operators made of parts take one knob per part, such as the product's `stage_core_mul`.
62
+ The docstrings describe the knobs of each operator.
63
+
64
+ The `timing` property gives the latency and the initiation interval (II) of the chosen staging configuration.
65
+
66
+ Operators that multiply take `wmultiplier`, the operand width of the target's multipliers (16, 18 and 24 bits are
67
+ common in modern FPGAs; in the absence of hard DSP blocks any value will work).
68
+
69
+ `rom_attrs` and `mul_attrs` pass synthesis attributes to the lookup tables and to the products' operand registers,
70
+ e.g. `rom_attrs={"rom_style": "block"}`.
71
+
72
+ Use `zkf.Pipe` to delay your own control or sideband signals by an operator's latency so they land with its output.
73
+
74
+ ### Catalogue
75
+
76
+ II - initiation interval (cycles between accepting new inputs; 1 for zero-bubble pipelines).
77
+
78
+ | Class | II | Function | Remarks |
79
+ |-----------------|---------|-----------------------------------------------------------------------------------------------|-----------------------------|
80
+ | `zkf.AbsNeg` | 1 | Absolute value and negation. | Does not canonicalize |
81
+ | `zkf.Finite` | 1 | Finiteness flag, and ±∞ replaced by the nearest finite value. | Does not canonicalize |
82
+ | `zkf.Cmp` | 1 | Compare two values; also outputs their min and max. | Does not canonicalize |
83
+ | `zkf.Add` | 1 | `a + b`, also `a - b` when the sign bit of `b` is flipped. | |
84
+ | `zkf.Mul` | 1 | `a⋅b`. | |
85
+ | `zkf.MulIlog2` | 1 | `a⋅2^k` for signed integer k (ldexp/scalbn). | |
86
+ | `zkf.Ilog2` | 1 | Raw exponent minus bias; sign-invariant signed integer. | Flags zero, infinity, negative |
87
+ | `zkf.Fma` | 1 | `(a⋅b) + c` fused multiply-add, high precision, rounded once. | Larger than separate mul->add; non-finite handling follows mul->add.|
88
+ | `zkf.FromInt` | 1 | Cast signed two's-complement integer to float. | |
89
+ | `zkf.Resize` | 1 | Cast between different float formats. | |
90
+ | `zkf.Rint` | 1 | Round to integer, outputs both a float and a saturated integer. | RNTE/floor/ceil/trunc |
91
+ | `zkf.Divsqrt` | 1 | `a ÷ b` or `√a`; `error` iff /0 or domain error. | Correct rounding, 0.5 ULP |
92
+ | `zkf.Exp2` | 1 | `2^x` | Faithful rounding, see below|
93
+ | `zkf.Log2` | 1 | `log2(x)`; `domain_error` if `x<0`, `pole` if `x=0`. | Faithful rounding, see below|
94
+ | `zkf.Cordic` | latency | `sin(2π⋅x)`, `cos(2π⋅x)`, `quadrant`; or `atan2(y,x)` in turns ∈ (-0.5,0.5], `hypot(y,x)`. | Faithful rounding, see below|
95
+ | `zkf.Pipe` | 1 | Delay line of N register stages, W bits each. | No-op |
96
+
97
+ ### Derived functions
98
+
99
+ The basic modules available enable efficient computation of a large set of derived functions; examples follow.
100
+ Bare angle functions follow the usual radian convention; helpers suffixed `_turns` expose ZKF's native turn
101
+ representation.
102
+
103
+ sin_turns(x), cos_turns(x) = zkf.Cordic(x) ; rotation; x in turns
104
+ atan2_turns(y,x) = zkf.Cordic(y, x) ; vectoring; angle in turns ∈ (-0.5,0.5]
105
+ atan_turns(x) = atan2_turns(x, 1)
106
+
107
+ normalize_angle(x) = x - 2π⋅floor((x + π) / (2π)) ; [-π,+π)
108
+ normalize_angle_turns(t) = t - floor(t + 0.5) ; [-0.5,+0.5)
109
+
110
+ INV_TAU = 1 / (2π)
111
+ radians_to_turns(x) = x⋅INV_TAU
112
+
113
+ sin(x), cos(x) = sin_turns(radians_to_turns(x)), cos_turns(radians_to_turns(x))
114
+ atan2(y,x) = 2π⋅atan2_turns(y, x)
115
+
116
+ sqrt(x) = zkf.Divsqrt(x) ; correctly rounded 0.5 ULP
117
+ exp(x) = exp2(x⋅log2(e))
118
+ ln(x) = log2(x) / log2(e)
119
+ log10(x) = log2(x) / log2(10)
120
+ log_b(x) = log2(x) / log2(b) ; x>0, b>0, b≠1
121
+ pow(a,b) = exp2(b⋅log2(a)) ; real-valued identity for a>0
122
+ recip(x) = 1 / x
123
+ rsqrt(x) = exp2(log2(x)⋅-2^-1) ; x>0; avoids division
124
+ rsqrt(x) = sqrt(1 / x) ; x>0, 1/x normal; faithful, 0.85 ULP max at wman=18
125
+ cbrt(x) = sign(x)⋅exp2(log2(abs(x)) / 3)
126
+
127
+ tan(x) = sin(x) / cos(x)
128
+ atan(x) = atan2(x, 1)
129
+ asin(x) = atan2(x, sqrt(1 - x⋅x)) ; x ∈ [-1,+1]
130
+ acos(x) = atan2(sqrt(1 - x⋅x), x) ; x ∈ [-1,+1]
131
+ h = max(abs(x), abs(y))
132
+ hypot(x,y) = h⋅sqrt((x/h)⋅(x/h) + (y/h)⋅(y/h)) ; x, y finite; also see zkf.Cordic
133
+
134
+ min(a,b), max(a,b) = zkf.Cmp(a,b)
135
+ clamp(x, lo, hi) = min(max(x, lo), hi)
136
+ lerp(a,b,t) = fma(t, b - a, a)
137
+ deadzone(x,d) = sign(x)⋅max(abs(x) - d, 0)
138
+ smoothstep(t) = t⋅t⋅(3 - 2⋅t); where t is clamped to [0,1]
139
+
140
+ dot(a,b) = sum_i a[i]⋅b[i] ; use zkf.Fma chains
141
+ norm2(x) = dot(x, x)
142
+ norm(x) = sqrt(norm2(x))
143
+ normalize(x) = x⋅rsqrt(norm2(x) + ε)
144
+ distance(a,b) = norm(a - b)
145
+ distance_2d(a,b) = hypot(a.x - b.x, a.y - b.y)
146
+
147
+ db_power(x) = 10⋅log10(x) ; x>0
148
+ db_amplitude(x) = 20⋅log10(abs(x)) ; x≠0
149
+ power_from_db(x) = exp2(x⋅log2(10) / 10)
150
+ amp_from_db(x) = exp2(x⋅log2(10) / 20)
151
+
152
+ sinc(x) = sin(π⋅x) / (π⋅x) ; normalized, sinc(0)=1
153
+ rms(x) = sqrt(mean(x⋅x))
154
+ ema(y,x,a) = fma(a, x - y, y)
155
+
156
+ complex_abs(re,im) = hypot(re, im)
157
+ arg(re,im) = atan2(im, re)
158
+ arg_turns(re,im) = atan2_turns(im, re)
159
+ unit_complex(t) = (cos(t), sin(t)) ; principal counterpart of arg()
160
+ polar(r,t) = (r⋅cos(t), r⋅sin(t)) ; r≥0
161
+ complex_mul((ar,ai),(br,bi)) = (ar⋅br - ai⋅bi, ar⋅bi + ai⋅br)
162
+ rotate2(x,y,t) = (x⋅cos(t) - y⋅sin(t), x⋅sin(t) + y⋅cos(t))
163
+
164
+ relu(x) = max(x, 0)
165
+ leaky_relu(x) = x ≥ 0 ? x : α⋅x
166
+ hard_sigmoid(x) = clamp(α⋅x + β, 0, 1)
167
+ hard_swish(x) = x⋅hard_sigmoid(x)
168
+
169
+ sigmoid(x) = 1 / (1 + exp2(-x⋅log2(e)))
170
+ tanh(x) = 2⋅sigmoid(2⋅x) - 1
171
+ softplus(x) = max(x, 0) + log2(1 + exp2(-abs(x)⋅log2(e))) / log2(e)
172
+ silu(x) = x⋅sigmoid(x)
173
+
174
+ m = max_i x[i]
175
+ logsumexp(x[]) = m + log2(sum_i exp2((x[i] - m)⋅log2(e))) / log2(e)
176
+ softmax_i(x[]) = exp2((x[i] - m)⋅log2(e)) / sum_j exp2((x[j] - m)⋅log2(e))
177
+ layer_norm(x) = (x - mean(x))⋅rsqrt(var(x) + ε)
178
+
179
+ And so on.
180
+
181
+ Generic floating-point remainder/modulo computation is not included because the general solution requires iterative
182
+ range reduction which maps poorly onto fixed-latency FPGA cores; instead, one can build the iterative solver using
183
+ the existing basic operators: zkf.Fma, zkf.Divsqrt, etc.
184
+
185
+ ## Semantics
186
+
187
+ Differences from IEEE 754: no NaN, no subnormals (exponent 0 always encodes +0; finite magnitudes in `(0, min_normal/2)`
188
+ round to +0; magnitudes in `[min_normal/2, min_normal)` round to signed min_normal), no -0, no exceptions,
189
+ overflow produces ±∞.
190
+
191
+ Infinity cases that would be NaN in IEEE 754:
192
+
193
+ | Expression | Result |
194
+ |---------------------|--------------------------------|
195
+ | +∞ + -∞ | +0 |
196
+ | 0⋅±∞ | +0 |
197
+ | 0 ÷ 0 | +0 |
198
+ | ±∞ ÷ ±∞ | +0 |
199
+ | √x; x<0 | -inf |
200
+
201
+ Non-NaN infinity cases (same intent as IEEE 754):
202
+
203
+ | Expression | Result |
204
+ |---------------------|--------------------------------|
205
+ | finite≠0 ÷ 0 | ±∞ (sign = sign of dividend) |
206
+ | ±∞ ÷ 0 | ±∞ (sign = sign of dividend) |
207
+ | finite ÷ ±∞ | +0 |
208
+ | ±∞⋅±∞ | ±∞ (sign = signs XOR) |
209
+ | finite≠0⋅±∞ | ±∞ (sign = signs XOR) |
210
+
211
+ The subnormal round-to-nearest behavior is illustrated below, compared against the basic flush to zero for any value
212
+ below the min normal. The timing/area cost of both approaches is approximately equivalent while the rounding method
213
+ halves the worst-case error.
214
+
215
+ ZKF only has a single canonical zero representation -- the positive zero. However, it is not an error to pass a
216
+ negative zero as an operand; the sign bit of a zero operand is simply ignored. This relaxation enables simplification
217
+ of certain basic operators.
218
+
219
+ <img src="docs/zkf_underflow_rounding.svg">
220
+
221
+ ### Accuracy of the transcendental functions
222
+
223
+ The exp2 and log2 transcendentals deliver faithful rounding: every finite result is one of the two representable
224
+ values bracketing the exact result.
225
+
226
+ A result differs from round-to-nearest only near a midpoint between adjacent representable values.
227
+ `zkf.Cordic` carries the same faithful-rounding contract.
228
+
229
+ <img src="docs/zkf_transcendental_accuracy.svg">
230
+
231
+ **ATTENTION:** the lookup tables of `zkf.Exp2` and `zkf.Log2` must be mapped to ROM; if fabric usage or timing looks
232
+ unreasonable, check the synthesis settings first, and if necessary give `rom_attrs`.
233
+
234
+ ## Sizing the exponent and the significand (wexp/wman)
235
+
236
+ The library is mostly focused on formats with wman≥7 (that is, at least 7 significand bits including the hidden one),
237
+ which covers all commonly encountered standard float formats.
238
+ Narrower wman is supported where logic generalizes to narrower widths without special-casing (e.g., in simple algebra).
239
+ Certain complex operators may require a larger minimal width where special efforts are required to support narrow
240
+ formats (e.g., CORDIC).
241
+ To support narrow formats, the optimal solution could be to introduce alternative operator implementations
242
+ instead of extending the existing ones; the reason is that narrow formats could be more efficiently implemented via
243
+ precomputed lookup tables rather than deriving the answer through live computation.
244
+
245
+ wexp can be chosen freely within an operator's limits, while wman is sensitive to the chip's DSP capabilities and thus
246
+ requires careful selection to achieve best resource utilization.
247
+
248
+ |wman |≈ε (interval)| Description |
249
+ |-----|-------------|---------------------------------------------------------------------------------------------|
250
+ | 16 | 3.052e-05 | DSP tiles in Lattice iCE40 and similar |
251
+ | 18 | 7.629e-06 | Classic FPGA DSP width, very common: ECP5, PolarFire, Trion, many Intel modes, etc. |
252
+ | 24 | 1.192e-07 | IEEE 754 binary32; also fits Versal DSP58's 27x24 asymmetric multiplier side |
253
+ | 27 | 1.490e-08 | Intel/Altera variable-precision DSPs |
254
+ | 32 | 4.657e-10 | 2x16 |
255
+ | 36 | 2.910e-11 | 2x18 (very common) or native Intel/Altera 36x36-style variable-precision mode |
256
+ | 48 | 7.105e-15 | 2x24 or 3x16; with an 8-bit exponent amounts to 7 bytes exactly |
257
+ | 53 | 2.220e-16 | IEEE 754 binary64 |
258
+
259
+ Narrower wman is rarely practical for computation due to low precision and fast error accumulation,
260
+ although they can still be useful for storage/exchange. One notable exception is neural networks though.
261
+
262
+ ### wman=18
263
+
264
+ An FPGA-friendly format because modern DSP-enabled FPGAs often implement 18x18 bit multipliers, which means that a
265
+ narrower mantissa is unlikely to save much resources or nontrivially improve timings as long as hardware multipliers
266
+ are used.
267
+
268
+ One can stay within 24 bits total by choosing wexp=6:
269
+
270
+ wexp=6 wman=18 wfrac=17 wfull=24 bias=31
271
+ lowest = 1/1073741824 ≈ 9.313e-10
272
+ max = 0xFFFF_C000 ≈ 4.295e+09
273
+ ε = 1/131072 ≈ 7.629e-06
274
+
275
+ ### wman=36
276
+
277
+ Similar to the above, wman=36 is efficient on common FPGAs because it maps multiplication to four 18x18 DSP slices.
278
+ This is often a better fit for intermediate result representation to avoid error accumulation --
279
+ the precision lands halfway between IEEE 754 binary64 and binary32.
280
+
281
+ Usually, on an 18x18 DSP chip, going even a single bit higher causes f_max to tank dramatically while area explodes.
282
+ Thus this is likely to be the optimal choice for a large number of applications.
283
+
284
+ Using binary32-compatible exponent wexp=8, 44 bits total (5.5 bytes):
285
+
286
+ wexp=8 wman=36 wfrac=35 wfull=44 bias=127
287
+ lowest = 1/85070591730234615865843651857942052864 ≈ 1.175e-38
288
+ max = 0xFFFFFFFF_F0000000_00000000_00000000 ≈ 3.403e+38
289
+ ε = 1/34359738368 ≈ 2.910e-11
290
+
291
+ ### IEEE 754-like and other standard float formats
292
+
293
+ ZKF offers limited compatibility with IEEE 754 so while it can match the bit layout,
294
+ not all states are mappable between the formats.
295
+
296
+ - wexp=5 wman=11: IEEE 754 binary16-like
297
+ - wexp=8 wman=24: IEEE 754 binary32-like
298
+ - wexp=11 wman=53: IEEE 754 binary64-like
299
+
300
+ Common non-IEEE formats:
301
+
302
+ - wexp=7 wman=17: AMD/ATI fp24-like
303
+ - wexp=8 wman=8: bfloat16-like
304
+ - wexp=8 wman=11: NVIDIA TF32-like (19 bits)
305
+
306
+ ## TODO
307
+
308
+ Roughly ordered by severity.
309
+
310
+ - Pre-tuned stage sets per operator and format, measured per flow and chip and ordered by latency, so that a user takes
311
+ the first that closes; or an API that takes the clock and the speed grade and picks one (preferred).
312
+ Each set is judged by its worst placement; a timing model would not do, as the binding paths are often mostly routing.
313
+
314
+ - `wmultiplier` is one number, the narrower side of a rectangular multiplier: two of its slices can be one tile on the
315
+ chip (25x18, 27x18), so a grid register may cut nothing there.