Compensated arithmetic for Python

Balansis

In active development

An open library for numerically stable computation built on compensated arithmetic: loss of precision, division by zero and overflow stop corrupting a calculation silently and become a visible state. The algebra of the model is proved in Lean 4; the code is on PyPI (1.1.0, AGPL-3.0 or a commercial licence).

The problem

Ordinary floating-point arithmetic silently loses significant digits when it adds quantities of different magnitudes (catastrophic cancellation), and returns nan or inf on overflow. Nothing signals the error. A financial calculation, an engineering simulation or an ML normalisation produces a plausible but wrong number, and it travels on down the pipeline.

Why the usual tools fall short

A naive sum drops the rounding remainder without a trace. Compensation techniques have been known for a long time, but they usually live in standalone functions: untyped, with no explicit states for special cases and no formal verification. Where the correctness of a calculation has to be shown to a reviewer (billing, risk, regulated calculations), that is not enough.

How it works

Every addition keeps its rounding remainder and carries it forward, and the result has a type. Division by zero becomes an explicit state: you choose the policy, and the event is logged. Underneath is an experimental computational model (ACT). We compare the library with the naive sum and do not claim it is more accurate than other compensation methods: if all you need is an exact sum, the standard math.fsum is just as exact and faster. The code is open. The algebra of the model is proved in Lean 4 over the reals; float64 behaviour is not formally proved.

Demo

Balansis terminal: the naive sum prints 93, the compensated one 3333, matching the Decimal reference of 3333; the naive softmax returns nan, the compensated one returns probabilities that sum to 1.
A real run. Lost digits: the naive NumPy sum gives 93, which is silently wrong, while the Balansis compensated sum gives 3333, matching the exact Decimal reference. Softmax without overflow: the naive one returns nan, the compensated one returns probabilities that sum to 1. The comparison is with the naive sum.

Technology

All our products and libraries →

Where it fits

Finance, billing and risk

Calculations that do not go wrong silently: the rounding remainder stays visible, and the balance adds up. For work where a wrong number costs money and goes through an audit.

Engineering simulations and ML normalisation

Adding quantities of different magnitudes without losing digits, and a softmax that does not overflow on large logits: probabilities instead of nan.

Regulated calculations

The algebra of the model is proved in Lean 4, and the proofs can be shown to a reviewer. They do not cover float64 behaviour.

What backs this up

153 Lean 4 theorems about the model, with no gaps

The proof project builds without a single sorry or admit (the markers Lean uses for an unproved step). What is proved is the algebra of the model over the reals; float64 behaviour is not formalised. Count as of 05.10.2026.

Reproduce: lake build + grep -r "sorry\|admit" formal/

Lost digits: the naive sum gives 93, the compensated one 3333

On a documented scenario the naive float sum gives 93, which is wrong, and the compensated one gives 3333, matching the Decimal reference. The comparison is with the naive sum; we do not compare the library with other compensation methods.

Reproduce: pytest tests/test_documented_scenarios.py

Softmax without overflow: the naive one gives nan, the library gives probabilities

On large logits the naive softmax returns nan, while the compensated one returns valid probabilities that sum to 1.

Reproduce: pytest tests/test_documented_scenarios.py

Tests: 870 passed, 0 failed

The test suite of the version under development passes with no failures on pure Python (as of 05.10.2026). Line coverage is 76% against the project’s own threshold of 80%.

Reproduce: pytest

The code is open, so everything above can be checked in the repository. Open the code ↗

Integration

A Python library, installed from PyPI. It goes into the calculation layer in place of naive arithmetic wherever loss of precision is unacceptable.

Work it out on your own figures

The AVA calculator works out whether automating a process pays off, on your figures, with no form and no price from us. If it does not pay off, it says so.

Estimate the payback

Tell us about your problem

Describe it in your own words. If it cannot be solved or will not pay off, we will tell you before any work starts.

In the reply we will say what we understood, what we need to clarify and whether it is worth doing.

or email us directly: hello@xteam.pro

New write-ups on Telegram