counted-float 0.8.4__tar.gz → 0.9.1__tar.gz

{counted_float-0.8.4 → counted_float-0.9.1}/.gitignore

@@ -30,4 +30,7 @@ Thumbs.db
 
 # IDE files
 .idea
-.vscode
+.vscode
+
+# other local files
+.local

{counted_float-0.8.4 → counted_float-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: counted-float
-Version: 0.8.4
+Version: 0.9.1
 Summary: Count floating-point operations in Python code & benchmark relative flop costs.
 Project-URL: Source, https://github.com/bertpl/counted-float
 Project-URL: ChangeLog, https://github.com/bertpl/counted-float/blob/develop/RELEASE_NOTES.md
@@ -18,9 +18,9 @@ Description-Content-Type: text/markdown
 
 <!--START_SECTION:images-->
 ![shields.io-python-versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
-![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/v0.8.4/badge-test-count.svg)
-![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.8.4/badge-coverage.svg)
-![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.8.4/splash.webp)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/v0.9.1/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.1/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.1/splash.webp)
 <!--END_SECTION:images-->
 
 # counted-float
@@ -167,10 +167,10 @@ and theoretical estimates of the relative cost of different floating point opera
     FlopType.SUB        [x-y]           :    1
     FlopType.MUL        [x*y]           :    1
     FlopType.DIV        [x/y]           :    3
-    FlopType.SQRT       [sqrt(x)]       :    4
+    FlopType.SQRT       [sqrt(x)]       :    3
     FlopType.POW2       [2^x]           :   12
-    FlopType.LOG2       [log2(x)]       :   15
-    FlopType.POW        [x^y]           :   32
+    FlopType.LOG2       [log2(x)]       :   14
+    FlopType.POW        [x^y]           :   33
 }
 ```
 These weights will be used by default when extracting total weighted flop costs:
@@ -189,10 +189,10 @@ with FlopCountingContext() as ctx:
     _ = math.log2(cf2)
     
 flop_counts = ctx.flop_counts()
-total_cost = flop_counts.total_weighted_cost()  # 1 + 32 + 15 = 48
+total_cost = flop_counts.total_weighted_cost()  # 1 + 33 + 14 = 48
 ```
 Note that the `total_weighted_cost` method will use the default flop weights as returned by `get_flop_weights()`.  This can be
-overridden by either configure different flop weights (see next section) or by setting the `weights` argument of the `total_weighted_cost()` method.
+overridden by either configuring different flop weights (see next section) or by setting the `weights` argument of the `total_weighted_cost()` method.
 
 
 ## 2.4. Configuring FLOP weights
@@ -202,13 +202,15 @@ using the `set_flop_weights()` function, which takes a `FlopWeights` object as a
 flop weights that might be obtained using benchmarks run on the target hardware (see later sections).
 
 ```python
-from counted_float.config import set_flop_weights
+from counted_float.config import set_active_flop_weights
 from counted_float import FlopWeights
 
-set_flop_weights(weights=FlopWeights(...))  # insert own weights here
+set_active_flop_weights(weights=FlopWeights(...))  # insert own weights here
 ```
 ## 2.5. Inspecting built-in data
 
+### 2.5.1. Default, pre-aggregated flop weights
+
 Built-in empirical, theoretical and consensus built-in flop weights can be inspected using the following functions:
 
 ```python
@@ -217,33 +219,64 @@ from counted_float.config import get_default_empirical_flop_weights, get_default
 >>> get_default_empirical_flop_weights(rounded=False).show()
 
 {
-    FlopType.ABS        [abs(x)]        :   0.94863
-    FlopType.MINUS      [-x]            :   0.74700
-    FlopType.EQUALS     [x==y]          :   0.91142
-    FlopType.GTE        [x>=y]          :   0.91889
-    FlopType.LTE        [x<=y]          :   0.90862
-    FlopType.CMP_ZERO   [x>=0]          :   0.80503
-    FlopType.RND        [round(x)]      :   1.00080
-    FlopType.ADD        [x+y]           :   0.86304
-    FlopType.SUB        [x-y]           :   1.19673
-    FlopType.MUL        [x*y]           :   1.06232
-    FlopType.DIV        [x/y]           :   3.50765
-    FlopType.SQRT       [sqrt(x)]       :   2.87080
-    FlopType.POW2       [2^x]           :  10.58784
-    FlopType.LOG2       [log2(x)]       :  17.08929
-    FlopType.POW        [x^y]           :  38.82827
+    FlopType.ABS        [abs(x)]        :   0.90744
+    FlopType.MINUS      [-x]            :   0.80068
+    FlopType.EQUALS     [x==y]          :   0.93532
+    FlopType.GTE        [x>=y]          :   0.94684
+    FlopType.LTE        [x<=y]          :   0.93101
+    FlopType.CMP_ZERO   [x>=0]          :   0.82204
+    FlopType.RND        [round(x)]      :   0.96944
+    FlopType.ADD        [x+y]           :   0.89296
+    FlopType.SUB        [x-y]           :   1.14383
+    FlopType.MUL        [x*y]           :   1.04677
+    FlopType.DIV        [x/y]           :   3.10940
+    FlopType.SQRT       [sqrt(x)]       :   2.56566
+    FlopType.POW2       [2^x]           :  10.80030
+    FlopType.LOG2       [log2(x)]       :  16.32770
+    FlopType.POW        [x^y]           :  40.50382
 }
 ```
 
