noisefloat

Stochastic numerical validation for Python and deep-learning operators.

Getting started · Framework · Examples · API reference · Paper

noisefloat carries randomly rounded replicas of scalars, arrays, and tensors, then estimates significant digits from their spread. Use it to compare numerical formulations, locate sensitive operators, and monitor rounding sensitivity during training or inference. NumPy, PyTorch, JAX, and TensorFlow array backends are supported; NumPy is the only required runtime dependency.

Framework

A numerical value becomes several synchronous stochastic samples (three by default). Supported operations run on corresponding samples, apply backend-native software rounding, and expose a representative mean plus reliability statistics.

Analysis task	Interface
Scalar and array algorithms	NFloat, mathematical functions, diagnostics
Differentiable overloaded arithmetic	NFloatSTE
PyTorch operator boundaries	NFloatTensor, NFloat*, wrap_model, nfloat_operator
Exposed PyTorch arithmetic	ArithmeticNFloat*, wrap_model_arithmetic
TensorFlow/Keras operator boundaries	TensorFlowNFloat*, wrap_keras
Iteration reports and shadow probes	NFloatIterationTracker, experiment helpers

The method is described in Chen (2026). Instrumentation is explicit: arithmetic wrappers expose supported Python-visible operations, while GEMM-like backend kernels use a controlled input-perturbation approximation. Operator-boundary wrappers round selected kernel outputs. See the framework guide for architecture and analysis scope.

Installation

Requires Python 3.9+ and NumPy 1.22+.

python -m pip install noisefloat

# Install from source:
git clone https://github.com/chenxinye/noisefloat.git
cd noisefloat
python -m pip install -e .

# Choose optional dependencies as needed:
python -m pip install -e ".[torch,scipy]"
# Other extras: jax, tensorflow, experiments, dev

Quick start

Compare an expression with a stable reformulation:

import noisefloat as nf

nf.configure(backend="numpy", exp_bits=8, sig_bits=23,
             n_samples=3, random_state=42)
nf.reset_chopper_cache()
x = nf.NFloat(1e-6)
direct = nf.exp(x) - 1.0
stable = nf.expm1(x)

print("direct:", direct.mean, direct.digits)
print("expm1 :", stable.mean, stable.digits)

The reported digits estimate sensitivity to the configured rounding policy. Compare formulations across seeds and against a reference calculation. Identical samples return the agreement sentinel 15; this does not certify fifteen accurate digits. Read Interpreting results.

Deep-learning operator analysis

import torch
import noisefloat as nf
from noisefloat.nn import (
    NFloatLinear, NFloatReLU, clear_kernel_reports,
    get_kernel_reports, nfloat_analysis,
)

torch.manual_seed(42)
nf.configure(backend="torch", exp_bits=8, sig_bits=23,
             n_samples=3, random_state=42)
nf.reset_chopper_cache()
model = torch.nn.Sequential(NFloatLinear(4, 8), NFloatReLU(), NFloatLinear(8, 2))
model.eval()
clear_kernel_reports()
with torch.no_grad(), nfloat_analysis(mode="test"):
    output = model(torch.randn(6, 4, dtype=torch.float64))

print(output.value.shape)
for report in get_kernel_reports():
    print(report.kernel_name, report.avg_digits, report.min_digits)

Use kernel wrappers with use_ste=True for the documented training example. STE is not universally preserved by module-level math helpers or arithmetic tensor dispatch. NFloatIterationTracker collects reports into tracker.rows and exports CSV, JSONL, and summary JSON files.

Applications and examples

The example gallery contains downloadable, focused scripts:

• Cancellation and stable formulas
• Polynomial evaluation and reduction boundaries
• Comparing software precision settings
• Custom operator instrumentation
• Model wrapping and analysis granularity
• STE training and iteration exports
• TensorFlow/Keras analysis
• Verification and research experiment recipes

For example, after installing the package:

python docs/_examples/cancellation.py
python docs/_examples/model_wrapping.py
python docs/_examples/training.py

Additional numerical demonstrations are available in examples/, CADNA-style verification cases in verifications/, and research workflows in exps/.

Documentation

The documentation covers CESTAC and discrete stochastic arithmetic, software architecture, precision settings, operator analysis, worked examples, and the API reference. It also includes citation guidance and the license.

Build with Python 3.11+:

python -m pip install -r docs/requirements.txt
make html                 # also works: make -C docs html

Open docs/_build/html/index.html, or preview over HTTP:

python -m http.server --directory docs/_build/html 8000

For documentation build requirements and hosting instructions, see Building the documentation.

Precision and reproducibility

• sig_bits counts fraction bits: FP16-like (5, 10), BF16-like (8, 7), FP32-like (8, 23), FP64-like (11, 52) for (exp_bits, sig_bits).
• The implementation emulates rounding within float64 working storage.
• configure changes global policy for subsequent operations. Recreate values when changing formats, and call reset_chopper_cache() to replay an RNG stream.
• Seed framework RNGs separately, including torch.manual_seed for model weights, inputs, and the arithmetic GEMM perturbation path.
• Install the SciPy extra for Student-t quantiles at custom confidence levels.

Citation

Chen, X. (2026) ‘Automated Numerical Stability Analysis of Deep Learning Operators’, arXiv preprint, arXiv:2607.25494. Available at: arxiv.org/abs/2607.25494.

See the references for the Harvard bibliography and BibTeX.

License

MIT © 2026 chenxinye.