[stdlib_math] add is_close routines.

doc/specs/stdlib_math.md

@@ -320,25 +320,25 @@ program demo_logspace_rstart_cbase
 
 end program demo_logspace_rstart_cbase
 ```
-## `arange`
+### `arange`
 
-### Status
+#### Status
 
 Experimental
 
-### Class
+#### Class
 
 Pure function.
 
-### Description
+#### Description
 
 Creates a one-dimensional `array` of the `integer/real` type with fixed-spaced values of given spacing, within a given interval.
 
-### Syntax
+#### Syntax
 
 `result = [[stdlib_math(module):arange(interface)]](start [, end, step])`
 
-### Arguments
+#### Arguments
 
 All arguments should be the same type and kind.
 
@@ -354,18 +354,18 @@ The default `end` value is the inputted `start` value.
 This is an `intent(in)` and `optional` argument.   
 The default `step` value is `1`.
 
-#### Warning
+##### Warning
 If `step = 0`, the `step` argument will be corrected to `1/1.0` by the internal process of the `arange` function.   
 If `step < 0`, the `step` argument will be corrected to `abs(step)` by the internal process of the `arange` function. 
 
-### Return value
+#### Return value
 
 Returns a one-dimensional `array` of fixed-spaced values.
 
 For `integer` type arguments, the length of the result vector is `(end - start)/step + 1`.  
 For `real` type arguments, the length of the result vector is `floor((end - start)/step) + 1`.
 
-### Example
+#### Example
 
 ```fortran
 program demo_math_arange
