Python

# NumPy np.allclose()

The NumPy allclose() function determines if two arrays are equal with a tolerance on an element-by-element basis.

This tutorial will explore the allclose() function syntax and give several practical examples demonstrating how to use it.

## NumPy allclose() Function

The allclose() function will compare the corresponding elements in the input arrays and determine if they are equal (with tolerance).

A tolerance value is always positive, typically in small numbers. To calculate the absolute difference between the two input arrays, NumPy adds the relative and absolute differences.

The relative difference is the product of rtol and abs(b), where b is the second input array.

## Function Syntax

This is depicted in the function syntax shown below:

numpy.allclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False)

Let us explore the function parameters.

## Function Parameters

1. a – the first input array.
2. b – the second input array.
3. rtol – defines the relative tolerance.
4. atol – defines absolute tolerance.
5. equal_nan – specifies whether or not to compare NaN as equal. If set to true, the function will treat a NaN in the first array as equivalent to a NaN in the second array.

## Function Return Value

The function returns a Boolean value. If the specified arrays are equal within the defined tolerance value, the function returns True. Otherwise, the function will return false.

## Example #1

Consider the example below that shows how to use the allclose() function in a 1D array.

# import numpy
import numpy as np
# first array
arr_1 = np.array([1e5,1e-5])
# second array
arr_2 = np.array([1.001e10, 1.002e-12])
print(f"Equal?: {np.allclose(arr_1, arr_2)}")

We create two 1-D arrays in the example above and compare them using the allclose() function.

NOTE: We do not set the absolute and relative tolerance values in the example above. The function should return:

Equal?: False

## Example #2To set tolerance values, we can use the example below:

# first array
arr_1 = np.array([1e5,1e-5])
# second array
arr_2 = np.array([1.001e10, 1.002e-12])
# tolerance values
rtol = 1e10
atol = 1e12
print(f"Equal?: {np.allclose(arr_1, arr_2, rtol=rtol, atol=atol)}")

In the example above, we set the relative and absolute tolerance values using the rtol and atol parameters.

NOTE: The above example’s tolerance values have been tweaked for illustration purposes.

The code below should return:

Equal?: True

## Example #3

In the example below, we use the allclose() function to test equality with arrays that include NaN values.

arr1 = np.array([1.0e10, np.nan])
arr2 = np.array([1.0e10, np.nan])
print(f"Equal?: {np.allclose(arr1, arr2)}")

In the example above, we have two arrays that seem equal. However, when we use the allclose() function, it returns false as shown:

Equal?: False

This is because the arrays contain NaN values. By default, the allclose() function will treat NaN values differently.

To solve this, we can set the equal_nan parameter to true as shown:

arr1 = np.array([1.0e10, np.nan])
arr2 = np.array([1.0e10, np.nan])
print(f"Equal?: {np.allclose(arr1, arr2, equal_nan=True)}")

In this case, the function should return:

Equal?: True

## Terminating

This article discussed how to use the allclose() function in NumPy. We also demonstrated how to use the function with various examples.

Happy coding!!!