Improve docs of `math.isclose(0, x)` when `x = 0` · Issue #131094 · python/cpython · GitHub

Documentation

In the documentation of math.isclose it states

When comparing x to 0.0, isclose(x, 0) is computed as abs(x) <= rel_tol * abs(x), which is False for any x and rel_tol less than 1.0.

The statement isn't correct since x = 0 will give True

Linked PRs

Seems the correction is to add a single word:

When comparing x to 0.0, isclose(x, 0) is computed as abs(x) <= rel_tol * abs(x), which is False for any nonzero x and rel_tol less than 1.0.

Would you mind making a PR?

When making the PR also update the formatting (the parameters should be emphasized). I think the suggested change to the doc is an improvement, although with floating point arithmetic there are some corner cases:

import math

x = 1e-320
rel_tol = 1e-9
abs_tol = math.nextafter(1, 0)
print(math.isclose(x, 0, rel_tol=rel_tol, abs_tol=abs_tol))

print(abs(x) <= rel_tol * abs(x))
print(abs(x) <= abs(rel_tol * x))

results in

True
False
False

@eendebakpt it's true because the difference is less than abs_tol:

import math

x = 1e-320
rel_tol = 1e-9
abs_tol = math.nextafter(1, 0)

diff = abs(0 - x);
print(diff <= abs_tol) # returns True

I think this statement in the documentation holds only for abs_tol being zero (which is the default).

The relevant code is:

cpython/Modules/mathmodule.c

Lines 3202 to 3211 in ad90c5f

    
               /* now do the regular computation 
        
                  this is essentially the "weak" test from the Boost library 
        
               */ 
        
               diff = fabs(b - a); 
        
               return (((diff <= fabs(rel_tol * b)) || 
        
                        (diff <= fabs(rel_tol * a))) || 
        
                       (diff <= abs_tol)); 
        
           }

@plashchynski I agree the statement is valid if f abs_tol is zero. The way the documentation is written suggest the statement is true in general though (if b=0).

@eendebakpt imho this statements sounds more like a reason to set abs_tol to a value greater than zero:

cpython/Doc/library/math.rst

Lines 351 to 355 in ad90c5f

    
           *abs_tol* is the absolute tolerance; it defaults to ``0.0`` and it must be 
        
           nonnegative.  When comparing ``x`` to ``0.0``, ``isclose(x, 0)`` is computed 
        
           as ``abs(x) <= rel_tol  * abs(x)``, which is ``False`` for any ``x`` and 
        
           rel_tol less than ``1.0``.  So add an appropriate positive abs_tol argument 
        
           to the call.

Btw, if a = math.nextafter(0, 1) then math.isclose(a, 0) will always be true for any rel_tol > 0:

import math
a = math.nextafter(0, 1)
print(math.isclose(a, 0, rel_tol=0.9)) # True

because:

print(math.nextafter(0, 1) * 0.9 == math.nextafter(0, 1)) # True

which is contrary to this statement and to pure mathematics as well.

Is there a policy for such corner cases? Should they be considered and handled?

@eendebakpt, I think you misread documentation. It looks like abs_tol disappear in equation of the paragraph, which deals with comparing x to 0, but it's because abs(x) <= rel_tol * abs(x) is valid only in case of abs_tol=0.0 (isclose(x, 0) means the default value of abs_val). Last sentence suggests what to do in this case: "So add an appropriate positive abs_tol argument to the call."

For nonzero abs_tol you must use the generic equation, mentioned right at the beginning of docs: abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol).

So, in your example:

>>> import math
... 
... x = 1e-320
... rel_tol = 1e-9
... abs_tol = math.nextafter(1, 0)
... 
>>> math.isclose(x, 0, rel_tol=rel_tol, abs_tol=abs_tol)
True
>>> abs(x) <= max(rel_tol * abs(x), abs_tol)
True

@hoodmane fix looks good for me. Though, I'm not sure we need such pedancy in docs.

pythongh-131094: Refine math.isclose docs

gh-131094: Refine `math.isclose` docs (#131139)

pythongh-131094: Refine `math.isclose` docs (pythonGH-131139)

Thank you for the report and the fix!

[3.12] gh-131094: Refine `math.isclose` docs (GH-131139) (#131393)

[3.13] gh-131094: Refine `math.isclose` docs (GH-131139) (#131392)

pythongh-131094: Refine `math.isclose` docs (python#131139)

Improve docs of `math.isclose(0, x)` when `x = 0` · Issue #131094 · python/cpython · GitHub

Repository navigation

Improve docs of math.isclose(0, x) when x = 0 #131094

Documentation

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

	/* now do the regular computation
	this is essentially the "weak" test from the Boost library
	*/

	diff = fabs(b - a);

	return (((diff <= fabs(rel_tol * b)) \|\|
	(diff <= fabs(rel_tol * a))) \|\|
	(diff <= abs_tol));
	}

	abs_tol is the absolute tolerance; it defaults to ``0.0`` and it must be
	nonnegative. When comparing ``x`` to ``0.0``, ``isclose(x, 0)`` is computed
	as ``abs(x) <= rel_tol * abs(x)``, which is ``False`` for any ``x`` and
	rel_tol less than ``1.0``. So add an appropriate positive abs_tol argument
	to the call.

Improve docs of `math.isclose(0, x)` when `x = 0` · Issue #131094 · python/cpython · GitHub

Repository navigation

Improve docs of math.isclose(0, x) when x = 0 #131094

Description

Documentation

Linked PRs

Activity

hoodmane commented on Mar 11, 2025

eendebakpt commented on Mar 11, 2025

plashchynski commented on Mar 11, 2025

eendebakpt commented on Mar 11, 2025

plashchynski commented on Mar 11, 2025

plashchynski commented on Mar 11, 2025

skirpichev commented on Mar 12, 2025

picnixz commented on Mar 18, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions