counted-float 0.9.3__tar.gz → 0.9.4__tar.gz

{counted_float-0.9.3 → counted_float-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: counted-float
-Version: 0.9.3
+Version: 0.9.4
 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/CHANGELOG.md
@@ -11,6 +11,7 @@ Requires-Python: >=3.10
 Requires-Dist: backports-strenum>=1.3.1
 Requires-Dist: numpy>=1.20
 Requires-Dist: psutil>=5.0
+Requires-Dist: py-cpuinfo>=9.0.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Provides-Extra: cli
@@ -21,9 +22,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.9.3/badge-test-count.svg)
-![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.3/badge-coverage.svg)
-![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.3/splash.webp)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/v0.9.4/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.4/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.4/splash.webp)
 <!--END_SECTION:images-->
 
 # counted-float
@@ -164,7 +165,7 @@ rationale behind choice of data sources and methodology.
     FlopType.GTE        [x>=y]          :    1
     FlopType.LTE        [x<=y]          :    1
     FlopType.CMP_ZERO   [x>=0]          :    1
-    FlopType.RND        [round(x)]      :    1
+    FlopType.RND        [round(x,0)]    :    1
     FlopType.ADD        [x+y]           :    1
     FlopType.SUB        [x-y]           :    1
     FlopType.MUL        [x*y]           :    1
@@ -227,7 +228,7 @@ from counted_float.config import get_default_empirical_flop_weights, get_default
     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.RND        [round(x,0)]    :   0.96944
     FlopType.ADD        [x+y]           :   0.89296
     FlopType.SUB        [x-y]           :   1.14383
     FlopType.MUL        [x*y]           :   1.04677
@@ -258,7 +259,7 @@ from counted_float.config import get_builtin_flop_weights
     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.RND        [round(x,0)]    :   2.63592
     FlopType.ADD        [x+y]           :   0.86616
     FlopType.SUB        [x-y]           :   1.10411
     FlopType.MUL        [x*y]           :   1.16515
@@ -284,43 +285,43 @@ 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.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
+Running FLOPS benchmarks using counted-float 0.9.4 ...
+
+baseline                           : wwwwwwwwww....................   [ 177.53 ns ±  2.0% |   720 cpu cycles ±  2.0% ]  /  1000 iterations
+FlopType.ABS        [abs(x)]       : wwwwwwwwww....................   [ 286.71 ns ±  5.7% | 1.16K cpu cycles ±  5.7% ]  /  1000 iterations
+FlopType.CMP_ZERO   [x>=0]         : wwwwwwwwww....................   [ 294.71 ns ±  3.6% | 1.20K cpu cycles ±  3.6% ]  /  1000 iterations
+FlopType.RND        [round(x,0)]   : wwwwwwwwww....................   [ 291.74 ns ±  6.1% | 1.18K cpu cycles ±  6.1% ]  /  1000 iterations
+FlopType.MINUS      [-x]           : wwwwwwwwww....................   [ 291.81 ns ±  5.8% | 1.18K cpu cycles ±  5.8% ]  /  1000 iterations
+FlopType.EQUALS     [x==y]         : wwwwwwwwww....................   [ 297.70 ns ±  4.2% | 1.21K cpu cycles ±  4.2% ]  /  1000 iterations
+FlopType.GTE        [x>=y]         : wwwwwwwwww....................   [ 301.59 ns ±  3.2% | 1.22K cpu cycles ±  3.2% ]  /  1000 iterations
+FlopType.LTE        [x<=y]         : wwwwwwwwww....................   [ 295.77 ns ±  2.2% | 1.20K cpu cycles ±  2.2% ]  /  1000 iterations
+FlopType.ADD        [x+y]          : wwwwwwwwww....................   [ 289.49 ns ±  2.6% | 1.17K cpu cycles ±  2.6% ]  /  1000 iterations
+FlopType.SUB        [x-y]          : wwwwwwwwww....................   [ 289.85 ns ±  1.7% | 1.18K cpu cycles ±  1.7% ]  /  1000 iterations
+FlopType.MUL        [x*y]          : wwwwwwwwww....................   [ 305.46 ns ±  2.8% | 1.24K cpu cycles ±  2.8% ]  /  1000 iterations
+FlopType.SQRT       [sqrt(x)]      : wwwwwwwwww....................   [ 435.30 ns ±  0.5% | 1.77K cpu cycles ±  0.5% ]  /  1000 iterations
+FlopType.DIV        [x/y]          : wwwwwwwwww....................   [ 479.90 ns ±  1.2% | 1.95K cpu cycles ±  1.2% ]  /  1000 iterations
+FlopType.POW2       [2^x]          : wwwwwwwwww....................   [   1.78 µs ±  0.1% | 7.22K cpu cycles ±  0.1% ]  /  1000 iterations
+FlopType.LOG2       [log2(x)]      : wwwwwwwwww....................   [   2.17 µs ±  0.6% | 8.80K cpu cycles ±  0.6% ]  /  1000 iterations
+FlopType.POW        [x^y]          : wwwwwwwwww....................   [   6.14 µs ±  0.4% | 24.9K cpu cycles ±  0.4% ]  /  1000 iterations
 
 >>> results.flop_weights.show() 
 
 {
-    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
+    FlopType.ABS        [abs(x)]        :   0.97517
+    FlopType.MINUS      [-x]            :   1.02074
+    FlopType.EQUALS     [x==y]          :   1.07339
+    FlopType.GTE        [x>=y]          :   1.10812
+    FlopType.LTE        [x<=y]          :   1.05609
+    FlopType.CMP_ZERO   [x>=0]          :   1.04665
+    FlopType.RND        [round(x,0)]    :   1.02017
+    FlopType.ADD        [x+y]           :   1.00000
+    FlopType.SUB        [x-y]           :   1.00328
+    FlopType.MUL        [x*y]           :   1.14268
+    FlopType.DIV        [x/y]           :   2.70079
+    FlopType.SQRT       [sqrt(x)]       :   2.30238
+    FlopType.POW2       [2^x]           :  14.30722
+    FlopType.LOG2       [log2(x)]       :  17.79592
+    FlopType.POW        [x^y]           :  53.26393
 }
 ```
 
@@ -335,7 +336,7 @@ uv tool install git+https://github.com/bertpl/counted-float@develop[numba,cli]
 ```
 This installs the `counted_float` command-line tool, which can be used to e.g. run flops benchmarks.
 
-## 4.1 Running benchmarks
+## 4.1. Running benchmarks
 
 ```
 counted_float benchmark

{counted_float-0.9.3 → counted_float-0.9.4}/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.9.3/badge-test-count.svg)
-![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.3/badge-coverage.svg)
-![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.3/splash.webp)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/v0.9.4/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/v0.9.4/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/v0.9.4/splash.webp)
 <!--END_SECTION:images-->
 
 # counted-float
@@ -143,7 +143,7 @@ rationale behind choice of data sources and methodology.
     FlopType.GTE        [x>=y]          :    1
     FlopType.LTE        [x<=y]          :    1
     FlopType.CMP_ZERO   [x>=0]          :    1
-    FlopType.RND        [round(x)]      :    1
+    FlopType.RND        [round(x,0)]    :    1
     FlopType.ADD        [x+y]           :    1
     FlopType.SUB        [x-y]           :    1
     FlopType.MUL        [x*y]           :    1
@@ -206,7 +206,7 @@ from counted_float.config import get_default_empirical_flop_weights, get_default
     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.RND        [round(x,0)]    :   0.96944
     FlopType.ADD        [x+y]           :   0.89296
     FlopType.SUB        [x-y]           :   1.14383
     FlopType.MUL        [x*y]           :   1.04677
@@ -237,7 +237,7 @@ from counted_float.config import get_builtin_flop_weights
     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.RND        [round(x,0)]    :   2.63592
     FlopType.ADD        [x+y]           :   0.86616
     FlopType.SUB        [x-y]           :   1.10411
     FlopType.MUL        [x*y]           :   1.16515
@@ -263,43 +263,43 @@ 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.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
+Running FLOPS benchmarks using counted-float 0.9.4 ...
+
+baseline                           : wwwwwwwwww....................   [ 177.53 ns ±  2.0% |   720 cpu cycles ±  2.0% ]  /  1000 iterations
+FlopType.ABS        [abs(x)]       : wwwwwwwwww....................   [ 286.71 ns ±  5.7% | 1.16K cpu cycles ±  5.7% ]  /  1000 iterations
+FlopType.CMP_ZERO   [x>=0]         : wwwwwwwwww....................   [ 294.71 ns ±  3.6% | 1.20K cpu cycles ±  3.6% ]  /  1000 iterations
+FlopType.RND        [round(x,0)]   : wwwwwwwwww....................   [ 291.74 ns ±  6.1% | 1.18K cpu cycles ±  6.1% ]  /  1000 iterations
+FlopType.MINUS      [-x]           : wwwwwwwwww....................   [ 291.81 ns ±  5.8% | 1.18K cpu cycles ±  5.8% ]  /  1000 iterations
+FlopType.EQUALS     [x==y]         : wwwwwwwwww....................   [ 297.70 ns ±  4.2% | 1.21K cpu cycles ±  4.2% ]  /  1000 iterations
+FlopType.GTE        [x>=y]         : wwwwwwwwww....................   [ 301.59 ns ±  3.2% | 1.22K cpu cycles ±  3.2% ]  /  1000 iterations
+FlopType.LTE        [x<=y]         : wwwwwwwwww....................   [ 295.77 ns ±  2.2% | 1.20K cpu cycles ±  2.2% ]  /  1000 iterations
+FlopType.ADD        [x+y]          : wwwwwwwwww....................   [ 289.49 ns ±  2.6% | 1.17K cpu cycles ±  2.6% ]  /  1000 iterations
+FlopType.SUB        [x-y]          : wwwwwwwwww....................   [ 289.85 ns ±  1.7% | 1.18K cpu cycles ±  1.7% ]  /  1000 iterations
+FlopType.MUL        [x*y]          : wwwwwwwwww....................   [ 305.46 ns ±  2.8% | 1.24K cpu cycles ±  2.8% ]  /  1000 iterations
+FlopType.SQRT       [sqrt(x)]      : wwwwwwwwww....................   [ 435.30 ns ±  0.5% | 1.77K cpu cycles ±  0.5% ]  /  1000 iterations
+FlopType.DIV        [x/y]          : wwwwwwwwww....................   [ 479.90 ns ±  1.2% | 1.95K cpu cycles ±  1.2% ]  /  1000 iterations
+FlopType.POW2       [2^x]          : wwwwwwwwww....................   [   1.78 µs ±  0.1% | 7.22K cpu cycles ±  0.1% ]  /  1000 iterations
+FlopType.LOG2       [log2(x)]      : wwwwwwwwww....................   [   2.17 µs ±  0.6% | 8.80K cpu cycles ±  0.6% ]  /  1000 iterations
+FlopType.POW        [x^y]          : wwwwwwwwww....................   [   6.14 µs ±  0.4% | 24.9K cpu cycles ±  0.4% ]  /  1000 iterations
 
 >>> results.flop_weights.show() 
 
 {
-    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
+    FlopType.ABS        [abs(x)]        :   0.97517
+    FlopType.MINUS      [-x]            :   1.02074
+    FlopType.EQUALS     [x==y]          :   1.07339
+    FlopType.GTE        [x>=y]          :   1.10812
+    FlopType.LTE        [x<=y]          :   1.05609
+    FlopType.CMP_ZERO   [x>=0]          :   1.04665
+    FlopType.RND        [round(x,0)]    :   1.02017
+    FlopType.ADD        [x+y]           :   1.00000
+    FlopType.SUB        [x-y]           :   1.00328
+    FlopType.MUL        [x*y]           :   1.14268
+    FlopType.DIV        [x/y]           :   2.70079
+    FlopType.SQRT       [sqrt(x)]       :   2.30238
+    FlopType.POW2       [2^x]           :  14.30722
+    FlopType.LOG2       [log2(x)]       :  17.79592
+    FlopType.POW        [x^y]           :  53.26393
 }
 ```
 
