counted-float 0.9.0__tar.gz → 0.9.2__tar.gz

{counted_float-0.9.0 → counted_float-0.9.2}/.gitignore

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

{counted_float-0.9.0 → counted_float-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: counted-float
-Version: 0.9.0
+Version: 0.9.2
 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
@@ -12,35 +12,32 @@ Requires-Dist: backports-strenum>=1.3.1
 Requires-Dist: numpy>=1.20
 Requires-Dist: psutil>=5.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: cli
+Requires-Dist: click>=8.0.0; extra == 'cli'
 Provides-Extra: numba
 Requires-Dist: numba>=0.50; extra == 'numba'
 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.9.0/badge-test-count.svg)
-![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.0/badge-coverage.svg)
-![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.0/splash.webp)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/v0.9.2/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.2/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.2/splash.webp)
 <!--END_SECTION:images-->
 
 # counted-float
 
-This Python package provides functionality for counting the number of floating point operations (FLOPs) of numerical
-algorithms implemented in plain Python.
+This Python package provides functionality for...
+- **counting floating point operations** (FLOPs) of numerical algorithms implemented in plain Python, optionally weighted by their relative cost of execution
+- **running benchmarks** to estimate the relative cost of executing various floating-point operations (requires `numba` optional dependency for achieving accurate results)
 
-The target application area are research prototypes of numerical algorithms where (weighted) flop counting can be 
+The target application area is evaluation of research prototypes of numerical algorithms where (weighted) flop counting can be 
 useful for estimating total computational cost, in cases where benchmarking a compiled version (C, Rust, ...) is not 
 feasible or desirable.
 
-The package contains two components:
- - `counting`: provides a CountedFloat class & flop counting context managers to count flops of code blocks.
- - `benchmarking`: provides functionality to micro-benchmark floating point operations to get an empirical
-   ballpark estimate of the relative cost of different operations on the target hardware.  Requires 'numba' optional dependency for accurate results.
-
 # 1. Installation
 
-
-
 Use you favorite package manager such as `uv` or `pip`:
 
 ```
@@ -50,6 +47,8 @@ pip install counted-float[numba]    # install with numba optional dependency
 Numba is optional due to its relatively large size (40-50MB, including llvmlite), but without it, benchmarks will
 not be reliable (but will still run, but not in jit-compiled form).
 
+NOTE: the `cli` optional dependency is only useful when installing the code as a tool using e.g. `uv` or `pipx` (see below)
+
 # 2. Counting Flops
 
 ## 2.1. CountedFloat class
@@ -275,72 +274,105 @@ The 3 built-in *default* flop weights are simply presets for the `key_filter` ar
 
 # 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:
+If the package is installed with the optional `numba` dependency, it provides the ability to micro-benchmark 
+floating point operations as follows:
 
 ```
 >>> from counted_float.benchmarking import run_flops_benchmark
 >>> results = run_flops_benchmark()
 
-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
-
+Running FLOPS benchmarks using counted-float 0.9.2 ...
+
+baseline                           : wwwwwwwwww....................   ( 187.03 ns =   759 cpu cycles) ±  0.6%  /  1000 iterations
+FlopType.ABS        [abs(x)]       : wwwwwwwwww....................   ( 303.31 ns = 1.23K cpu cycles) ±  1.7%  /  1000 iterations
+FlopType.CMP_ZERO   [x>=0]         : wwwwwwwwww....................   ( 302.19 ns = 1.23K cpu cycles) ±  3.0%  /  1000 iterations
+FlopType.RND        [round(x)]     : wwwwwwwwww....................   ( 305.95 ns = 1.24K cpu cycles) ±  4.8%  /  1000 iterations
+FlopType.MINUS      [-x]           : wwwwwwwwww....................   ( 306.31 ns = 1.24K cpu cycles) ±  2.6%  /  1000 iterations
+FlopType.EQUALS     [x==y]         : wwwwwwwwww....................   ( 320.59 ns = 1.30K cpu cycles) ±  3.9%  /  1000 iterations
+FlopType.GTE        [x>=y]         : wwwwwwwwww....................   ( 331.51 ns = 1.34K cpu cycles) ±  2.9%  /  1000 iterations
+FlopType.LTE        [x<=y]         : wwwwwwwwww....................   ( 333.81 ns = 1.35K cpu cycles) ±  1.0%  /  1000 iterations
+FlopType.ADD        [x+y]          : wwwwwwwwww....................   ( 315.84 ns = 1.28K cpu cycles) ±  3.2%  /  1000 iterations
+FlopType.SUB        [x-y]          : wwwwwwwwww....................   ( 335.49 ns = 1.36K cpu cycles) ±  3.8%  /  1000 iterations
+FlopType.MUL        [x*y]          : wwwwwwwwww....................   ( 325.65 ns = 1.32K cpu cycles) ±  3.0%  /  1000 iterations
+FlopType.SQRT       [sqrt(x)]      : wwwwwwwwww....................   ( 443.30 ns = 1.80K cpu cycles) ±  2.6%  /  1000 iterations
+FlopType.DIV        [x/y]          : wwwwwwwwww....................   ( 491.51 ns = 1.99K cpu cycles) ±  1.1%  /  1000 iterations
+FlopType.POW2       [2^x]          : wwwwwwwwww....................   (   1.79 µs = 7.28K cpu cycles) ±  0.3%  /  1000 iterations
+FlopType.LOG2       [log2(x)]      : wwwwwwwwww....................   (   2.17 µs = 8.80K cpu cycles) ±  0.8%  /  1000 iterations
+FlopType.POW        [x^y]          : wwwwwwwwww....................   (   6.32 µs = 25.6K cpu cycles) ±  0.7%  /  1000 iterations
 
 >>> results.flop_weights.show() 
 
 {
-    FlopType.ABS        [abs(x)]        :   0.83953
-    FlopType.MINUS      [-x]            :   0.85441
-    FlopType.EQUALS     [x==y]          :   1.04173
-    FlopType.GTE        [x>=y]          :   1.02677
-    FlopType.LTE        [x<=y]          :   0.99542
-    FlopType.CMP_ZERO   [x>=0]          :   0.89041
-    FlopType.RND        [round(x)]      :   0.88915
-    FlopType.ADD        [x+y]           :   0.96007
-    FlopType.SUB        [x-y]           :   0.98034
-    FlopType.MUL        [x*y]           :   1.01992
-    FlopType.DIV        [x/y]           :   2.17358
-    FlopType.SQRT       [sqrt(x)]       :   1.95006
-    FlopType.POW2       [2^x]           :  11.65331
-    FlopType.LOG2       [log2(x)]       :  14.38278
-    FlopType.POW        [x^y]           :  46.72479
+    FlopType.ABS        [abs(x)]        :   0.84769
+    FlopType.MINUS      [-x]            :   0.86954
+    FlopType.EQUALS     [x==y]          :   0.97369
+    FlopType.GTE        [x>=y]          :   1.05327
+    FlopType.LTE        [x<=y]          :   1.07007
+    FlopType.CMP_ZERO   [x>=0]          :   0.83957
+    FlopType.RND        [round(x)]      :   0.86695
+    FlopType.ADD        [x+y]           :   0.93905
+    FlopType.SUB        [x-y]           :   1.08227
+    FlopType.MUL        [x*y]           :   1.01055
+    FlopType.DIV        [x/y]           :   2.21970
+    FlopType.SQRT       [sqrt(x)]       :   1.86822
+    FlopType.POW2       [2^x]           :  11.72183
+    FlopType.LOG2       [log2(x)]       :  14.45542
+    FlopType.POW        [x^y]           :  44.68266
 }
 ```
 
-## 3.2. Using `uv`
+## 4. Installing the package as a command-line tool
 
-There's a lower-threshold way of running benchmarks if you have `uv` installed.  Simply install the package including `numba`.
+An alternative way of using (parts) of the functionality is installing the package as a stand-alone command-line tool
+using `uv` or `pipx`:
 
 ```
