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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: counted-float
-Version: 1.0.4
+Version: 1.1.0
 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.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)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/develop/v1.1.0/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/develop/v1.1.0/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/develop/v1.1.0/splash.webp)
 
 # counted-float
 
@@ -61,10 +61,12 @@ The `CountedFloat` class is a subclass of `float` and is "contagious", meaning t
 ensure results of math operations where at least one operand is a `CountedFloat` will also be a `CountedFloat`.
 This way we ensure flop counting is a 'closed system'.
 
-On top of this, we monkey-patch the `math` module to ensure that all math operations
-that require counting (`sqrt`, `log2`, `pow`, ...) are also instrumented.
+On top of this, `math` module functions that require counting (`sqrt`, `log2`, `pow`, ...) are
+also instrumented: while a `FlopCountingContext` is active (see below), they are temporarily
+replaced by counting equivalents. Outside such a context — including at plain `import` time —
+the `math` module is left completely untouched.
 
-**Example 1**:
+**Example**:
 
 ```python
 from counted_float import CountedFloat
@@ -78,18 +80,6 @@ is_float_1 = isinstance(cf, float)  # True
 is_float_2 = isinstance(result, float)  # True
 ```
 
-**Example 2**:
-
-```python
-import math
-from counted_float import CountedFloat
-
-cf1 = CountedFloat(0.81)
-
-s = math.sqrt(cf1)  # s = CountedFloat(0.9)
-is_float = isinstance(s, float)  # True
-```
-
 ### The counting model: what gets counted and why
 
 The counting model is a contract with two sides:
@@ -118,6 +108,13 @@ The library detects constants through two mechanisms, applying the same rule:
 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.
 
+One more consequence of the context-scoped `math` patching: `math.*` calls participate in
+counting (and in contagion) only while a `FlopCountingContext` is active. Operator-based
+contagion (`+`, `*`, `**`, ...) works everywhere, but counts are meant to be read through a
+context — so the practical rule is simply: run your measured algorithm inside one.
+
+## 2.2. FLOP counting context managers
+
 Once we use the `CountedFloat` class, we can use the available context managers to count the number of
 flops performed by `CountedFloat` objects.
 
@@ -136,7 +133,24 @@ counts = ctx.flop_counts()   # {FlopType.MUL: 1, FlopType.ADD: 1}
 counts.total_count()         # 2
 ```
 
-**Example 2**:  _pause counting 1_
+**Example 2**:  _math module functions_
+
+```python
+import math
+from counted_float import CountedFloat, FlopCountingContext
+
+cf1 = CountedFloat(0.81)
+
+with FlopCountingContext() as ctx:
+    s = math.sqrt(cf1)  # s = CountedFloat(0.9)
+
+counts = ctx.flop_counts()   # {FlopType.SQRT: 1}
+```
+
+Note that `math.*` functions are only instrumented *inside* the context: outside it,
+`math.sqrt(cf1)` returns a plain `float` and counts nothing.
+
+**Example 3**:  _pause counting 1_
 
 ```python
 from counted_float import CountedFloat, FlopCountingContext
@@ -155,7 +169,7 @@ counts = ctx.flop_counts()   # {FlopType.MUL: 1, FlopType.SUB: 1}
 counts.total_count()         # 2
 ```
 
-**Example 3**:  _pause counting 2_
+**Example 4**:  _pause counting 2_
 
 ```python
 from counted_float import CountedFloat, FlopCountingContext, PauseFlopCounting
@@ -546,7 +560,7 @@ CountedFloat is 37.3x slower than float
  
 # Appendix A - Flop counting / analysis details
 
-This appendix provides detailed information about how each floating-point operation (FLOP) type is counted and analyzed in the `counted-float` package. For each flop type, you will find:
+This appendix provides detailed information about how each floating-point operation (FLOP) type is counted and analyzed in the `counted-float` package. All `math.*` entries below assume an active `FlopCountingContext` (outside one, the `math` module is not instrumented). For each flop type, you will find:
 - Relevant scalar instructions for ARM (v8+) and x86 (SSE2+)
 - Python operations that are counted for this flop type
 - Python operations that are *not* counted for this flop type

