Python math library | isclose() method

In the Python math module, math.isclose() the method is used to determine whether two floating point numbers are close in value. To use this function in Python you must import the math module.

Syntax: isclose(a, b, rel_tol = 1e-09, abs_tol 0.0) Parameters: rel_tol: maximum difference for being considered “close”, relative to the magnitude of the input values abs_tol: maximum difference for being considered “close”, regardless of the magnitude of the input values -> rel_tol and abs_tol can be changed by using keyword argument, or by simply providing directly as according to their positions in the parameter list. Return Value : Return True if a is close in value to b, and False otherwise.

Without Using any Tolerance

For the values to be considered close, the difference between them must be smaller than at least one of the tolerances. If both torelances are provided, the absolute tolerance is checked first, and if exceeded the the relative tolerance is checked.

Python3

# Example 1 : Without specifying any tolerance

# By default, math.isclose() applies a relative tolerance of 1e-09 = 0.0000000010

# Importing Math module
import math

# printing whether two values are close or not
print(math.isclose(2.005, 2.005)) # True,values are exact
print(math.isclose(2.005, 2.004)) # False, relative difference > default rel_tol
print(math.isclose(2.006, 2.005)) # False, relative difference > default rel_tol

# calculating relative differences:
# |2.005 - 2.004|/((2.005 - 2.004)/2) = 0.0005
# |2.006 - 2.005|/((2.006 - 2.005)/2) = 0.0005

Output:

True
False
False

Using Absolute Tolerance

The absolute difference between the two values is checked against specified absolute tolerance (abs_tol), if the abs_tol is exceed mathisclose() returns False and True if otherwise.

Python3

# Example 2 : Using absolute tolerances

# Importing Math module
import math

# printing whether two values are close or not
print(math.isclose(2.005, 2.125, abs_tol = 0.25)) # True, absolute difference < abs_tol
print(math.isclose(2.547, 2.0048, abs_tol = 0.5)) # False, absolute difference > abs_tol
print(math.isclose(2.0214, 2.00214, abs_tol = 0.02)) # True, absolute difference < abs_tol

# calculating absolute differences:
# |2.005 - 2.125|    = 0.12000
# |2.547 - 2.0048|   = 0.54220
# |2.0214 - 2.00214| = 0.01926

Output:

True
False
True

You can change absolute tolerance, as in above case absolute tolerance is different in all three cases.

Using Relative Tolerance

By default, math.isclose() provides a default rel_tol = 1e-09 = 0.0000000010. If no tolerance is specified then this is used.

However, rel_tol can be specified to meet requirements.

Python3

# Example 3 : Using relative tolerances
import math  # isclose() is domiciled in the math library
a = 2.005
b = 2.004

calc_rel_diff = abs(a - b) / ((a + b) / 2)
print("Calculated relative difference = {:.6f}".format(calc_rel_diff))
print("Default relative difference used in math.isclose() = {:.10f}".format(1e-09))

# printing whether two values are close or not without specifying the tolerances. Takes default rel_tol
# Calculated relative difference way above default rel_tol = 1e-09 = 0.0000000010, Returns False
print("Returns: {} --> calc_rel_diff = {} > default rel_tol = {:.10f}".format(math.isclose(a, b), calc_rel_diff, 1e-09))
# specify rel_tol
rel_tol = 5e-04
print("Returns: {}  --> calc_rel_diff = {} < specified rel_tol = {:.4f}".format(math.isclose(a, b, rel_tol=rel_tol),calc_rel_diff, rel_tol))  # Calculated relative difference below default rel_tol = 1e-09 = 0.0000000010

Output:

Calculated relative difference = 0.000499
Default relative difference used in math.isclose() = 0.0000000010
Returns: False --> calc_rel_diff = 0.0004988775255674181 > default rel_tol = 0.0000000010
Returns: True  --> calc_rel_diff = 0.0004988775255674181 < specified rel_tol = 0.0005

Combining both tolerances

Using both abs_tol (absolute tolerance) and rel_tol (relative tolerance) together in the math.isclose() function allows you to define a more precise and flexible criterion for determining if two numbers are “close enough” based on both absolute and relative considerations.

abs_tol is checked first. If the absolute difference between the numbers is within abs_tol, the function returns True.

If the absolute difference is greater than abs_tol, the function then checks the relative difference based on rel_tol. If the relative difference is within rel_tol, the function returns True.

If neither the absolute tolerance nor the relative tolerance conditions are met, the function returns False.

The example below illustrate a case where the absolute tolerance is exceeded while the relative tolerance is not exceeded giving a positive comparison.

Python3

# Example 4 : Using both tolerances: abs_rel exceeded but the rel_tol not exceeded returning True
import math # isclose() is domiciled in the math library
a = 2.005
b = 2.004
calc_rel_diff = abs(a - b) / ((a + b) / 2)
calc_abs_diff = abs(a-b)
print("Calculated relative difference = {:.6f}".format(calc_rel_diff))
print("Calculated absolute difference = {:.6f}".format(calc_abs_diff))

# Specifying both tolerances
abs_rol = 4e-04 # 0.0004
rel_tol = 5e-04 # 0.0005

print("Returns: {}  --> Though the calculated absolute difference = {:.6f} > specified abs_tol = {:.6f}, the calc_rel_diff = {:.6f} < specified rel_tol = {:.6f} which is checked last if the absolute difference is exceeded.".format(math.isclose(a, b, rel_tol=rel_tol, abs_tol=abs_rol),calc_abs_diff, abs_rol, calc_rel_diff, rel_tol)) # Calculated relative difference below default rel_tol = 1e-09 = 0.0000000010

Output:

Calculated relative difference = 0.000499
Calculated absolute difference = 0.001000
Returns: True  --> Though the calculated absolute difference = 0.001000 > specified abs_tol = 0.000400, the calc_rel_diff = 0.000499 < specified rel_tol = 0.000500  which is checked last if the absolute difference is exceeded.

If both tolerances were exceeded then math.isclose() would return False.