-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
+uv tool install git+https://github.com/bertpl/counted-float@main[numba,cli]         # latest official release
+uv tool install git+https://github.com/bertpl/counted-float@develop[numba,cli]      # or latest develop version
 ```
-After which you can run the `run_flops_benchmarks` command from the command line:
+This installs the `counted_float` command-line tool, which can be used to e.g. run flops benchmarks.
+
+## 4.1 Running benchmarks
+
 ```
-run_flops_benchmark
+counted_float benchmark
 ```
-Final results will be shown as json.
+after which the results will be shown as .json.
+
+## 4.2. Show built-in data
 
+```
+[~] counted_float show-data
+                                           MINUS       ABS  CMP_ZERO       LTE    EQUALS       GTE       ADD       SUB       MUL       RND      SQRT       DIV      POW2      LOG2       POW
+ALL                                         0.59      0.63      0.74      0.90      0.90      0.90      0.92      1.05      1.15      1.25      3.55      3.57     12.33     14.68     34.01
+ ├─benchmarks                               0.80      0.91      0.82      0.93      0.94      0.95      0.89      1.14      1.05      0.97      2.57      3.11     10.80     16.33     40.50
+ │  ├─arm                                   0.99      0.79      0.88      1.00      1.01      1.04      0.99      1.00      1.00      0.88      1.83      2.17     11.46     14.24     45.98
+ │  │  └─apple                              0.99      0.79      0.88      1.00      1.01      1.04      0.99      1.00      1.00      0.88      1.83      2.17     11.46     14.24     45.98
+ │  │     └─m3_max_macbook_pro_16           0.99      0.79      0.88      1.00      1.01      1.04      0.99      1.00      1.00      0.88      1.83      2.17     11.46     14.24     45.98
+ │  └─x86                                   0.65      1.04      0.77      0.87      0.87      0.87      0.81      1.31      1.09      1.07      3.59      4.46     10.18     18.72     35.68
+ │     └─intel                              0.65      1.04      0.77      0.87      0.87      0.87      0.81      1.31      1.09      1.07      3.59      4.46     10.18     18.72     35.68
+ │        ├─gen12_i7_1265u                  1.06      1.08      1.26      1.24      1.24      1.24      0.85      1.02      0.93      3.94      6.38      8.69     20.67     40.99     87.44
+ │        └─gen7_i5_7200u                   0.40      0.99      0.47      0.60      0.60      0.60      0.77      1.68      1.29      0.29      2.03      2.29      5.01      8.55     14.56
+ └─specs                                    0.43      0.43      0.67      0.86      0.86      0.86      0.96      0.96      1.27      1.61      4.92      4.09     14.08     13.20     28.56
+    ├─arm                                   0.82      0.82      0.65      0.65      0.65      0.65      1.03      1.03      1.45      1.35      5.92      5.53        /         /         / 
+    │  ├─arm_v7a_cortex_a9                  0.32      0.32      0.32      0.32      0.32      0.32      1.28      1.28      1.92      1.28     10.22      7.99        /         /         / 
+    │  ├─arm_v8_cortex_a55                  1.41      1.41      0.35      0.35      0.35      0.35      1.41      1.41      1.41      1.41      7.78      7.78        /         /         / 
+    │  ├─arm_v8_cortex_a76                  0.90      0.90      0.90      0.90      0.90      0.90      0.90      0.90      1.36      1.36      4.93      4.63        /         /         / 
+    │  ├─arm_v9_cortex_x1                   0.90      0.90      0.90      0.90      0.90      0.90      0.90      0.90      1.36      1.36      4.78      4.63        /         /         / 
+    │  ├─arm_v9_cortex_x2                   0.90      0.90      0.90      0.90      0.90      0.90      0.90      0.90      1.36      1.36      4.78      4.63        /         /         / 
+    │  └─arm_v9_cortex_x3                   0.90      0.90      0.90      0.90      0.90      0.90      0.90      0.90      1.36      1.36      4.78      4.63        /         /         / 
+    └─x86                                   0.23      0.23      0.70      1.14      1.14      1.14      0.89      0.89      1.11      1.92      4.09      3.02     12.96     12.15     26.29
+       ├─amd                                0.17      0.17        /       1.45      1.45      1.45      0.88      0.88      0.88      0.59      3.26      2.04      7.89      6.93     15.71
+       │  ├─zen3_r7_5800x                   0.14      0.14        /       1.49      1.49      1.49      0.88      0.88      0.88      0.54      3.38      2.03      7.40      6.62     14.90
+       │  ├─zen4_r9_7900x                   0.13      0.13        /       1.40      1.40      1.40      0.89      0.89      0.89      0.64      3.19      1.91      6.99      6.25     14.13
+       │  └─zen5_r7_9800x3d                 0.29      0.29        /       1.47      1.47      1.47      0.88      0.88      0.88      0.59      3.23      2.20      9.51      8.03     18.42
+       └─intel                              0.30      0.30      0.90      0.90      0.90      0.90      0.90      0.90      1.39      6.28      5.12      4.47     21.27     21.31     43.97
+          ├─gen09_coffee_lake               0.29      0.29      0.88      0.88      0.88      0.88      0.88      0.88      1.47      6.16      5.03      4.39     21.16     20.74     43.37
+          ├─gen10_cannon_lake               0.29      0.29      0.88      0.88      0.88      0.88      0.88      0.88      1.47      6.16      5.03      4.39     21.16     20.74     43.37
+          └─gen11_tiger_lake                0.31      0.31      0.93      0.93      0.93      0.93      0.93      0.93      1.24      6.51      5.32      4.64     21.49     22.48     45.21
+```
 
-# 4. Known limitations
+# 5. Known limitations
 
 - currently any non-Python-built-in math operations are not counted (e.g. `numpy`)
 - not all Python built-in math operations are counted (e.g. `log`, `log10`, `exp`, `exp10`)

{counted_float-0.9.0 → counted_float-0.9.2}/README.md

@@ -1,28 +1,22 @@
 <!--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.9.0/badge-test-count.svg)
-![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.0/badge-coverage.svg)
-![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.0/splash.webp)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/v0.9.2/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.2/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.2/splash.webp)
 <!--END_SECTION:images-->
 
 # counted-float
 
-This Python package provides functionality for counting the number of floating point operations (FLOPs) of numerical
-algorithms implemented in plain Python.
+This Python package provides functionality for...
+- **counting floating point operations** (FLOPs) of numerical algorithms implemented in plain Python, optionally weighted by their relative cost of execution
+- **running benchmarks** to estimate the relative cost of executing various floating-point operations (requires `numba` optional dependency for achieving accurate results)
 
-The target application area are research prototypes of numerical algorithms where (weighted) flop counting can be 
+The target application area is evaluation of research prototypes of numerical algorithms where (weighted) flop counting can be 
 useful for estimating total computational cost, in cases where benchmarking a compiled version (C, Rust, ...) is not 
 feasible or desirable.
 
-The package contains two components:
- - `counting`: provides a CountedFloat class & flop counting context managers to count flops of code blocks.
- - `benchmarking`: provides functionality to micro-benchmark floating point operations to get an empirical
-   ballpark estimate of the relative cost of different operations on the target hardware.  Requires 'numba' optional dependency for accurate results.
-
 # 1. Installation
 
-
-
 Use you favorite package manager such as `uv` or `pip`:
 
 ```
