Update stdlib_math.is_close, like python math.isclose

Author: zoziha

doc/specs/stdlib_math.md

@@ -348,22 +348,20 @@ end program demo_math_arange
 
 #### Description
 
-Returns a boolean scalar/array where two scalars/arrays are element-wise equal within a tolerance.
-
-The tolerance values are positive, typically very small numbers. The relative difference `(rtol*abs(b))` and the absolute difference `atol` are added together to compare against the absolute difference between `a` and `b`.
+Returns a boolean scalar/array where two scalars/arrays are element-wise equal within a tolerance, behaves like `isclose` in Python stdlib.
 
 ```fortran
 !> For `real` type
-abs(a - b) <= rtol*abs(b) + atol
+is_close(a, b, rel_tol, abs_tol) = abs(a - b) <= max(rel_tol*(abs(a), abs(b)), abs_tol)
 
 !> For `complex` type
-abs(a%re - b%re) <= rtol*abs(b%re) + atol
-abs(a%im - b%im) <= rtol*abs(b%im) + atol
+is_close(a, b, rel_tol, abs_tol) = is_close(a%re, b%re, rel_tol, abs_tol) .and. &
+                                   is_close(a%im, b%im, rel_tol, abs_tol)
 ```
 
 #### Syntax
 
-`bool = [[stdlib_math(module):is_close(interface)]] (a, b [, rtol, atol])`
+`bool = [[stdlib_math(module):is_close(interface)]] (a, b [, rel_tol, abs_tol])`
 
 #### Status
 
@@ -381,14 +379,15 @@ This argument is `intent(in)`.
 `b`: Shall be a `real/complex` scalar/array.
 This argument is `intent(in)`.
 
-`rtol`: Shall be a `real` scalar.
-This argument is `intent(in)` and `optional`, which is `1.0e-5` by default.
+`rel_tol`: Shall be a `real` scalar.
+This argument is `intent(in)` and `optional`, which is `1.0e-9` by default.
 
-`atol`: Shall be a `real` scalar.
-This argument is `intent(in)` and `optional`, which is `1.0e-8` by default.
+`abs_tol`: Shall be a `real` scalar.
+This argument is `intent(in)` and `optional`, which is `0.0` by default.
 
-Note: All `real/complex` arguments must have same `kind`.
-If the value of `rtol/atol` is negative (not recommended), it will be corrected to `abs(rtol/atol)` by the internal process of `is_close`.
+Note: All `real/complex` arguments must have same `kind`.  
+If the value of `rel_tol/abs_tol` is negative (not recommended), 
+it will be corrected to `abs(rel_tol/abs_tol)` by the internal process of `is_close`.
 
 #### Result value
 