@@ -388,3 +388,126 @@ program demo_math_arange
 
 end program demo_math_arange
 ```
+
+### `is_close`
+
+#### Description
+
+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
+is_close(a, b, rel_tol, abs_tol) = abs(a - b) <= max(rel_tol*(abs(a), abs(b)), abs_tol)
+
+!> For `complex` type
+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 [, rel_tol, abs_tol])`
+
+#### Status
+
+Experimental.
+
+#### Class
+
+Elemental function.
+
+#### Arguments
+
+`a`: Shall be a `real/complex` scalar/array.
+This argument is `intent(in)`.
+
+`b`: Shall be a `real/complex` scalar/array.
+This argument is `intent(in)`.
+
+`rel_tol`: Shall be a `real` scalar.
+This argument is `intent(in)` and `optional`, which is `1.0e-9` 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 `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
+
+Returns a `logical` scalar/array.
+
+#### Example
+
+```fortran
+program demo_math_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, 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
+```
+
+### `all_close`
+
+#### Description
+
+Returns a boolean scalar where two arrays are element-wise equal within a tolerance, behaves like `all(is_close(a, b [, rel_tol, abs_tol]))`.
+
+#### Syntax
+
+`bool = [[stdlib_math(module):all_close(interface)]] (a, b [, rel_tol, abs_tol])`
+
+#### Status
+
+Experimental.
+
+#### Class
+
+Pure function.
+
+#### Arguments
+
+`a`: Shall be a `real/complex` array.
+This argument is `intent(in)`.
+
+`b`: Shall be a `real/complex` array.
+This argument is `intent(in)`.
+
+`rel_tol`: Shall be a `real` scalar.
+This argument is `intent(in)` and `optional`, which is `1.0e-9` 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 `rel_tol/abs_tol` is negative (not recommended), 
+it will be corrected to `abs(rel_tol/abs_tol)` by the internal process of `all_close`.
+
+#### Result value
+
+Returns a `logical` scalar.
+
+#### Example
+
+```fortran
+program demo_math_all_close
+    use stdlib_math,  only: all_close
+    use stdlib_error, only: check
+    real    :: x(2) = [1, 2], random(4, 4)
+    complex :: z(4, 4)
+
+    call check(all_close(x, [2.0, 2.0], rel_tol=1.0e-6, abs_tol=1.0e-3), &
+               msg="all_close(x, [2.0, 2.0]) failed.", warn=.true.)
+               !! all_close(x, [2.0, 2.0]) failed.
+
+    call random_number(random(4, 4))
+    z = 1.0
+    print *, all_close(z+1.0e-11*random, z)     !! T
+
+end program demo_math_all_close
+```

src/CMakeLists.txt

@@ -33,6 +33,8 @@ set(fppFiles
     stdlib_math_linspace.fypp
     stdlib_math_logspace.fypp
     stdlib_math_arange.fypp
+    stdlib_math_is_close.fypp
+    stdlib_math_all_close.fypp
     stdlib_string_type.fypp
     stdlib_string_type_constructor.fypp
     stdlib_strings_to_string.fypp

src/Makefile.manual

@@ -27,8 +27,10 @@ SRCFYPP = \
         stdlib_stats_moment_scalar.fypp \
         stdlib_stats_var.fypp \
         stdlib_math.fypp \
-	stdlib_math_linspace.fypp \
-	stdlib_math_logspace.fypp \
+        stdlib_math_linspace.fypp \
+        stdlib_math_logspace.fypp \
+        stdlib_math_is_close.fypp \
+        stdlib_math_all_close.fypp \
         stdlib_stats_distribution_PRNG.fypp \
         stdlib_string_type.fypp \
         stdlib_string_type_constructor.fypp \
@@ -74,7 +76,8 @@ $(SRCGEN): %.f90: %.fypp common.fypp
 # Fortran module dependencies
 f18estop.o: stdlib_error.o
 stdlib_ascii.o: stdlib_kinds.o
-stdlib_bitsets.o: stdlib_kinds.o
+stdlib_bitsets.o: stdlib_kinds.o \
+    stdlib_optval.o
 stdlib_bitsets_64.o: stdlib_bitsets.o
 stdlib_bitsets_large.o: stdlib_bitsets.o
 stdlib_error.o: stdlib_optval.o
@@ -87,7 +90,8 @@ stdlib_io.o: \
     stdlib_kinds.o \
     stdlib_ascii.o
 stdlib_linalg.o: \
-    stdlib_kinds.o
+    stdlib_kinds.o \
+    stdlib_optval.o
 stdlib_linalg_diag.o: \
     stdlib_linalg.o \
     stdlib_kinds.o
@@ -167,6 +171,11 @@ stdlib_math_logspace.o: \
 stdlib_math_arange.o: \
     stdlib_math.o
 stdlib_linalg_outer_product.o: stdlib_linalg.o
+stdlib_math_is_close.o: \
+    stdlib_math.o
+stdlib_math_all_close.o: \
+    stdlib_math.o \
+    stdlib_math_is_close.o
 stdlib_stringlist_type.o: stdlib_string_type.o \
     stdlib_math.o \
-	stdlib_optval.o
+    stdlib_optval.o

src/stdlib_math.fypp

@@ -11,7 +11,7 @@ module stdlib_math
     public :: clip, gcd, linspace, logspace
     public :: EULERS_NUMBER_SP, EULERS_NUMBER_DP, EULERS_NUMBER_QP
     public :: DEFAULT_LINSPACE_LENGTH, DEFAULT_LOGSPACE_BASE, DEFAULT_LOGSPACE_LENGTH
-    public :: arange
+    public :: arange, is_close, all_close
 
     integer, parameter :: DEFAULT_LINSPACE_LENGTH = 100
     integer, parameter :: DEFAULT_LOGSPACE_LENGTH = 50
@@ -289,6 +289,38 @@ module stdlib_math
         #:endfor
     end interface arange
 
+    !> Version: experimental
+    !>
+    !> Returns a boolean scalar/array where two scalar/arrays are element-wise equal within a tolerance.
+    !> ([Specification](../page/specs/stdlib_logic.html#is_close))
+    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, rel_tol, abs_tol) result(close)
+            ${t1}$, intent(in) :: a, b
+            real(${k1}$), intent(in), optional :: rel_tol, abs_tol
+            logical :: close
+        end function is_close_${t1[0]}$${k1}$
+        #:endfor
+    end interface is_close
+
+    !> Version: experimental
+    !>
+    !> Returns a boolean scalar where two arrays are element-wise equal within a tolerance.
+    !> ([Specification](../page/specs/stdlib_logic.html#all_close))
+    interface all_close
+        #:set RC_KINDS_TYPES = REAL_KINDS_TYPES + CMPLX_KINDS_TYPES
+        #:set RANKS = range(1, MAXRANK + 1)
+        #:for k1, t1 in RC_KINDS_TYPES
+        #:for r1 in RANKS
+        logical pure module function all_close_${r1}$_${t1[0]}$${k1}$(a, b, rel_tol, abs_tol) result(close)
+            ${t1}$, intent(in) :: a${ranksuffix(r1)}$, b${ranksuffix(r1)}$
+            real(${k1}$), intent(in), optional :: rel_tol, abs_tol
+        end function all_close_${r1}$_${t1[0]}$${k1}$
+        #:endfor
+        #:endfor
+    end interface all_close
+
 contains
 
     #:for k1, t1 in IR_KINDS_TYPES

src/stdlib_math_all_close.fypp

@@ -0,0 +1,24 @@
+#:include "common.fypp"
+#:set RANKS = range(1, MAXRANK + 1)
+#:set RC_KINDS_TYPES = REAL_KINDS_TYPES + CMPLX_KINDS_TYPES
+
+submodule (stdlib_math) stdlib_math_all_close
+
+    implicit none
+
+contains
+
+    #:for k1, t1 in RC_KINDS_TYPES
+    #:for r1 in RANKS
+    logical pure module function all_close_${r1}$_${t1[0]}$${k1}$(a, b, rel_tol, abs_tol) result(close)
+
+        ${t1}$, intent(in) :: a${ranksuffix(r1)}$, b${ranksuffix(r1)}$
+        real(${k1}$), intent(in), optional :: rel_tol, abs_tol
+
+        close = all(is_close(a, b, rel_tol, abs_tol))
+
+    end function all_close_${r1}$_${t1[0]}$${k1}$
+    #:endfor
+    #:endfor
+
+end submodule stdlib_math_all_close

src/stdlib_math_arange.fypp

@@ -44,7 +44,7 @@ contains
         step_  = optval(step, 1_${k1}$)
         step_  = sign(merge(step_, 1_${k1}$, step_ /= 0_${k1}$), end_ - start_)
 
-        allocate(result((end_ - start_)/step_ + 1))
+        allocate(result((end_ - start_)/step_ + 1_${k1}$))
 
         result = [(i, i=start_, end_, step_)]
 

src/stdlib_math_is_close.fypp

@@ -0,0 +1,33 @@
+#:include "common.fypp"
+
+submodule(stdlib_math) stdlib_math_is_close
+
+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, rel_tol, abs_tol) result(close)
+        ${t1}$, intent(in) :: a, b
+        real(${k1}$), intent(in), optional :: rel_tol, abs_tol
+        logical :: close
+
+        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, rel_tol, abs_tol) result(close)
+        ${t1}$, intent(in) :: a, b
+        real(${k1}$), intent(in), optional :: rel_tol, abs_tol
+        logical :: close
+
+        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
+
+end submodule stdlib_math_is_close

src/tests/math/CMakeLists.txt

@@ -1,4 +1,6 @@
 ADDTEST(stdlib_math)
 ADDTEST(linspace)
 ADDTEST(logspace)
-ADDTEST(math_arange)
+ADDTEST(math_arange)
+ADDTEST(math_is_close)
+ADDTEST(math_all_close)

src/tests/math/Makefile.manual

@@ -1,5 +1,7 @@
 PROGS_SRC = test_stdlib_math.f90 test_linspace.f90 test_logspace.f90 \
-    test_math_arange.f90
+    test_math_arange.f90 \
+    test_math_is_close.f90 \
+    test_math_all_close.f90
 
 
 include ../Makefile.manual.test.mk