@@ -32,6 +26,8 @@ pip install counted-float[numba]    # install with numba optional dependency
 Numba is optional due to its relatively large size (40-50MB, including llvmlite), but without it, benchmarks will
 not be reliable (but will still run, but not in jit-compiled form).
 
+NOTE: the `cli` optional dependency is only useful when installing the code as a tool using e.g. `uv` or `pipx` (see below)
+
 # 2. Counting Flops
 
 ## 2.1. CountedFloat class
@@ -257,72 +253,105 @@ The 3 built-in *default* flop weights are simply presets for the `key_filter` ar
 
 # 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:
+If the package is installed with the optional `numba` dependency, it provides the ability to micro-benchmark 
+floating point operations as follows:
 
 ```
 >>> from counted_float.benchmarking import run_flops_benchmark
 >>> results = run_flops_benchmark()
 
-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
-
+Running FLOPS benchmarks using counted-float 0.9.2 ...
+
+baseline                           : wwwwwwwwww....................   ( 187.03 ns =   759 cpu cycles) ±  0.6%  /  1000 iterations
+FlopType.ABS        [abs(x)]       : wwwwwwwwww....................   ( 303.31 ns = 1.23K cpu cycles) ±  1.7%  /  1000 iterations
+FlopType.CMP_ZERO   [x>=0]         : wwwwwwwwww....................   ( 302.19 ns = 1.23K cpu cycles) ±  3.0%  /  1000 iterations
+FlopType.RND        [round(x)]     : wwwwwwwwww....................   ( 305.95 ns = 1.24K cpu cycles) ±  4.8%  /  1000 iterations
+FlopType.MINUS      [-x]           : wwwwwwwwww....................   ( 306.31 ns = 1.24K cpu cycles) ±  2.6%  /  1000 iterations
+FlopType.EQUALS     [x==y]         : wwwwwwwwww....................   ( 320.59 ns = 1.30K cpu cycles) ±  3.9%  /  1000 iterations
+FlopType.GTE        [x>=y]         : wwwwwwwwww....................   ( 331.51 ns = 1.34K cpu cycles) ±  2.9%  /  1000 iterations
+FlopType.LTE        [x<=y]         : wwwwwwwwww....................   ( 333.81 ns = 1.35K cpu cycles) ±  1.0%  /  1000 iterations
+FlopType.ADD        [x+y]          : wwwwwwwwww....................   ( 315.84 ns = 1.28K cpu cycles) ±  3.2%  /  1000 iterations
+FlopType.SUB        [x-y]          : wwwwwwwwww....................   ( 335.49 ns = 1.36K cpu cycles) ±  3.8%  /  1000 iterations
+FlopType.MUL        [x*y]          : wwwwwwwwww....................   ( 325.65 ns = 1.32K cpu cycles) ±  3.0%  /  1000 iterations
+FlopType.SQRT       [sqrt(x)]      : wwwwwwwwww....................   ( 443.30 ns = 1.80K cpu cycles) ±  2.6%  /  1000 iterations
+FlopType.DIV        [x/y]          : wwwwwwwwww....................   ( 491.51 ns = 1.99K cpu cycles) ±  1.1%  /  1000 iterations
+FlopType.POW2       [2^x]          : wwwwwwwwww....................   (   1.79 µs = 7.28K cpu cycles) ±  0.3%  /  1000 iterations
+FlopType.LOG2       [log2(x)]      : wwwwwwwwww....................   (   2.17 µs = 8.80K cpu cycles) ±  0.8%  /  1000 iterations
+FlopType.POW        [x^y]          : wwwwwwwwww....................   (   6.32 µs = 25.6K cpu cycles) ±  0.7%  /  1000 iterations
 
 >>> results.flop_weights.show() 
 
 {
-    FlopType.ABS        [abs(x)]        :   0.83953
-    FlopType.MINUS      [-x]            :   0.85441
-    FlopType.EQUALS     [x==y]          :   1.04173
-    FlopType.GTE        [x>=y]          :   1.02677
-    FlopType.LTE        [x<=y]          :   0.99542
-    FlopType.CMP_ZERO   [x>=0]          :   0.89041
-    FlopType.RND        [round(x)]      :   0.88915
-    FlopType.ADD        [x+y]           :   0.96007
-    FlopType.SUB        [x-y]           :   0.98034
-    FlopType.MUL        [x*y]           :   1.01992
-    FlopType.DIV        [x/y]           :   2.17358
-    FlopType.SQRT       [sqrt(x)]       :   1.95006
-    FlopType.POW2       [2^x]           :  11.65331
-    FlopType.LOG2       [log2(x)]       :  14.38278
-    FlopType.POW        [x^y]           :  46.72479
+    FlopType.ABS        [abs(x)]        :   0.84769
+    FlopType.MINUS      [-x]            :   0.86954
+    FlopType.EQUALS     [x==y]          :   0.97369
+    FlopType.GTE        [x>=y]          :   1.05327
+    FlopType.LTE        [x<=y]          :   1.07007
+    FlopType.CMP_ZERO   [x>=0]          :   0.83957
+    FlopType.RND        [round(x)]      :   0.86695
+    FlopType.ADD        [x+y]           :   0.93905
+    FlopType.SUB        [x-y]           :   1.08227
+    FlopType.MUL        [x*y]           :   1.01055
+    FlopType.DIV        [x/y]           :   2.21970
+    FlopType.SQRT       [sqrt(x)]       :   1.86822
+    FlopType.POW2       [2^x]           :  11.72183
+    FlopType.LOG2       [log2(x)]       :  14.45542
+    FlopType.POW        [x^y]           :  44.68266
 }
 ```
 