@@ -398,11 +397,11 @@ Returns a `logical` scalar/array.
 
 ```fortran
 program demo_math_is_close
-    use stdlib_math, only: is_close
+    use stdlib_math,  only: is_close
     use stdlib_error, only: check
     real :: x(2) = [1, 2]
-    print *, is_close(x,[real :: 1, 2.1])     !! [T, F]
-    print *, is_close(2.0, 2.1, atol=0.1)     !! T
+    print *, is_close(x,[real :: 1, 2.1])        !! [T, F]
+    print *, is_close(2.0, 2.1, abs_tol=0.1)     !! T
     call check(all(is_close(x, [2.0, 2.0])), msg="all(is_close(x, [2.0, 2.0])) failed.", warn=.true.)
         !! all(is_close(x, [2.0, 2.0])) failed.
 end program demo_math_is_close

src/stdlib_math.fypp

@@ -286,10 +286,10 @@ module stdlib_math
     interface is_close
         #:set RC_KINDS_TYPES = REAL_KINDS_TYPES + CMPLX_KINDS_TYPES
         #:for k1, t1 in RC_KINDS_TYPES
-        elemental module function is_close_${t1[0]}$${k1}$(a, b, rtol, atol) result(result)
+        elemental module function is_close_${t1[0]}$${k1}$(a, b, rel_tol, abs_tol) result(close)
             ${t1}$, intent(in) :: a, b
-            real(${k1}$), intent(in), optional :: rtol, atol
-            logical :: result
+            real(${k1}$), intent(in), optional :: rel_tol, abs_tol
+            logical :: close
         end function is_close_${t1[0]}$${k1}$
         #:endfor
     end interface is_close

src/stdlib_math_is_close.fypp

@@ -7,25 +7,25 @@ contains
     #! Determines whether the values of `a` and `b` are close.
 
     #:for k1, t1 in REAL_KINDS_TYPES
-    elemental module function is_close_${t1[0]}$${k1}$(a, b, rtol, atol) result(result)
+    elemental module function is_close_${t1[0]}$${k1}$(a, b, rel_tol, abs_tol) result(close)
         ${t1}$, intent(in) :: a, b
-        real(${k1}$), intent(in), optional :: rtol, atol
-        logical :: result
+        real(${k1}$), intent(in), optional :: rel_tol, abs_tol
+        logical :: close
 
-        result = abs(a - b) <= abs(optval(rtol, 1.0e-5_${k1}$)*b) + &
-                               abs(optval(atol, 1.0e-8_${k1}$))
+        close = abs(a - b) <= max( abs(optval(rel_tol, 1.0e-9_${k1}$)*max(abs(a), abs(b))), &
+                                   abs(optval(abs_tol, 0.0_${k1}$)) )
 
     end function is_close_${t1[0]}$${k1}$
     #:endfor
 
     #:for k1, t1 in CMPLX_KINDS_TYPES
-    elemental module function is_close_${t1[0]}$${k1}$(a, b, rtol, atol) result(result)
+    elemental module function is_close_${t1[0]}$${k1}$(a, b, rel_tol, abs_tol) result(close)
         ${t1}$, intent(in) :: a, b
-        real(${k1}$), intent(in), optional :: rtol, atol
-        logical :: result
+        real(${k1}$), intent(in), optional :: rel_tol, abs_tol
+        logical :: close
 
-        result = is_close_r${k1}$(a%re, b%re, rtol, atol) .and. &
-                 is_close_r${k1}$(a%im, b%im, rtol, atol)
+        close = is_close_r${k1}$(a%re, b%re, rel_tol, abs_tol) .and. &
+                is_close_r${k1}$(a%im, b%im, rel_tol, abs_tol)
 
     end function is_close_${t1[0]}$${k1}$
     #:endfor

src/tests/math/test_math_is_close.f90

@@ -10,30 +10,36 @@ subroutine test_math_is_close_real
         use stdlib_math, only: is_close
         use stdlib_error, only: check
 
-        call check(is_close(2.5, 2.5, rtol=1.0e-5), msg="is_close(2.5, 2.5, rtol=1.0e-5) failed.")
-        call check(all(is_close([2.5, 3.2], [2.5, 10.0], rtol=1.0e-5)), &
-                   msg="all(is_close([2.5, 3.2], [2.5, 10.0], rtol=1.0e-5)) failed (expected).", warn=.true.)
+        call check(is_close(2.5, 2.5, rel_tol=1.0e-5), msg="is_close(2.5, 2.5, rel_tol=1.0e-5) failed.")
+        call check(all(is_close([2.5, 3.2], [2.5, 10.0], rel_tol=1.0e-5)), &
+                   msg="all(is_close([2.5, 3.2], [2.5, 10.0], rel_tol=1.0e-5)) failed (expected).", warn=.true.)
         call check(all(is_close(reshape([2.5, 3.2, 2.2, 1.0], [2, 2]), reshape([2.5, 3.2001, 2.25, 1.1], [2, 2]), &
-                   atol=1.0e-5, rtol=0.1)), &
+                   abs_tol=1.0e-5, rel_tol=0.1)), &
                    msg="all(is_close(reshape([2.5, 3.2, 2.2, 1.0],[2,2]), reshape([2.5, 3.2001, 2.25, 1.1],[2,2]), &
-                   &rtol=1.0e-5, atol=0.1)) failed.")
+                   &rel_tol=1.0e-5, abs_tol=0.1)) failed.")
+
+        !> Tests for zeros
+        call check(is_close(0.0, -0.0), msg="is_close(0.0, -0.0) failed.")
 
     end subroutine test_math_is_close_real
 
     subroutine test_math_is_close_complex
         use stdlib_math, only: is_close
         use stdlib_error, only: check
 
-        call check(is_close((2.5,1.2), (2.5,1.2), rtol=1.0e-5), &
-                   msg="is_close((2.5,1.2), (2.5,1.2), rtol=1.0e-5) failed.")
-        call check(all(is_close([(2.5,1.2), (3.2,1.2)], [(2.5,1.2), (10.0,1.2)], rtol=1.0e-5)), &
-                   msg="all(is_close([(2.5,1.2), (3.2,1.2)], [(2.5,1.2), (10.0,1.2)], rtol=1.0e-5)) failed (expected).", &
+        call check(is_close((2.5,1.2), (2.5,1.2), rel_tol=1.0e-5), &
+                   msg="is_close((2.5,1.2), (2.5,1.2), rel_tol=1.0e-5) failed.")
+        call check(all(is_close([(2.5,1.2), (3.2,1.2)], [(2.5,1.2), (10.0,1.2)], rel_tol=1.0e-5)), &
+                   msg="all(is_close([(2.5,1.2), (3.2,1.2)], [(2.5,1.2), (10.0,1.2)], rel_tol=1.0e-5)) failed (expected).", &
                    warn=.true.)
         call check(all(is_close(reshape([(2.5,1.2009), (3.2,1.199999)], [1, 2]), reshape([(2.4,1.2009), (3.15,1.199999)], [1, 2]), &
-                   atol=1.0e-5, rtol=0.1)), &
+                   abs_tol=1.0e-5, rel_tol=0.1)), &
                    msg="all(is_close(reshape([(2.5,1.2009), (3.2,1.199999)], [1, 2]), &
                    &reshape([(2.4,1.2009), (3.15,1.199999)], [1, 2]), &
-                   &rtol=1.0e-5, atol=0.1)) failed.")
+                   &rel_tol=1.0e-5, abs_tol=0.1)) failed.")
+
+        !> Tests for zeros
+        call check(is_close((0.0, -0.0), (-0.0, 0.0)), msg="is_close((0.0, -0.0), (-0.0, 0.0)) failed.")
 
     end subroutine test_math_is_close_complex