-These 3 types of built-in weights are defined as follows:
-* `empirical`: geo-mean of the flop weights corresponding to the built-in **benchmarking** results
-* `theoretical`: geo-mean of the flop weights corresponding to the built-in **specification analyses** (FPU instruction latencies)
-* `consensus`: geo-mean of the `empirical` and `theoretical` flop weights
-
 The default weights that are configured in the package are the integer-rounded `consensus` weights.
 
+### 2.5.2. Custom-aggregated flop weights
+
+We can retrieve built-in flop weights in a more fine-grained manner, by custom filtering and the aggregating them with
+the geometric mean.
+
+```python
+from counted_float.config import get_builtin_flop_weights
+
+>>> get_builtin_flop_weights(key_filter="intel").show()
+
+{
+    FlopType.ABS        [abs(x)]        :   0.56708
+    FlopType.MINUS      [-x]            :   0.44910
+    FlopType.EQUALS     [x==y]          :   0.89744
+    FlopType.GTE        [x>=y]          :   0.89744
+    FlopType.LTE        [x<=y]          :   0.89744
+    FlopType.CMP_ZERO   [x>=0]          :   0.84762
+    FlopType.RND        [round(x)]      :   2.63592
+    FlopType.ADD        [x+y]           :   0.86616
+    FlopType.SUB        [x-y]           :   1.10411
+    FlopType.MUL        [x*y]           :   1.16515
+    FlopType.DIV        [x/y]           :   4.55230
+    FlopType.SQRT       [sqrt(x)]       :   4.37234
+    FlopType.POW2       [2^x]           :  14.78792
+    FlopType.LOG2       [log2(x)]       :  20.51270
+    FlopType.POW        [x^y]           :  40.16390
+}
+```
+
+The 3 built-in *default* flop weights are simply presets for the `key_filter` argument:  
+* `get_default_empirical_flop_weights()` --> `get_built_in_flop_weights(key_filter="benchmarks")`
+* `get_default_theoretical_flop_weights()` --> `get_built_in_flop_weights(key_filter="specs")`
+* `get_default_consensus_flop_weights()` --> `get_built_in_flop_weights(key_filter="")`
+
 # 3. Benchmarking
 
+## 3.1. General
+
 If the package is installed with the optional `numba` dependency, it provides
 the ability to micro-benchmark floating point operations as follows:
 
@@ -251,22 +284,25 @@ the ability to micro-benchmark floating point operations as follows:
 >>> from counted_float.benchmarking import run_flops_benchmark
 >>> results = run_flops_benchmark()
 
