counted-float 1.0.3__tar.gz → 1.0.4__tar.gz

{counted_float-1.0.3 → counted_float-1.0.4}/.gitignore

@@ -33,4 +33,7 @@ Thumbs.db
 .vscode
 
 # other local files
-.local
+.local
+# Only working_docs/README.md is committed; everything else here stays out of git.
+working_docs/*
+!working_docs/README.md

{counted_float-1.0.3 → counted_float-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: counted-float
-Version: 1.0.3
+Version: 1.0.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/main/CHANGELOG.md
@@ -20,9 +20,9 @@ Requires-Dist: numba>=0.50; extra == 'numba'
 Description-Content-Type: text/markdown
 
 ![shields.io-python-versions](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
-![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.3/badge-test-count.svg)
-![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.3/badge-coverage.svg)
-![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.3/splash.webp)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.4/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.4/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.4/splash.webp)
 
 # counted-float
 
@@ -90,7 +90,33 @@ s = math.sqrt(cf1)  # s = CountedFloat(0.9)
 is_float = isinstance(s, float)  # True
 ```
 
-## 2.2. FLOP counting context managers
+### The counting model: what gets counted and why
+
+The counting model is a contract with two sides:
+
+- **Your side:** wrap every *runtime input* of the algorithm you want to measure in `CountedFloat`
+  at its boundary. Contagion does the rest — everything derived from those inputs stays counted
+  automatically.
+- **The library's side:** count every FLOP that a compiled (C/Rust/...) port of your algorithm
+  would execute *on data derived from those inputs*.
+
+From this contract follows a clean rule for everything else: **constants are free.** Any plain
+float encountered mid-computation is, by the contract, not an input — so it must be a constant of
+the algorithm (a literal, a coefficient, a tolerance), and operations purely among constants are
+work a compiled port would fold at compile time or precompute. This is why e.g. `math.sqrt(3)`
+counts nothing: the port ships `sqrt(3)` as a precomputed constant.
+
+The library detects constants through two mechanisms, applying the same rule:
+
+- **Unwrapped values** (plain floats): constants by the wrapping contract, as above.
+- **`int` operands**: evidence of a *hardcoded* constant — ints don't fall out of floating-point
+  computations, so an int operand almost certainly appears literally in your source. This enables
+  counting the strength reductions a compiled port would apply: `x**2` counts MUL (i.e. `x*x`),
+  `2**x` counts EXP2, `math.log(x, 10)` counts LOG10 — while `x**2.0`, with a float that *could*
+  be a runtime value, conservatively counts a generic POW.
+
+The flip side: an unwrapped runtime input is invisible to the counter — that is a wrapping error
+at your algorithm's boundary, not something the library can detect. When in doubt, wrap.
 
 Once we use the `CountedFloat` class, we can use the available context managers to count the number of
 flops performed by `CountedFloat` objects.
@@ -636,21 +662,21 @@ This appendix provides detailed information about how each floating-point operat
 - Relevant CPU instructions
   - **ARM:** (software)
   - **x86:** (software)
-- **Counted Python operations:** `math.log(x)` for `CountedFloat`
+- **Counted Python operations:** `math.log(x)` for `CountedFloat`; `math.log(x, base)` for `CountedFloat` decomposes per the constant-detection heuristic (int base 2/10 -> LOG2/LOG10; other int base -> LOG+MUL; float base -> LOG per counted operand + DIV)
 - **Not counted:** `numpy.log`, log on non-CountedFloat
 
 ### FlopType.LOG2 (`log2(x)`)
 - Relevant CPU instructions
   - **ARM:** (software)
   - **x86:** (software)
-- **Counted Python operations:** `math.log2(x)` for `CountedFloat`
+- **Counted Python operations:** `math.log2(x)` for `CountedFloat`; `math.log(x, 2)` (int base) for `CountedFloat`
 - **Not counted:** `numpy.log2`, log2 on non-CountedFloat
 
 ### FlopType.LOG10 (`log10(x)`)
 - Relevant CPU instructions
   - **ARM:** (software)
   - **x86:** (software)
-- **Counted Python operations:** `math.log10(x)` for `CountedFloat`
+- **Counted Python operations:** `math.log10(x)` for `CountedFloat`; `math.log(x, 10)` (int base) for `CountedFloat`
 - **Not counted:** `numpy.log10`, log10 on non-CountedFloat
 
 ### FlopType.POW (`x^y`)

{counted_float-1.0.3 → counted_float-1.0.4}/README.md

@@ -1,7 +1,7 @@
 ![shields.io-python-versions](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
-![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.3/badge-test-count.svg)
-![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.3/badge-coverage.svg)
-![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.3/splash.webp)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.4/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.4/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/release/v1.0.4/splash.webp)
 
 # counted-float
 
@@ -69,7 +69,33 @@ s = math.sqrt(cf1)  # s = CountedFloat(0.9)
 is_float = isinstance(s, float)  # True
 ```
 
-## 2.2. FLOP counting context managers
+### The counting model: what gets counted and why
+
+The counting model is a contract with two sides:
+
+- **Your side:** wrap every *runtime input* of the algorithm you want to measure in `CountedFloat`
+  at its boundary. Contagion does the rest — everything derived from those inputs stays counted
+  automatically.
+- **The library's side:** count every FLOP that a compiled (C/Rust/...) port of your algorithm
+  would execute *on data derived from those inputs*.
+
+From this contract follows a clean rule for everything else: **constants are free.** Any plain
+float encountered mid-computation is, by the contract, not an input — so it must be a constant of
+the algorithm (a literal, a coefficient, a tolerance), and operations purely among constants are
+work a compiled port would fold at compile time or precompute. This is why e.g. `math.sqrt(3)`
+counts nothing: the port ships `sqrt(3)` as a precomputed constant.
+
+The library detects constants through two mechanisms, applying the same rule:
+
+- **Unwrapped values** (plain floats): constants by the wrapping contract, as above.
+- **`int` operands**: evidence of a *hardcoded* constant — ints don't fall out of floating-point
+  computations, so an int operand almost certainly appears literally in your source. This enables
+  counting the strength reductions a compiled port would apply: `x**2` counts MUL (i.e. `x*x`),
+  `2**x` counts EXP2, `math.log(x, 10)` counts LOG10 — while `x**2.0`, with a float that *could*
+  be a runtime value, conservatively counts a generic POW.
+
+The flip side: an unwrapped runtime input is invisible to the counter — that is a wrapping error
+at your algorithm's boundary, not something the library can detect. When in doubt, wrap.
 
 Once we use the `CountedFloat` class, we can use the available context managers to count the number of
 flops performed by `CountedFloat` objects.
@@ -615,21 +641,21 @@ This appendix provides detailed information about how each floating-point operat
 - Relevant CPU instructions
   - **ARM:** (software)
   - **x86:** (software)
-- **Counted Python operations:** `math.log(x)` for `CountedFloat`
+- **Counted Python operations:** `math.log(x)` for `CountedFloat`; `math.log(x, base)` for `CountedFloat` decomposes per the constant-detection heuristic (int base 2/10 -> LOG2/LOG10; other int base -> LOG+MUL; float base -> LOG per counted operand + DIV)
 - **Not counted:** `numpy.log`, log on non-CountedFloat
 
 ### FlopType.LOG2 (`log2(x)`)
 - Relevant CPU instructions
   - **ARM:** (software)
   - **x86:** (software)
-- **Counted Python operations:** `math.log2(x)` for `CountedFloat`
+- **Counted Python operations:** `math.log2(x)` for `CountedFloat`; `math.log(x, 2)` (int base) for `CountedFloat`
 - **Not counted:** `numpy.log2`, log2 on non-CountedFloat
 
 ### FlopType.LOG10 (`log10(x)`)
 - Relevant CPU instructions
   - **ARM:** (software)
   - **x86:** (software)
-- **Counted Python operations:** `math.log10(x)` for `CountedFloat`
+- **Counted Python operations:** `math.log10(x)` for `CountedFloat`; `math.log(x, 10)` (int base) for `CountedFloat`
 - **Not counted:** `numpy.log10`, log10 on non-CountedFloat
 
 ### FlopType.POW (`x^y`)

{counted_float-1.0.3 → counted_float-1.0.4}/counted_float/_core/counting/_counted_float.py

@@ -182,7 +182,15 @@ class CountedFloat(float):
         return CountedFloat(super().__rtruediv__(other))
 
     def __pow__(self, other) -> CountedFloat:
-        """x**other"""
+        """
+        x**other
+
+        Counting heuristic: an `int` operand is taken as evidence of a hardcoded constant in the
+        source (ints don't fall out of floating-point computations), so `x**2` counts as MUL —
+        the strength reduction (x*x) a compiled port would apply. A float operand may just as well
+        be a runtime variable that happens to hold that value, where a port would compile a
+        generic pow, so `x**2.0` counts as POW.
+        """
         if isinstance(other, int) and other == 2:
             GLOBAL_COUNTER.incr_mul()  # x^2 = x*x
         else:
@@ -192,7 +200,14 @@ class CountedFloat(float):
         return CountedFloat(super().__pow__(other))
 
     def __rpow__(self, other) -> CountedFloat:
-        """other**x"""
+        """
+        other**x
+
+        Same constant-detection heuristic as __pow__, applied to the base: an `int` base 2 or 10
+        is taken as a hardcoded constant, counting as EXP2 / EXP10 (the strength reduction a
+        compiled port would apply); a float base may be a runtime variable, so it counts as
+        generic POW.
+        """
         if isinstance(other, int) and other == 2:
             GLOBAL_COUNTER.incr_exp2()
         elif isinstance(other, int) and other == 10:
@@ -214,10 +229,15 @@ original_math_log2 = math.log2
 original_math_log10 = math.log10
 original_math_exp = math.exp
 original_math_exp2 = math.exp2
+original_math_pow = math.pow
 original_math_sin = math.sin
 original_math_cos = math.cos
 original_math_tan = math.tan
 
+# sentinel for math_log's optional base argument; the stdlib signature is math.log(x[, base]),
+# where omitting base is not the same as passing any real value (and None is rejected)
+_NO_BASE = object()
+
 
 def math_sqrt(x: float) -> float | CountedFloat:
     if isinstance(x, CountedFloat):
@@ -235,12 +255,50 @@ def math_cbrt(x: float) -> float | CountedFloat:
         return original_math_cbrt(x)
 
 
-def math_log(x: float) -> float | CountedFloat:
-    if isinstance(x, CountedFloat):
-        GLOBAL_COUNTER.incr_log()
-        return CountedFloat(original_math_log(x))
+def math_log(x: float, base=_NO_BASE) -> float | CountedFloat:
+    """
+    Patched math.log: stdlib contract (optional base), with flop classification for the base
+    following the same constant-detection heuristic as CountedFloat.__pow__ / __rpow__
+    (int operand = hardcoded constant in the source):
+      - base omitted      -> LOG
+      - base int 2 / 10   -> LOG2 / LOG10 (a compiled port calls log2/log10 directly)
+      - base other int    -> LOG + MUL (a port computes log(x) * C, with C = 1/log(base) folded
+                             at compile time)
+      - base float        -> a port computes log(x)/log(base): LOG per CountedFloat operand + DIV
+    As everywhere in the counting model, only operations touching CountedFloat values are counted:
+    any runtime input to the counted algorithm should itself be a CountedFloat; whatever remains a
+    plain float is by definition not part of the core algorithm and/or precomputable.
+    """
+    if base is _NO_BASE:
+        if isinstance(x, CountedFloat):
+            GLOBAL_COUNTER.incr_log()
+            return CountedFloat(original_math_log(x))
+        else:
+            return original_math_log(x)
     else:
-        return original_math_log(x)
+        # computed first: raises per stdlib contract before anything is counted
+        result = original_math_log(x, base)
+        if isinstance(base, int) and base == 2:
+            if isinstance(x, CountedFloat):
+                GLOBAL_COUNTER.incr_log2()
+        elif isinstance(base, int) and base == 10:
+            if isinstance(x, CountedFloat):
+                GLOBAL_COUNTER.incr_log10()
+        elif isinstance(base, int):
+            if isinstance(x, CountedFloat):
+                GLOBAL_COUNTER.incr_log()
+                GLOBAL_COUNTER.incr_mul()
+        else:
+            if isinstance(x, CountedFloat):
+                GLOBAL_COUNTER.incr_log()
+            if isinstance(base, CountedFloat):
+                GLOBAL_COUNTER.incr_log()
+            if isinstance(x, CountedFloat) or isinstance(base, CountedFloat):
+                GLOBAL_COUNTER.incr_div()
+        if isinstance(x, CountedFloat) or isinstance(base, CountedFloat):
+            return CountedFloat(result)
+        else:
+            return result
 
 
 def math_log2(x: float) -> float | CountedFloat:
@@ -276,7 +334,34 @@ def math_exp2(x: float) -> float | CountedFloat:
 
 
 def math_pow(x: float, y: float) -> float | CountedFloat:
-    return x**y
+    """
+    Patched math.pow: stdlib contract (always-float result, ValueError on domain errors), with
+    flop classification identical to the x**y form — including the constant-detection heuristic
+    documented on CountedFloat.__pow__ / __rpow__ (int operand = hardcoded constant).
+    """
+    if isinstance(x, CountedFloat) or isinstance(y, CountedFloat):
+        # computed first: math.pow raises ValueError on domain errors (e.g. negative base with
+        # fractional exponent) and then nothing should be counted
+        result = original_math_pow(x, y)
+        if isinstance(x, CountedFloat):
+            if isinstance(y, int) and y == 2:
+                GLOBAL_COUNTER.incr_mul()  # x^2 = x*x
+            else:
+                if isinstance(y, int):
+                    GLOBAL_COUNTER.incr_i2f()
+                GLOBAL_COUNTER.incr_pow()
+        else:
+            if isinstance(x, int) and x == 2:
+                GLOBAL_COUNTER.incr_exp2()
+            elif isinstance(x, int) and x == 10:
+                GLOBAL_COUNTER.incr_exp10()
+            else:
+                if isinstance(x, int):
+                    GLOBAL_COUNTER.incr_i2f()
+                GLOBAL_COUNTER.incr_pow()
+        return CountedFloat(result)
+    else:
+        return original_math_pow(x, y)
 
 
 def math_sin(x: float) -> float | CountedFloat:

{counted_float-1.0.3 → counted_float-1.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "counted-float"
-version = "1.0.3"
+version = "1.0.4"
 description = "Count floating-point operations in Python code & benchmark relative flop costs."
 readme = "README.md"
 requires-python = ">=3.11"