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 the
benchmarkingoptional dependency)
Flop weights are computed using a highly curated dataset spanning a wide range of modern CPUs:
- 21 benchmarks, 16 spec sheets, 12 third party measurements (Agner Fog, uops.info)
- covering x86 (Intel, AMD) and ARM (Apple, AWS, Azure) architectures
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.
Full documentation: counted-float.readthedocs.io
Installation
Use your favorite package manager such as uv or pip. What you install decides which of
the three capabilities you get:
pip install counted-float # counting
pip install counted-float[benchmarking] # + measure this machine's flop costs
pip install counted-float[cli] # + the counted_float command
Counting is the base install and needs nothing else. Building CountedFloat
values, counting contexts, the built-in flop weights, reading benchmark results
shipped with the package, and evaluating what counting costs you on your own
workload all work here. It is about 17 MB installed.
Benchmarking measures your machine — running the flop benchmark suite to derive weights for the hardware you are on, rather than using the shipped consensus ones. It needs compiled probes (numba) and the packages that describe a CPU (psutil, py-cpuinfo), which is most of the install size: with it, expect roughly 180 MB. Without the extra, calling the benchmark suite tells you what to install instead of failing obscurely, and nothing else is affected.
The CLI adds the counted_float command. The command is always installed;
without the extra it reports what to install instead of producing a traceback.
Extras compose, so counted-float[benchmarking,cli] gets you everything.
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
Performance overhead
CountedFloat adds counting overhead in two forms — the price of Python-level
operator dispatch and result wrapping. How much slower your code runs depends
almost entirely on its operation mix:
- native float ops (
+,-,*,/, comparisons): the expensive end of the range — the fixed per-operation dispatch cost dwarfs the nanoseconds of actual arithmetic; - patched
math.*calls (math.sqrt,math.lgamma, …): a roughly fixed surcharge per call, so the multiple shrinks as the function itself gets more expensive.
counted_float evaluate-overhead measures your own machine — a per-flop-type
overhead table, the geomean across types, and a practical mixed workload; see
the captured example
for representative figures.
Three facts worth knowing:
- counting state is per-thread: a
FlopCountingContextmeasures only the thread that opened it (open one context per worker thread to measure multi-threaded code, and sum the results). Free-threaded builds (3.14t) are supported and CI-tested; - the overhead is inherent and
PauseFlopCountingdoes not reduce it (the instrumented operators still execute; only count registration stops) — the escape hatch for hot uncounted regions is converting back viafloat(x); - overhead never affects count accuracy — counts are exact regardless.
This makes CountedFloat a tool for research and prototyping code, not
production hot loops.
numpy counting is an explicit non-goal: np.float64 (float subclass) scalars
work and count correctly, but mixing CountedFloat with numpy arrays raises TypeError rather
than silently returning uncounted results — see
Known limitations
for the full boundary.
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_floatas a stand-alone command-line tool - Known limitations — what falls outside the counting model
- Reference — per-FLOP-type counting rules, methodology, CPU scope
1 maintainer
Metadata
1 maintainer
Release files for counted-float 2.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| counted_float-2.8.0.tar.gz | 189.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| counted_float-2.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 437.1 kB
Release files / counted_float-2.8.0.tar.gz
| Download URL | counted_float-2.8.0.tar.gz |
|---|---|
| Size | 189.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5d654d9b9b6fce32ef40edd384e543307d59868848037a2c451f7e7ff14dc5ad
|
|
BLAKE2b-256 checksum How to use checksums |
7c447b5a68d081320eb9cd0a3bb6a856d7261471a3dee38a084e7b0be34b0760
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / counted_float-2.8.0-py3-none-any.whl
| Download URL | counted_float-2.8.0-py3-none-any.whl |
|---|---|
| Size | 248.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a64af393d5d3419bc5197ae46800dfa1dd95743dd979bee42b11236410281a31
|
|
BLAKE2b-256 checksum How to use checksums |
66bc846207e71b36cdece35ea54ab9db138d7ede73ab1be51e74564f6c794dc4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency log