-baseline                           : wwwwwwwwww....................    186.43 ns ±    0.82 ns / operation
-FlopType.ABS        [abs(x)]       : wwwwwwwwww....................    300.85 ns ±    5.26 ns / operation
-FlopType.CMP_ZERO   [x>=0]         : wwwwwwwwww....................    307.79 ns ±    6.65 ns / operation
-FlopType.RND        [round(x)]     : wwwwwwwwww....................    307.62 ns ±    5.12 ns / operation
-FlopType.MINUS      [-x]           : wwwwwwwwww....................    302.88 ns ±    4.51 ns / operation
-FlopType.EQUALS     [x==y]         : wwwwwwwwww....................    328.41 ns ±    5.73 ns / operation
-FlopType.GTE        [x>=y]         : wwwwwwwwww....................    326.37 ns ±    5.07 ns / operation
-FlopType.LTE        [x<=y]         : wwwwwwwwww....................    322.10 ns ±    4.74 ns / operation
-FlopType.ADD        [x+y]          : wwwwwwwwww....................    317.28 ns ±    9.27 ns / operation
-FlopType.SUB        [x-y]          : wwwwwwwwww....................    320.05 ns ±    6.38 ns / operation
-FlopType.MUL        [x*y]          : wwwwwwwwww....................    325.44 ns ±    4.00 ns / operation
-FlopType.SQRT       [sqrt(x)]      : wwwwwwwwww....................    452.21 ns ±    4.32 ns / operation
-FlopType.DIV        [x/y]          : wwwwwwwwww....................    482.68 ns ±    0.93 ns / operation
-FlopType.POW2       [2^x]          : wwwwwwwwww....................      1.77 µs ±    0.00 µs / operation
-FlopType.LOG2       [log2(x)]      : wwwwwwwwww....................      2.15 µs ±    0.01 µs / operation
-FlopType.POW        [x^y]          : wwwwwwwwww....................      6.55 µs ±    0.01 µs / operation
+Running FLOPS benchmarks using counted-float 0.9.0 ...
+
+baseline                           : wwwwwwwwww....................    187.97 ns ±    0.52 ns / 1000 flops
+FlopType.ABS        [abs(x)]       : wwwwwwwwww....................    307.23 ns ±    8.37 ns / 1000 flops
+FlopType.CMP_ZERO   [x>=0]         : wwwwwwwwww....................    301.36 ns ±    7.22 ns / 1000 flops
+FlopType.RND        [round(x)]     : wwwwwwwwww....................    302.96 ns ±    8.39 ns / 1000 flops
+FlopType.MINUS      [-x]           : wwwwwwwwww....................    304.00 ns ±    7.99 ns / 1000 flops
+FlopType.EQUALS     [x==y]         : wwwwwwwwww....................    319.64 ns ±    6.71 ns / 1000 flops
+FlopType.GTE        [x>=y]         : wwwwwwwwww....................    325.35 ns ±    9.26 ns / 1000 flops
+FlopType.LTE        [x<=y]         : wwwwwwwwww....................    323.17 ns ±   11.45 ns / 1000 flops
+FlopType.ADD        [x+y]          : wwwwwwwwww....................    316.96 ns ±   11.11 ns / 1000 flops
+FlopType.SUB        [x-y]          : wwwwwwwwww....................    318.59 ns ±    9.36 ns / 1000 flops
+FlopType.MUL        [x*y]          : wwwwwwwwww....................    318.11 ns ±    7.16 ns / 1000 flops
+FlopType.SQRT       [sqrt(x)]      : wwwwwwwwww....................    449.06 ns ±    2.42 ns / 1000 flops
+FlopType.DIV        [x/y]          : wwwwwwwwww....................    483.70 ns ±    2.00 ns / 1000 flops
+FlopType.POW2       [2^x]          : wwwwwwwwww....................      1.77 µs ±    0.00 µs / 1000 flops
+FlopType.LOG2       [log2(x)]      : wwwwwwwwww....................      2.13 µs ±    0.01 µs / 1000 flops
+FlopType.POW        [x^y]          : wwwwwwwwww....................      6.53 µs ±    0.00 µs / 1000 flops
+
 
 >>> results.flop_weights.show() 
 