-## 3.2. Using `uv`
+## 4. Installing the package as a command-line tool
 
-There's a lower-threshold way of running benchmarks if you have `uv` installed.  Simply install the package including `numba`.
+An alternative way of using (parts) of the functionality is installing the package as a stand-alone command-line tool
+using `uv` or `pipx`:
 
 ```
-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
+uv tool install git+https://github.com/bertpl/counted-float@main[numba,cli]         # latest official release
+uv tool install git+https://github.com/bertpl/counted-float@develop[numba,cli]      # or latest develop version
 ```
-After which you can run the `run_flops_benchmarks` command from the command line:
+This installs the `counted_float` command-line tool, which can be used to e.g. run flops benchmarks.
+
+## 4.1 Running benchmarks
+
 ```
-run_flops_benchmark
+counted_float benchmark
 ```
-Final results will be shown as json.
+after which the results will be shown as .json.
+
+## 4.2. Show built-in data
 
+```
+[~] counted_float show-data
+                                           MINUS       ABS  CMP_ZERO       LTE    EQUALS       GTE       ADD       SUB       MUL       RND      SQRT       DIV      POW2      LOG2       POW
+ALL                                         0.59      0.63      0.74      0.90      0.90      0.90      0.92      1.05      1.15      1.25      3.55      3.57     12.33     14.68     34.01
+ ├─benchmarks                               0.80      0.91      0.82      0.93      0.94      0.95      0.89      1.14      1.05      0.97      2.57      3.11     10.80     16.33     40.50
+ │  ├─arm                                   0.99      0.79      0.88      1.00      1.01      1.04      0.99      1.00      1.00      0.88      1.83      2.17     11.46     14.24     45.98
+ │  │  └─apple                              0.99      0.79      0.88      1.00      1.01      1.04      0.99      1.00      1.00      0.88      1.83      2.17     11.46     14.24     45.98
+ │  │     └─m3_max_macbook_pro_16           0.99      0.79      0.88      1.00      1.01      1.04      0.99      1.00      1.00      0.88      1.83      2.17     11.46     14.24     45.98
+ │  └─x86                                   0.65      1.04      0.77      0.87      0.87      0.87      0.81      1.31      1.09      1.07      3.59      4.46     10.18     18.72     35.68
+ │     └─intel                              0.65      1.04      0.77      0.87      0.87      0.87      0.81      1.31      1.09      1.07      3.59      4.46     10.18     18.72     35.68
+ │        ├─gen12_i7_1265u                  1.06      1.08      1.26      1.24      1.24      1.24      0.85      1.02      0.93      3.94      6.38      8.69     20.67     40.99     87.44
+ │        └─gen7_i5_7200u                   0.40      0.99      0.47      0.60      0.60      0.60      0.77      1.68      1.29      0.29      2.03      2.29      5.01      8.55     14.56
+ └─specs                                    0.43      0.43      0.67      0.86      0.86      0.86      0.96      0.96      1.27      1.61      4.92      4.09     14.08     13.20     28.56
+    ├─arm                                   0.82      0.82      0.65      0.65      0.65      0.65      1.03      1.03      1.45      1.35      5.92      5.53        /         /         / 
+    │  ├─arm_v7a_cortex_a9                  0.32      0.32      0.32      0.32      0.32      0.32      1.28      1.28      1.92      1.28     10.22      7.99        /         /         / 
+    │  ├─arm_v8_cortex_a55                  1.41      1.41      0.35      0.35      0.35      0.35      1.41      1.41      1.41      1.41      7.78      7.78        /         /         / 
+    │  ├─arm_v8_cortex_a76                  0.90      0.90      0.90      0.90      0.90      0.90      0.90      0.90      1.36      1.36      4.93      4.63        /         /         / 
+    │  ├─arm_v9_cortex_x1                   0.90      0.90      0.90      0.90      0.90      0.90      0.90      0.90      1.36      1.36      4.78      4.63        /         /         / 
+    │  ├─arm_v9_cortex_x2                   0.90      0.90      0.90      0.90      0.90      0.90      0.90      0.90      1.36      1.36      4.78      4.63        /         /         / 
+    │  └─arm_v9_cortex_x3                   0.90      0.90      0.90      0.90      0.90      0.90      0.90      0.90      1.36      1.36      4.78      4.63        /         /         / 
+    └─x86                                   0.23      0.23      0.70      1.14      1.14      1.14      0.89      0.89      1.11      1.92      4.09      3.02     12.96     12.15     26.29
+       ├─amd                                0.17      0.17        /       1.45      1.45      1.45      0.88      0.88      0.88      0.59      3.26      2.04      7.89      6.93     15.71
+       │  ├─zen3_r7_5800x                   0.14      0.14        /       1.49      1.49      1.49      0.88      0.88      0.88      0.54      3.38      2.03      7.40      6.62     14.90
+       │  ├─zen4_r9_7900x                   0.13      0.13        /       1.40      1.40      1.40      0.89      0.89      0.89      0.64      3.19      1.91      6.99      6.25     14.13
+       │  └─zen5_r7_9800x3d                 0.29      0.29        /       1.47      1.47      1.47      0.88      0.88      0.88      0.59      3.23      2.20      9.51      8.03     18.42
+       └─intel                              0.30      0.30      0.90      0.90      0.90      0.90      0.90      0.90      1.39      6.28      5.12      4.47     21.27     21.31     43.97
+          ├─gen09_coffee_lake               0.29      0.29      0.88      0.88      0.88      0.88      0.88      0.88      1.47      6.16      5.03      4.39     21.16     20.74     43.37
+          ├─gen10_cannon_lake               0.29      0.29      0.88      0.88      0.88      0.88      0.88      0.88      1.47      6.16      5.03      4.39     21.16     20.74     43.37
+          └─gen11_tiger_lake                0.31      0.31      0.93      0.93      0.93      0.93      0.93      0.93      1.24      6.51      5.32      4.64     21.49     22.48     45.21
+```
 
