counted-float 1.2.0

Count floating-point operations in Python code & benchmark relative flop costs.

counted-float

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 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.

Flop weights are computed using a highly curated dataset spanning a wide range of modern CPUs:

• 19 benchmarks, 16 spec sheets, 12 third party measurements (Agner Fog, uops.info)
• covering x86 (Intel, AMD) and ARM (Apple, AWS, Azure) architectures

Full documentation: counted-float.readthedocs.io

Installation

Use your favorite package manager such as uv or pip:

pip install counted-float           # install without numba optional dependency
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).

Quick start

CountedFloat is a drop-in replacement for the built-in float; it is "contagious", so results of math operations involving a CountedFloat stay CountedFloat:

from counted_float import CountedFloat

cf = CountedFloat(1.3)
f = 2.8

result = cf + f  # result = CountedFloat(4.1)

is_float_1 = isinstance(cf, float)  # True
is_float_2 = isinstance(result, float)  # True

FLOPs performed by CountedFloat values are counted while a FlopCountingContext is active:

from counted_float import CountedFloat, FlopCountingContext

cf1 = CountedFloat(1.73)
cf2 = CountedFloat(2.94)

with FlopCountingContext() as ctx:
    _ = cf1 * cf2
    _ = cf1 + cf2

counts = ctx.flop_counts()   # {FlopType.MUL: 1, FlopType.ADD: 1}
counts.total_count()         # 2

Documentation

The documentation site covers the rest:

• Counting FLOPs — the counting model, counting contexts, pausing
• Math patching semantics — how (and when) math.* functions are instrumented
• FLOP weights — built-in consensus weights, configuring your own
• Benchmarking — estimating flop weights on your own hardware
• CLI reference — using counted_float as a stand-alone command-line tool
• Known limitations — what falls outside the counting model
• Reference — per-FLOP-type counting rules, methodology, CPU scope