{counted_float-1.0.4 → counted_float-1.1.0}/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.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)
+![genbadge-test-count](https://bertpl.github.io/counted-float/version_artifacts/develop/v1.1.0/badge-test-count.svg)
+![genbadge-test-coverage](https://bertpl.github.io/counted-float/version_artifacts/develop/v1.1.0/badge-coverage.svg)
+![counted_float logo](https://bertpl.github.io/counted-float/version_artifacts/develop/v1.1.0/splash.webp)
 
 # counted-float
 
@@ -40,10 +40,12 @@ The `CountedFloat` class is a subclass of `float` and is "contagious", meaning t
 ensure results of math operations where at least one operand is a `CountedFloat` will also be a `CountedFloat`.
 This way we ensure flop counting is a 'closed system'.
 
-On top of this, we monkey-patch the `math` module to ensure that all math operations
-that require counting (`sqrt`, `log2`, `pow`, ...) are also instrumented.
+On top of this, `math` module functions that require counting (`sqrt`, `log2`, `pow`, ...) are
+also instrumented: while a `FlopCountingContext` is active (see below), they are temporarily
+replaced by counting equivalents. Outside such a context — including at plain `import` time —
+the `math` module is left completely untouched.
 
-**Example 1**:
+**Example**:
 
 ```python
 from counted_float import CountedFloat
@@ -57,18 +59,6 @@ is_float_1 = isinstance(cf, float)  # True
 is_float_2 = isinstance(result, float)  # True
 ```
 
-**Example 2**:
-
-```python
-import math
-from counted_float import CountedFloat
-
-cf1 = CountedFloat(0.81)
-
-s = math.sqrt(cf1)  # s = CountedFloat(0.9)
-is_float = isinstance(s, float)  # True
-```
-
 ### The counting model: what gets counted and why
 
 The counting model is a contract with two sides:
@@ -97,6 +87,13 @@ The library detects constants through two mechanisms, applying the same rule:
 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.
 
+One more consequence of the context-scoped `math` patching: `math.*` calls participate in
+counting (and in contagion) only while a `FlopCountingContext` is active. Operator-based
+contagion (`+`, `*`, `**`, ...) works everywhere, but counts are meant to be read through a
+context — so the practical rule is simply: run your measured algorithm inside one.
+
+## 2.2. FLOP counting context managers
+
 Once we use the `CountedFloat` class, we can use the available context managers to count the number of
 flops performed by `CountedFloat` objects.
 
@@ -115,7 +112,24 @@ counts = ctx.flop_counts()   # {FlopType.MUL: 1, FlopType.ADD: 1}
 counts.total_count()         # 2
 ```
 
-**Example 2**:  _pause counting 1_
+**Example 2**:  _math module functions_
+
+```python
+import math
+from counted_float import CountedFloat, FlopCountingContext
+
+cf1 = CountedFloat(0.81)
+
+with FlopCountingContext() as ctx:
+    s = math.sqrt(cf1)  # s = CountedFloat(0.9)
+
+counts = ctx.flop_counts()   # {FlopType.SQRT: 1}
+```
+
+Note that `math.*` functions are only instrumented *inside* the context: outside it,
+`math.sqrt(cf1)` returns a plain `float` and counts nothing.
+
+**Example 3**:  _pause counting 1_
 
 ```python
 from counted_float import CountedFloat, FlopCountingContext
@@ -134,7 +148,7 @@ counts = ctx.flop_counts()   # {FlopType.MUL: 1, FlopType.SUB: 1}
 counts.total_count()         # 2
 ```
 
-**Example 3**:  _pause counting 2_
+**Example 4**:  _pause counting 2_
 
 ```python
 from counted_float import CountedFloat, FlopCountingContext, PauseFlopCounting
@@ -525,7 +539,7 @@ CountedFloat is 37.3x slower than float
  
 # Appendix A - Flop counting / analysis details
 
-This appendix provides detailed information about how each floating-point operation (FLOP) type is counted and analyzed in the `counted-float` package. For each flop type, you will find:
+This appendix provides detailed information about how each floating-point operation (FLOP) type is counted and analyzed in the `counted-float` package. All `math.*` entries below assume an active `FlopCountingContext` (outside one, the `math` module is not instrumented). For each flop type, you will find:
 - Relevant scalar instructions for ARM (v8+) and x86 (SSE2+)
 - Python operations that are counted for this flop type
 - Python operations that are *not* counted for this flop type

{counted_float-1.0.4 → counted_float-1.1.0}/counted_float/_core/benchmarking/counted_float/_counted_float_benchmark.py

@@ -42,6 +42,8 @@ class BenchmarkFloat(MicroBenchmark):
             # using standard float() arithmetic
             a = -1e50
             b = 1e50
+            # NOTE: fa/fb are never read (the loop re-evaluates fmid instead); they are kept
+            #       on purpose so the kernel mimics a realistic bisection workload
             fa = _zero_function(a)
             fb = _zero_function(b)
             while b - a > 1e-15:
@@ -70,6 +72,8 @@ class BenchmarkCountedFloat(MicroBenchmark):
             # which will make sure all the remaining operations are also executed using CountedFloat arithmetic
             a = CountedFloat(-1e50)
             b = CountedFloat(1e50)
+            # NOTE: fa/fb are never read (the loop re-evaluates fmid instead); they are kept
+            #       on purpose so the kernel mimics a realistic bisection workload
             fa = _zero_function(a)
             fb = _zero_function(b)
             while b - a > 1e-15:

{counted_float-1.0.4 → counted_float-1.1.0}/counted_float/_core/counting/_builtin_data.py

@@ -40,7 +40,7 @@ class BuiltInData:
             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)
+            return _compute_nested_average_flop_weights(nested_flop_weights_dict)
 
     @classmethod
     def get_flop_weights_dict(cls, key_filter: str = "") -> dict[str, FlopWeights]:
@@ -86,11 +86,11 @@ class BuiltInData:
 # =================================================================================================
 #  Utilities
 # =================================================================================================
-def _computed_nested_average_flop_weights(nested_flop_weights_dict: dict[str, dict | FlopWeights]) -> FlopWeights:
+def _compute_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)
+            nested_flop_weights_dict[key] = _compute_nested_average_flop_weights(value)
 
     # now we can average all FlopWeights instances
     return FlopWeights.as_geo_mean(list(nested_flop_weights_dict.values()))
@@ -121,10 +121,6 @@ def _load_json_files_as_dict(resource_root) -> dict[str, str]:
                   '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():
@@ -211,6 +207,7 @@ class FlopWeightsTreeView:
                         child.lst_is_leaf,
                         child.lst_tree_str,
                         child.lst_flop_weights,
+                        strict=True,
                     )
                 ):
                     self.lst_indent.append(1 + indent)