-# 4. Known limitations
+# 5. Known limitations
 
 - currently any non-Python-built-in math operations are not counted (e.g. `numpy`)
 - not all Python built-in math operations are counted (e.g. `log`, `log10`, `exp`, `exp10`)

{counted_float-0.9.0 → counted_float-0.9.2}/counted_float/__init__.py

@@ -2,13 +2,14 @@ import counted_float.benchmarking as benchmarking
 import counted_float.config as config
 
 from ._core.counting import BuiltInData, CountedFloat, FlopCountingContext, PauseFlopCounting
-from ._core.counting.models import (
+from ._core.models import (
     FlopCounts,
     FlopsBenchmarkDurations,
     FlopsBenchmarkResults,
     FlopType,
     FlopWeights,
     FPUInstruction,
+    Quantiles,
     SystemInfo,
 )
 
@@ -24,5 +25,6 @@ __all__ = [
     "FlopWeights",
     "FPUInstruction",
     "PauseFlopCounting",
+    "Quantiles",
     "SystemInfo",
 ]

counted_float-0.9.2/counted_float/_core/_cli.py

@@ -0,0 +1,23 @@
+import click
+
+from counted_float import BuiltInData
+from counted_float.benchmarking import run_flops_benchmark
+
+
+# -------------------------------------------------------------------------
+#  Commands
+# -------------------------------------------------------------------------
+@click.group()
+def cli():
+    pass
+
+
+@cli.command(short_help="run flop benchmarks")
+def benchmark():
+    result = run_flops_benchmark()
+    result.show()
+
+
+@cli.command(short_help="show all built-in data")
+def show_data():
+    BuiltInData.show()

{counted_float-0.9.0 → counted_float-0.9.2}/counted_float/_core/benchmarking/__init__.py

@@ -1,6 +1,6 @@
 from importlib.metadata import version
 
-from counted_float._core.counting.models import FlopsBenchmarkResults
+from counted_float._core.models import FlopsBenchmarkResults
 
 from ._flops_benchmark_suite import FlopsBenchmarkSuite
 

{counted_float-0.9.0 → counted_float-0.9.2}/counted_float/_core/benchmarking/_flops_benchmark_suite.py

@@ -4,7 +4,7 @@ import numpy as np
 import psutil
 
 from counted_float._core.compatibility import is_numba_installed, numba
-from counted_float._core.counting.models import (
+from counted_float._core.models import (
     BenchmarkSettings,
     FlopsBenchmarkDurations,
     FlopsBenchmarkResults,
@@ -25,7 +25,7 @@ class FlopsBenchmarkSuite:
         array_size: int = 1000,
         n_runs_total: int = 30,
         n_runs_warmup: int = 10,
-        n_seconds_per_run_target: float = 0.5,
+        n_seconds_per_run_target: float = 0.01,
     ) -> FlopsBenchmarkResults:
         """
         Run entire flops benchmarking suite and return the results as a FlopsBenchmarkResults object.
@@ -49,7 +49,7 @@ class FlopsBenchmarkSuite:
             for flop_type, benchmark in benchmarks.items()
         }
 
-        # put results in appropriate format & return
+        # put results in appropriate format
         return FlopsBenchmarkResults(
             system_info=SystemInfo(
                 platform_processor=platform.processor(),
@@ -61,6 +61,7 @@ class FlopsBenchmarkSuite:
                 platform_python_compiler=platform.python_compiler(),
                 psutil_cpu_count_logical=psutil.cpu_count(logical=True),
                 psutil_cpu_count_physical=psutil.cpu_count(logical=False),
+                psutil_cpu_freq_mhz=int(psutil.cpu_freq().current),
             ),
             benchmark_settings=BenchmarkSettings(
                 array_size=array_size,

{counted_float-0.9.0 → counted_float-0.9.2}/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, single_operation=f"{size} flops")
+        super().__init__(name=name, single_operation=f"{size} iterations")
         self.size = size
         self.f = f
         self.n_operations = 0

{counted_float-0.9.0 → counted_float-0.9.2}/counted_float/_core/benchmarking/_micro_benchmark.py

@@ -1,7 +1,9 @@
 from abc import ABC, abstractmethod
 
-from ._models import MicroBenchmarkResult, SingleRunResult
-from ._time_utils import Timer, format_time_durations
+import psutil
+
+from counted_float._core.models import MicroBenchmarkResult, SingleRunResult
+from counted_float._core.utils import Timer, compute_latency, format_latency, format_time_duration
 
 
 # =================================================================================================
@@ -74,11 +76,21 @@ class MicroBenchmark(ABC):
             warmup_runs=warmup_runs,
             benchmark_runs=benchmark_runs,
         )
-        stats = benchmark_result.summary_stats()
-        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
+        # display duration estimates
+        stats = benchmark_result.summary_stats()
+        s_time_duration = format_time_duration(nsec=stats.q50)
+        s_latency = format_latency(n_cycles=compute_latency(nsec=stats.q50, cpu_freq_mhz=psutil.cpu_freq().current))
+        s_uncertainty = f"{50 * (stats.q75 - stats.q25) / stats.q50:4.1f}%"
+        print(f"   ({s_time_duration} = {s_latency}) ± {s_uncertainty}  /  {self.single_operation}")
+        #
+        # s_extra_info = self._compute_extra_result_info(benchmark_result)
+        # if s_extra_info:
+        #     print(f"   {s_time_duration} / {self.single_operation}     [{s_extra_info}]")
+        # else:
+        #     print(f"   {s_time_duration} / {self.single_operation}")
+
+        # return final result
         return benchmark_result
 
     def run_once(self, n_operations: int) -> SingleRunResult:

counted_float-0.9.2/counted_float/_core/benchmarking/_time_utils.py

@@ -0,0 +1 @@
+import time