@@ -289,6 +325,21 @@ FlopType.POW        [x^y]          : wwwwwwwwww....................      6.55 µ
 }
 ```
 
+## 3.2. Using `uv`
+
+There's a lower-threshold way of running benchmarks if you have `uv` installed.  Simply install the package including `numba`.
+
+```
+uv tool install git+https://github.com/bertpl/counted-float@main[numba]         # latest official release
+uv tool install git+https://github.com/bertpl/counted-float@develop[numba]      # or latest develop version
+```
+After which you can run the `run_flops_benchmarks` command from the command line:
+```
+run_flops_benchmark
+```
+Final results will be shown as json.
+
+
 # 4. Known limitations
 
 - currently any non-Python-built-in math operations are not counted (e.g. `numpy`)

{counted_float-0.8.4 → counted_float-0.9.1}/README.md

@@ -1,8 +1,8 @@
 <!--START_SECTION:images-->
 ![shields.io-python-versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
-![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/v0.8.4/badge-test-count.svg)
-![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.8.4/badge-coverage.svg)
-![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.8.4/splash.webp)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/v0.9.1/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.1/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.1/splash.webp)
 <!--END_SECTION:images-->
 
 # counted-float
@@ -149,10 +149,10 @@ and theoretical estimates of the relative cost of different floating point opera
     FlopType.SUB        [x-y]           :    1
     FlopType.MUL        [x*y]           :    1
     FlopType.DIV        [x/y]           :    3
-    FlopType.SQRT       [sqrt(x)]       :    4
+    FlopType.SQRT       [sqrt(x)]       :    3
     FlopType.POW2       [2^x]           :   12
-    FlopType.LOG2       [log2(x)]       :   15
-    FlopType.POW        [x^y]           :   32
+    FlopType.LOG2       [log2(x)]       :   14
+    FlopType.POW        [x^y]           :   33
 }
 ```
 These weights will be used by default when extracting total weighted flop costs:
@@ -171,10 +171,10 @@ with FlopCountingContext() as ctx:
     _ = math.log2(cf2)
     
 flop_counts = ctx.flop_counts()
-total_cost = flop_counts.total_weighted_cost()  # 1 + 32 + 15 = 48
+total_cost = flop_counts.total_weighted_cost()  # 1 + 33 + 14 = 48
 ```
 Note that the `total_weighted_cost` method will use the default flop weights as returned by `get_flop_weights()`.  This can be
-overridden by either configure different flop weights (see next section) or by setting the `weights` argument of the `total_weighted_cost()` method.
+overridden by either configuring different flop weights (see next section) or by setting the `weights` argument of the `total_weighted_cost()` method.
 
 
 ## 2.4. Configuring FLOP weights
@@ -184,13 +184,15 @@ using the `set_flop_weights()` function, which takes a `FlopWeights` object as a
 flop weights that might be obtained using benchmarks run on the target hardware (see later sections).
 
 ```python
-from counted_float.config import set_flop_weights
+from counted_float.config import set_active_flop_weights
 from counted_float import FlopWeights
 
-set_flop_weights(weights=FlopWeights(...))  # insert own weights here
+set_active_flop_weights(weights=FlopWeights(...))  # insert own weights here
 ```
 ## 2.5. Inspecting built-in data
 
+### 2.5.1. Default, pre-aggregated flop weights
+
 Built-in empirical, theoretical and consensus built-in flop weights can be inspected using the following functions:
 
 ```python