@@ -238,7 +235,6 @@ class FlopWeightsTreeView:
         tree_width = 5 + max([len(line) for line in self.lst_tree_str])
         col_width = 10
         sorted_flop_types = self.lst_flop_weights[0].get_sorted_flop_types()
-        max_indent = max(self.lst_indent)
 
         n_cols_per_block = max(1, int((console_width - tree_width) / col_width))
         flop_types_per_block = [
@@ -260,6 +256,7 @@ class FlopWeightsTreeView:
                 self.lst_is_leaf,
                 self.lst_tree_str,
                 self.lst_flop_weights,
+                strict=True,
             ):
                 line = tree_str.ljust(tree_width)
                 for flop_type in flop_types:

{counted_float-1.0.4 → counted_float-1.1.0}/counted_float/_core/counting/_context_managers.py

@@ -4,6 +4,7 @@ as well as providing .pause() and .resume() methods to control flop counting.
 """
 
 from counted_float._core.counting._global_counter import GLOBAL_COUNTER
+from counted_float._core.counting._math_patching import apply_math_patches, remove_math_patches
 from counted_float._core.models import FlopCounts
 
 
@@ -15,10 +16,6 @@ class FlopCountingContext:
     Context manager that can be used to count FLOP operations in a block of code.  Only floating-point
     operations of CountedFloat objects are counted.  So make sure all math uses this type.
 
-    Flops need to be registered by either of the following:
-      - calls to register_flops(...)
-      - using CountedFloat() objects in the computations
-
     LIMITATIONS:
         - this context manager is not thread-safe
         - not _all_ floating-point operations are counted, see the docs for more details.
@@ -71,11 +68,15 @@ class FlopCountingContext:
     #  Context manager interface
     # -------------------------------------------------------------------------
     def __enter__(self):
+        # patching the math module is tied to the with-block lifetime (not to pause()/resume(),
+        # which only control whether counts are registered)
+        apply_math_patches()
         self.resume()
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.pause()
+        remove_math_patches()
 
 
 # =================================================================================================

counted_float-1.1.0/counted_float/_core/counting/_counted_float.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from ._global_counter import GLOBAL_COUNTER
+
+
+class CountedFloat(float):
+    # -------------------------------------------------------------------------
+    #  CONSTRUCTOR
+    # -------------------------------------------------------------------------
+    def __new__(cls, value: float | int):
+        if isinstance(value, int):
+            GLOBAL_COUNTER.incr_i2f()
+        self = super().__new__(cls, float(value))
+        return self
+
+    def __str__(self):
+        return self.__repr__()
+
+    def __repr__(self):
+        return f"CountedFloat({super().__repr__()})"
+
+    def __hash__(self):
+        return super().__hash__()
+
+    # -------------------------------------------------------------------------
+    #  OVERLOADED MATH OPERATIONS
+    # -------------------------------------------------------------------------
+    def __abs__(self) -> CountedFloat:
+        """abs(x)"""
+        GLOBAL_COUNTER.incr_abs()
+        return CountedFloat(super().__abs__())
+
+    def __neg__(self) -> CountedFloat:
+        """-x"""
+        GLOBAL_COUNTER.incr_minus()
+        return CountedFloat(super().__neg__())
+
+    def __eq__(self, other) -> bool:
+        """x==other or other==x"""
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        GLOBAL_COUNTER.incr_comp()
+        return super().__eq__(other)
+
+    def __ne__(self, other) -> bool:
+        """x!=other or other!=x"""
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        GLOBAL_COUNTER.incr_comp()
+        return super().__ne__(other)
+
+    def __lt__(self, other):
+        """x<other"""
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        GLOBAL_COUNTER.incr_comp()
+        return super().__lt__(other)
+
+    def __le__(self, other):
+        """x<=other"""
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        GLOBAL_COUNTER.incr_comp()
+        return super().__le__(other)
+
+    def __gt__(self, other):
+        """x>other"""
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        GLOBAL_COUNTER.incr_comp()
+        return super().__gt__(other)
+
+    def __ge__(self, other):
+        """x>=other"""
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        GLOBAL_COUNTER.incr_comp()
+        return super().__ge__(other)
+
+    def __round__(self, n=None) -> int:
+        """
+        round(x, n)
+          n = None -> round to nearest integer and return int
+          n = 0    -> round to nearest integer and return float
+          n > 0    -> round to n decimal places and return float
+        """
+        if n is None:
+            GLOBAL_COUNTER.incr_f2i()  # will round and return int
+        else:
+            GLOBAL_COUNTER.incr_rnd()  # will round and return float
+
+        return super().__round__(n)
+
+    def __floor__(self) -> int:
+        """math.floor(x)"""
+        GLOBAL_COUNTER.incr_f2i()
+        return super().__floor__()
+
+    def __ceil__(self) -> int:
+        """math.ceil(x)"""
+        GLOBAL_COUNTER.incr_f2i()
+        return super().__ceil__()
+
+    def __int__(self) -> int:
+        """int(x)"""
+        GLOBAL_COUNTER.incr_f2i()
+        return super().__int__()
+
+    def __trunc__(self) -> int:
+        """int(x)"""
+        GLOBAL_COUNTER.incr_f2i()
+        return super().__trunc__()
+
+    def __add__(self, other) -> CountedFloat:
+        """x+other"""
+        GLOBAL_COUNTER.incr_add()
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        return CountedFloat(super().__add__(other))
+
+    def __radd__(self, other) -> CountedFloat:
+        """other+x"""
+        GLOBAL_COUNTER.incr_add()
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        return CountedFloat(super().__radd__(other))
+
+    def __sub__(self, other) -> CountedFloat:
+        """x-other"""
+        GLOBAL_COUNTER.incr_sub()
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        return CountedFloat(super().__sub__(other))
+
+    def __rsub__(self, other) -> CountedFloat:
+        """other-x"""
+        GLOBAL_COUNTER.incr_sub()
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        return CountedFloat(super().__rsub__(other))
+
+    def __mul__(self, other) -> CountedFloat:
+        """x*other or other*x"""
+        GLOBAL_COUNTER.incr_mul()
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        return CountedFloat(super().__mul__(other))
+
+    def __rmul__(self, other) -> CountedFloat:
+        """other*x"""
+        GLOBAL_COUNTER.incr_mul()
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        return CountedFloat(super().__rmul__(other))
+
+    def __truediv__(self, other) -> CountedFloat:
+        """x/other"""
+        GLOBAL_COUNTER.incr_div()
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        return CountedFloat(super().__truediv__(other))
+
+    def __rtruediv__(self, other) -> CountedFloat:
+        """other/x"""
+        GLOBAL_COUNTER.incr_div()
+        if isinstance(other, int):
+            GLOBAL_COUNTER.incr_i2f()
+        return CountedFloat(super().__rtruediv__(other))
+
+    def __pow__(self, other) -> CountedFloat:
+        """
+        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:
+            if isinstance(other, int):
+                GLOBAL_COUNTER.incr_i2f()
+            GLOBAL_COUNTER.incr_pow()
+        return CountedFloat(super().__pow__(other))
+
+    def __rpow__(self, other) -> CountedFloat:
+        """
+        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:
+            GLOBAL_COUNTER.incr_exp10()
+        else:
+            if isinstance(other, int):
+                GLOBAL_COUNTER.incr_i2f()
+            GLOBAL_COUNTER.incr_pow()
+        return CountedFloat(super().__rpow__(other))