How math.isclose Works in Python: Tolerances Explained

Due to the way computers store floating-point numbers in binary format, direct equality checks (a == b) often fail due to rounding errors. Python's math.isclose() function resolves this by evaluating whether two values are close enough to be considered equal based on specified tolerance thresholds. This article breaks down the mathematical formula used by math.isclose() and details how it applies relative tolerance (rel_tol) and absolute tolerance (abs_tol) to make this determination.

The Underlying Evaluation Formula

The math.isclose() function determines equivalence by checking if the absolute difference between two numbers is less than or equal to the greater of two tolerance thresholds. The exact mathematical criterion evaluated is:

abs(a - b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)

If the condition evaluates to True, the function returns True; otherwise, it returns False.

Relative Tolerance (`rel_tol`)

Relative tolerance measures the allowable difference relative to the magnitude of the values being compared.

Default value: 1e-09 (meaning the values must agree within roughly nine decimal places).
Calculation: Python multiplies rel_tol by the larger absolute value of the two inputs: rel_tol * max(abs(a), abs(b)).
Purpose: It automatically scales with the size of the numbers. A difference of 10 is insignificant when comparing numbers in the billions, but massive when comparing numbers smaller than 1. Relative tolerance accommodates this scaling behavior.

Absolute Tolerance (`abs_tol`)

Absolute tolerance is a fixed, unchanging minimum threshold for the allowable difference between two numbers.

Default value: 0.0.
Calculation: It is not scaled by the input values; it is used directly as specified.
Purpose: It is essential for comparisons near zero. Because the relative tolerance scales with max(abs(a), abs(b)), comparing any small number to zero causes the relative threshold to approach zero, resulting in False even for negligible differences. Setting abs_tol provides a fallback threshold when numbers are near zero.

How the Criteria Interact

By using the max() function between the relative and absolute thresholds, math.isclose() ensures that:

For large numbers: The relative tolerance term (rel_tol * max(abs(a), abs(b))) is typically larger than abs_tol, meaning the function automatically scales the acceptable margin of error to the size of the inputs.
For numbers near zero: The relative term shrinks toward zero. If defined, abs_tol takes precedence as the larger value, preventing comparisons against zero from failing due to minor floating-point imprecision.

Special Values and Constraints

Non-negative tolerances: Both rel_tol and abs_tol must be greater than or equal to 0.0. Passing negative values will raise a ValueError.
Infinities (inf, -inf): Comparing two infinities of the same sign returns True. Comparing an infinity to any finite number returns False.
Not a Number (NaN): If either a or b is NaN, math.isclose() always returns False, as NaN is not considered close to any value, including itself.