@@ -199,33 +201,64 @@ from counted_float.config import get_default_empirical_flop_weights, get_default
 >>> get_default_empirical_flop_weights(rounded=False).show()
 
 {
-    FlopType.ABS        [abs(x)]        :   0.94863
-    FlopType.MINUS      [-x]            :   0.74700
-    FlopType.EQUALS     [x==y]          :   0.91142
-    FlopType.GTE        [x>=y]          :   0.91889
-    FlopType.LTE        [x<=y]          :   0.90862
-    FlopType.CMP_ZERO   [x>=0]          :   0.80503
-    FlopType.RND        [round(x)]      :   1.00080
-    FlopType.ADD        [x+y]           :   0.86304
-    FlopType.SUB        [x-y]           :   1.19673
-    FlopType.MUL        [x*y]           :   1.06232
-    FlopType.DIV        [x/y]           :   3.50765
-    FlopType.SQRT       [sqrt(x)]       :   2.87080
-    FlopType.POW2       [2^x]           :  10.58784
-    FlopType.LOG2       [log2(x)]       :  17.08929
-    FlopType.POW        [x^y]           :  38.82827
+    FlopType.ABS        [abs(x)]        :   0.90744
+    FlopType.MINUS      [-x]            :   0.80068
+    FlopType.EQUALS     [x==y]          :   0.93532
+    FlopType.GTE        [x>=y]          :   0.94684
+    FlopType.LTE        [x<=y]          :   0.93101
+    FlopType.CMP_ZERO   [x>=0]          :   0.82204
+    FlopType.RND        [round(x)]      :   0.96944
+    FlopType.ADD        [x+y]           :   0.89296
+    FlopType.SUB        [x-y]           :   1.14383
+    FlopType.MUL        [x*y]           :   1.04677
+    FlopType.DIV        [x/y]           :   3.10940
+    FlopType.SQRT       [sqrt(x)]       :   2.56566
+    FlopType.POW2       [2^x]           :  10.80030
+    FlopType.LOG2       [log2(x)]       :  16.32770
+    FlopType.POW        [x^y]           :  40.50382
 }
 ```
 
-These 3 types of built-in weights are defined as follows:
-* `empirical`: geo-mean of the flop weights corresponding to the built-in **benchmarking** results
-* `theoretical`: geo-mean of the flop weights corresponding to the built-in **specification analyses** (FPU instruction latencies)
-* `consensus`: geo-mean of the `empirical` and `theoretical` flop weights
-
 The default weights that are configured in the package are the integer-rounded `consensus` weights.
 
+### 2.5.2. Custom-aggregated flop weights
+
+We can retrieve built-in flop weights in a more fine-grained manner, by custom filtering and the aggregating them with
+the geometric mean.
+
+```python
+from counted_float.config import get_builtin_flop_weights
+
+>>> get_builtin_flop_weights(key_filter="intel").show()
+
+{
+    FlopType.ABS        [abs(x)]        :   0.56708
+    FlopType.MINUS      [-x]            :   0.44910
+    FlopType.EQUALS     [x==y]          :   0.89744
+    FlopType.GTE        [x>=y]          :   0.89744
+    FlopType.LTE        [x<=y]          :   0.89744
+    FlopType.CMP_ZERO   [x>=0]          :   0.84762
+    FlopType.RND        [round(x)]      :   2.63592
+    FlopType.ADD        [x+y]           :   0.86616
+    FlopType.SUB        [x-y]           :   1.10411
+    FlopType.MUL        [x*y]           :   1.16515
+    FlopType.DIV        [x/y]           :   4.55230
+    FlopType.SQRT       [sqrt(x)]       :   4.37234
+    FlopType.POW2       [2^x]           :  14.78792
+    FlopType.LOG2       [log2(x)]       :  20.51270
+    FlopType.POW        [x^y]           :  40.16390
+}
+```
+
+The 3 built-in *default* flop weights are simply presets for the `key_filter` argument:  
+* `get_default_empirical_flop_weights()` --> `get_built_in_flop_weights(key_filter="benchmarks")`
+* `get_default_theoretical_flop_weights()` --> `get_built_in_flop_weights(key_filter="specs")`
+* `get_default_consensus_flop_weights()` --> `get_built_in_flop_weights(key_filter="")`
+
 # 3. Benchmarking
 
+## 3.1. General
+
 If the package is installed with the optional `numba` dependency, it provides
 the ability to micro-benchmark floating point operations as follows:
 
@@ -233,22 +266,25 @@ the ability to micro-benchmark floating point operations as follows:
 >>> from counted_float.benchmarking import run_flops_benchmark
 >>> results = run_flops_benchmark()
 
-baseline                           : wwwwwwwwww....................    186.43 ns ±    0.82 ns / operation
-FlopType.ABS        [abs(x)]       : wwwwwwwwww....................    300.85 ns ±    5.26 ns / operation
-FlopType.CMP_ZERO   [x>=0]         : wwwwwwwwww....................    307.79 ns ±    6.65 ns / operation
-FlopType.RND        [round(x)]     : wwwwwwwwww....................    307.62 ns ±    5.12 ns / operation
-FlopType.MINUS      [-x]           : wwwwwwwwww....................    302.88 ns ±    4.51 ns / operation
-FlopType.EQUALS     [x==y]         : wwwwwwwwww....................    328.41 ns ±    5.73 ns / operation
-FlopType.GTE        [x>=y]         : wwwwwwwwww....................    326.37 ns ±    5.07 ns / operation
-FlopType.LTE        [x<=y]         : wwwwwwwwww....................    322.10 ns ±    4.74 ns / operation
-FlopType.ADD        [x+y]          : wwwwwwwwww....................    317.28 ns ±    9.27 ns / operation
-FlopType.SUB        [x-y]          : wwwwwwwwww....................    320.05 ns ±    6.38 ns / operation
-FlopType.MUL        [x*y]          : wwwwwwwwww....................    325.44 ns ±    4.00 ns / operation
-FlopType.SQRT       [sqrt(x)]      : wwwwwwwwww....................    452.21 ns ±    4.32 ns / operation
-FlopType.DIV        [x/y]          : wwwwwwwwww....................    482.68 ns ±    0.93 ns / operation
-FlopType.POW2       [2^x]          : wwwwwwwwww....................      1.77 µs ±    0.00 µs / operation
-FlopType.LOG2       [log2(x)]      : wwwwwwwwww....................      2.15 µs ±    0.01 µs / operation
-FlopType.POW        [x^y]          : wwwwwwwwww....................      6.55 µs ±    0.01 µs / operation
+Running FLOPS benchmarks using counted-float 0.9.0 ...
+
+baseline                           : wwwwwwwwww....................    187.97 ns ±    0.52 ns / 1000 flops
+FlopType.ABS        [abs(x)]       : wwwwwwwwww....................    307.23 ns ±    8.37 ns / 1000 flops
+FlopType.CMP_ZERO   [x>=0]         : wwwwwwwwww....................    301.36 ns ±    7.22 ns / 1000 flops
+FlopType.RND        [round(x)]     : wwwwwwwwww....................    302.96 ns ±    8.39 ns / 1000 flops
+FlopType.MINUS      [-x]           : wwwwwwwwww....................    304.00 ns ±    7.99 ns / 1000 flops
+FlopType.EQUALS     [x==y]         : wwwwwwwwww....................    319.64 ns ±    6.71 ns / 1000 flops
+FlopType.GTE        [x>=y]         : wwwwwwwwww....................    325.35 ns ±    9.26 ns / 1000 flops
+FlopType.LTE        [x<=y]         : wwwwwwwwww....................    323.17 ns ±   11.45 ns / 1000 flops
+FlopType.ADD        [x+y]          : wwwwwwwwww....................    316.96 ns ±   11.11 ns / 1000 flops
+FlopType.SUB        [x-y]          : wwwwwwwwww....................    318.59 ns ±    9.36 ns / 1000 flops
+FlopType.MUL        [x*y]          : wwwwwwwwww....................    318.11 ns ±    7.16 ns / 1000 flops
+FlopType.SQRT       [sqrt(x)]      : wwwwwwwwww....................    449.06 ns ±    2.42 ns / 1000 flops
+FlopType.DIV        [x/y]          : wwwwwwwwww....................    483.70 ns ±    2.00 ns / 1000 flops
+FlopType.POW2       [2^x]          : wwwwwwwwww....................      1.77 µs ±    0.00 µs / 1000 flops
+FlopType.LOG2       [log2(x)]      : wwwwwwwwww....................      2.13 µs ±    0.01 µs / 1000 flops
+FlopType.POW        [x^y]          : wwwwwwwwww....................      6.53 µs ±    0.00 µs / 1000 flops
+
 
 >>> results.flop_weights.show() 
 
@@ -271,6 +307,21 @@ FlopType.POW        [x^y]          : wwwwwwwwww....................      6.55 µ
 }
 ```
 
+## 3.2. Using `uv`
+
+There's a lower-threshold way of running benchmarks if you have `uv` installed.  Simply install the package including `numba`.
+
+```
+uv tool install git+https://github.com/bertpl/counted-float@main[numba]         # latest official release
+uv tool install git+https://github.com/bertpl/counted-float@develop[numba]      # or latest develop version
+```
+After which you can run the `run_flops_benchmarks` command from the command line:
+```
+run_flops_benchmark
+```
+Final results will be shown as json.
+
+
 # 4. Known limitations
 
 - currently any non-Python-built-in math operations are not counted (e.g. `numpy`)

{counted_float-0.8.4 → counted_float-0.9.1}/counted_float/_core/benchmarking/__init__.py

@@ -1,3 +1,5 @@
+from importlib.metadata import version
+
 from counted_float._core.counting.models import FlopsBenchmarkResults
 
 from ._flops_benchmark_suite import FlopsBenchmarkSuite
@@ -5,4 +7,13 @@ from ._flops_benchmark_suite import FlopsBenchmarkSuite
 
 def run_flops_benchmark() -> FlopsBenchmarkResults:
     """Run the flops benchmark suite with default settings returns a FlopsBenchmarkResults object."""
-    return FlopsBenchmarkSuite().run()
+
+    print()
+    print(f"Running FLOPS benchmarks using counted-float {version('counted-float')} ...")
+    print()
+
+    benchmark_results = FlopsBenchmarkSuite().run()
+
+    print()
+
+    return benchmark_results