@@ -314,7 +314,7 @@ uv tool install git+https://github.com/bertpl/counted-float@develop[numba,cli]
 ```
 This installs the `counted_float` command-line tool, which can be used to e.g. run flops benchmarks.
 
-## 4.1 Running benchmarks
+## 4.1. Running benchmarks
 
 ```
 counted_float benchmark

{counted_float-0.9.3 → counted_float-0.9.4}/counted_float/__init__.py

@@ -5,7 +5,7 @@ from ._core.counting import BuiltInData, CountedFloat, FlopCountingContext, Paus
 from ._core.models import (
     FlopCounts,
     FlopsBenchmarkDurations,
-    FlopsBenchmarkResults,
+    FlopsBenchmarkResults_V1,
     FlopType,
     FlopWeights,
     Quantiles,
@@ -19,7 +19,7 @@ __all__ = [
     "FlopCountingContext",
     "FlopCounts",
     "FlopsBenchmarkDurations",
-    "FlopsBenchmarkResults",
+    "FlopsBenchmarkResults_V1",
     "FlopType",
     "FlopWeights",
     "PauseFlopCounting",

{counted_float-0.9.3 → counted_float-0.9.4}/counted_float/_core/benchmarking/__init__.py

@@ -1,11 +1,9 @@
 from importlib.metadata import version
 
-from counted_float._core.models import FlopsBenchmarkResults
+from .flops import FlopsBenchmarkResults_V2, FlopsBenchmarkSuite
 
-from ._flops_benchmark_suite import FlopsBenchmarkSuite
 
-
-def run_flops_benchmark() -> FlopsBenchmarkResults:
+def run_flops_benchmark() -> FlopsBenchmarkResults_V2:
     """Run the flops benchmark suite with default settings returns a FlopsBenchmarkResults object."""
 
     print()

counted_float-0.9.4/counted_float/_core/benchmarking/flops/__init__.py

@@ -0,0 +1,3 @@
+from ._array_generator import ArrayGenerator
+from ._flops_benchmark_suite import FlopsBenchmarkResults_V2, FlopsBenchmarkSuite
+from ._flops_micro_benchmark import FlopsMicroBenchmark

counted_float-0.9.4/counted_float/_core/benchmarking/flops/_array_generator.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import random
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+
+# =================================================================================================
+#  Base class
+# =================================================================================================
+class ArrayGenerator(ABC):
+    # -------------------------------------------------------------------------
+    #  API
+    # -------------------------------------------------------------------------
+    @abstractmethod
+    def new_array(self, size: int) -> np.ndarray:
+        """Generates random 1D numpy array of requested size"""
+        raise NotImplementedError
+
+    # -------------------------------------------------------------------------
+    #  Factory Methods
+    # -------------------------------------------------------------------------
+    @classmethod
+    def lin_range(cls, min_value: float, max_value: float) -> ArrayGenerator:
+        return ArrayGeneratorLinear(min_value, max_value)
+
+    @classmethod
+    def log_range(cls, min_value: float, max_value: float) -> ArrayGenerator:
+        return ArrayGeneratorLog(min_value, max_value)
+
+
+# =================================================================================================
+#  Implementations
+# =================================================================================================
+class ArrayGeneratorLinear(ArrayGenerator):
+    def __init__(self, min_value: float, max_value: float):
+        """Array generator, where values are in interval [min_value, max_value] with avg. equal to mid-point."""
+        self.min_value = min_value
+        self.max_value = max_value
+
+    def new_array(self, size: int) -> np.ndarray:
+        uniform_values = 0.5 * (1.0 + _random_balanced_values(size))  # uniform random values in [0,1]
+        return self.min_value + uniform_values * (self.max_value - self.min_value)
+
+
+class ArrayGeneratorLog(ArrayGenerator):
+    def __init__(self, min_value: float, max_value: float):
+        """Array generator, where values are in interval [min_value, max_value] with geomean of values eq. to geo-mid"""
+        self.min_value = min_value
+        self.max_value = max_value
+
+    def new_array(self, size: int) -> np.ndarray:
+        uniform_values = 0.5 * (1.0 + _random_balanced_values(size))  # uniform random values in [0,1]
+        return self.min_value * (self.max_value / self.min_value) ** uniform_values
+
+
+# =================================================================================================
+#  Helpers
+# =================================================================================================
+def _random_balanced_values(size: int) -> np.ndarray:
+    """
+    Returns random values in [-1,1], such that...
+      - mean value == 0.0
+      - cumulative sum of any arbitrary first n values also lies within [-1,1]
+    """
+    cumsum = 0.0
+    lst = []
+    for i in range(size - 1):
+        next_min_value = max(-1.0, -1.0 - cumsum)
+        next_max_value = min(1.0, 1.0 - cumsum)
+        next_value = random.uniform(next_min_value, next_max_value)
+        lst.append(next_value)
+        cumsum += next_value
+    lst.append(-cumsum)
+    return np.array(lst)