ML Foundations
Choose an absolute tolerance when comparing a residual with zero
Relative tolerance alone is usually unsuitable for a near-zero comparison. Make the acceptable absolute error explicit.
Evidence and testing
Review record: Tensor Almanac automated evidence gate (no independent human review). Example versions, recorded outputs and limitations appear below.
Small and close to zero are different tests
A numerical test may expect a residual to be zero after cancellation or normalization. Replacing `residual == 0` with `math.isclose(residual, 0)` can still return false for a small nonzero number. The function combines a relative tolerance with an absolute tolerance, and its default absolute tolerance is zero. Python explicitly calls out the need for an appropriate absolute tolerance near zero. [1]
For a finite nonzero residual compared with zero, a relative tolerance below one scales the allowed difference by the residual itself. That does not make the residual close enough. This is a consequence of the documented comparison rule, not evidence that the function has failed to notice a small magnitude. [1]
Express the allowed residual in the same units
The example uses the synthetic residual `1e-12`. Default `isclose` rejects it against zero. With relative tolerance disabled and absolute tolerance `1e-9`, it passes; with the tighter absolute tolerance `1e-13`, it fails. A larger residual, `1e-6`, also fails the `1e-9` absolute threshold. These cases expose the chosen boundary rather than assuming every small-looking value should pass. [1]
An absolute tolerance has the units of the quantity being compared. The numbers here illustrate API behavior; they are not recommended thresholds for every model, sensor or computation. Select the threshold from the application's accepted error and data scale, then test a case on either side of it.
Executed with Python 3.13.5; bounded synthetic example. Exact stdout and source-byte SHA-256 are preserved in private evidence.
import math
residual = 1e-12
print("exact zero:", residual == 0.0)
print("default isclose to zero:", math.isclose(residual, 0.0))
print("absolute tolerance 1e-9:", math.isclose(residual, 0.0, rel_tol=0.0, abs_tol=1e-9))
print("absolute tolerance 1e-13:", math.isclose(residual, 0.0, rel_tol=0.0, abs_tol=1e-13))
print("outside tolerance:", math.isclose(1e-6, 0.0, rel_tol=0.0, abs_tol=1e-9))
Recorded output
exact zero: False default isclose to zero: False absolute tolerance 1e-9: True absolute tolerance 1e-13: False outside tolerance: False
Keep tolerance separate from correctness
Floating-point representation can introduce approximation, but that does not justify dismissing every failed assertion as rounding. Python's tutorial explains why many decimal fractions are not represented exactly in binary and distinguishes the stored value from its displayed decimal form. [2]
A useful test therefore records both the numerical contract and its tolerance. Keep a failing example outside the permitted range so that an accidentally generous threshold does not conceal a regression. This guide covers finite scalar comparisons only. It does not select domain-specific tolerances, establish accuracy for a complete numerical algorithm, or claim that passing a tolerance check proves the surrounding computation is correct.