{counted_float-0.8.4 → counted_float-0.9.1}/counted_float/_core/benchmarking/_flops_micro_benchmark.py

@@ -33,7 +33,7 @@ class FlopsMicroBenchmark(MicroBenchmark):
     """
 
     def __init__(self, name: str, f: Callable, size: int):
-        super().__init__(name=name)
+        super().__init__(name=name, single_operation=f"{size} flops")
         self.size = size
         self.f = f
         self.n_operations = 0

{counted_float-0.8.4 → counted_float-0.9.1}/counted_float/_core/benchmarking/_micro_benchmark.py

@@ -23,8 +23,9 @@ class MicroBenchmark(ABC):
 
     MAX_N_OPERATIONS_FACTOR = 10  # never adjust n_operations by more than this factor (up or down)
 
-    def __init__(self, name: str):
+    def __init__(self, name: str, single_operation: str = "operation"):
         self.name = name
+        self.single_operation = single_operation
 
     def run_many(
         self, n_runs_total: int = 20, n_runs_warmup: int = 5, n_seconds_per_run_target: float = 0.5
@@ -74,7 +75,8 @@ class MicroBenchmark(ABC):
             benchmark_runs=benchmark_runs,
         )
         stats = benchmark_result.summary_stats()
-        print(f"   {format_time_durations(nsec_q25=stats.q25, nsec_q50=stats.q50, nsec_q75=stats.q75)}")
+        s_time_duration = format_time_durations(nsec_q25=stats.q25, nsec_q50=stats.q50, nsec_q75=stats.q75)
+        print(f"   {s_time_duration} / {self.single_operation}")
 
         # return quantiles
         return benchmark_result

{counted_float-0.8.4 → counted_float-0.9.1}/counted_float/_core/benchmarking/_time_utils.py

@@ -14,7 +14,7 @@ def format_time_durations(nsec_q25: float, nsec_q50: float, nsec_q75: float) ->
     else:
         formatter = _format_nsec_as_s
 
-    return f"{formatter(nsec_q50)} ± {formatter((nsec_q75 - nsec_q25) / 2)} / operation"
+    return f"{formatter(nsec_q50)} ± {formatter((nsec_q75 - nsec_q25) / 2)}"
 
 
 def _format_nsec_as_ns(nsec: float) -> str:

counted_float-0.9.1/counted_float/_core/counting/_builtin_data.py

@@ -0,0 +1,147 @@
+from importlib.resources import files
+
+from pydantic import ValidationError
+
+from counted_float._core.counting.models import FlopsBenchmarkResults, FlopWeights, InstructionLatencies
+
+
+# =================================================================================================
+#  Main accessor class
+# =================================================================================================
+class BuiltInData:
+    """
+    A class that provides access to built-in data for the counted_float package.
+    """
+
+    # -------------------------------------------------------------------------
+    #  FlopWeights
+    # -------------------------------------------------------------------------
+    @classmethod
+    def get_flop_weights(cls, key_filter: str = "") -> FlopWeights:
+        """
+        Return averaged FlopWeights over all FlopWeights found using get_flop_weights_dict for the provided key_filter.
+
+        Averaging happens one key-level at a time, which implicitly defines a recursive weighting scheme. At every level
+        of aggregation, an attempt is made to impute missing data (if any) to avoid biasing the average towards entries
+        with more complete data.
+        """
+        flat_flop_weights_dict = cls.get_flop_weights_dict(key_filter)
+        if len(flat_flop_weights_dict) == 0:
+            raise ValueError(f"No built-in flop weights found for key_filter='{key_filter}'")
+        else:
+            nested_flop_weights_dict = _flat_to_nested_dict(flat_flop_weights_dict)
+            return _computed_nested_average_flop_weights(nested_flop_weights_dict)
+
+    @classmethod
+    def get_flop_weights_dict(cls, key_filter: str = "") -> dict[str, FlopWeights]:
+        """
+        Get the built-in flop weights data as a dict mapping key -> FlopWeights.
+
+        Keys be .-separated values indicating the path + filename of the source data file, e.g.:
+            'benchmarks.arm.apple_m4_pro'
+            'specs.x86.intel_core_i9_13900k'
+            ...
+
+        :param key_filter: (str, default="") If non-empty, only include entries whose keys contain this substring.
+        :return: A dictionary mapping benchmark names to their corresponding FlopsBenchmarkResults.
+        """
+        return {
+            key: _construct_flop_weights_from_json_str(json_str)
+            for key, json_str in _load_json_files_as_dict(files("counted_float._core.data")).items()
+            if key_filter in key
+        }
+
+    # -------------------------------------------------------------------------
+    #  Benchmarks
+    # -------------------------------------------------------------------------
+    @classmethod
+    def benchmarks(cls) -> dict[str, FlopsBenchmarkResults]:
+        return {
+            key: FlopsBenchmarkResults.model_validate_json(json_str)
+            for key, json_str in _load_json_files_as_dict(files("counted_float._core.data.benchmarks")).items()
+        }
+
+    # -------------------------------------------------------------------------
+    #  Specs
+    # -------------------------------------------------------------------------
+    @classmethod
+    def specs(cls) -> dict[str, InstructionLatencies]:
+        return {
+            key: InstructionLatencies.model_validate_json(json_str)
+            for key, json_str in _load_json_files_as_dict(files("counted_float._core.data.specs")).items()
+        }
+
+
+# =================================================================================================
+#  Utilities
+# =================================================================================================
+def _computed_nested_average_flop_weights(nested_flop_weights_dict: dict[str, dict | FlopWeights]) -> FlopWeights:
+    # make sure all values of the dict are FlopWeights instances
+    for key, value in nested_flop_weights_dict.items():
+        if isinstance(value, dict):
+            nested_flop_weights_dict[key] = _computed_nested_average_flop_weights(value)
+
+    # now we can average all FlopWeights instances
+    return FlopWeights.as_geo_mean(list(nested_flop_weights_dict.values()))
+
+
+def _flat_to_nested_dict(flat_dict: dict) -> dict:
+    """
+    Convert a flat dict with .-separated keys to a nested dict.
+    E.g. {'a.b.c': 1, 'a.b.d': 2, 'a.e': 3} -> {'a': {'b': {'c': 1, 'd': 2}, 'e': 3}}
+    """
+    nested_dict = {}
+    for flat_key, value in flat_dict.items():
+        keys = flat_key.split(".")
+        d = nested_dict
+        for key in keys[:-1]:
+            d = d.setdefault(key, dict())
+        d[keys[-1]] = value
+    return nested_dict
+
+
+def _load_json_files_as_dict(resource_root) -> dict[str, str]:
+    """
+    Read all .json files recursively from the given resource root (or the default one) and return
+    a dict mapping key -> json_str, where keys are .-separated values indicating the path
+        + filename of the source data file.
+
+    Example keys: 'benchmarks.arm.apple_m4_pro'
+                  'specs.x86.intel_core_i9_13900k'
+    """
+
+    # allow both plain & recursive calls
+    # if resource_root is None:
+    #     resource_root = files("counted_float._core.data")
+
+    # crawl entire folder structure
+    result = {}
+    for entry in resource_root.iterdir():
+        if entry.is_dir():
+            sub_dir_json_dict = _load_json_files_as_dict(entry)
+            for key, value in sub_dir_json_dict.items():
+                result[f"{entry.name}.{key}"] = value
+        elif entry.is_file() and entry.name.endswith(".json"):
+            result[entry.stem] = entry.read_text(encoding="utf-8")
+    return result
+
+
+def _construct_flop_weights_from_json_str(json_str: str) -> FlopWeights:
+    """
+    Construct a FlopWeights instance from a JSON string, where the JSON string can represent either...
+      - FlopsBenchmarkResults
+      - InstructionLatencies
+    :param json_str: (str) JSON string representing either of the aforementioned data structures.
+    :return: FlopWeights instance extracted from the input data.
+    """
+
+    # try all supported classes, all of which have a .flop_weights property
+    for pydantic_cls in [FlopsBenchmarkResults, InstructionLatencies]:
+        try:
+            obj = pydantic_cls.model_validate_json(json_str)
+            return obj.flop_weights
+        except ValidationError:
+            continue
+
+    # none of the supported classes worked
+    raise ValueError("Input JSON string does not represent a known data structure.")