add is_close/all_close .

Author: zoziha

doc/specs/forlab_io.md

@@ -529,7 +529,7 @@ Prints a line of progress percentage on the screen.
 ```fortran
 program demo_io_progress_perc
 
-    use forlab_strings, only: progress_perc
+    use forlab_io, only: progress_perc
     use forlab_stats, only: randu
     
     do i = 0, 100, 10

doc/specs/forlab_math.md

@@ -6,70 +6,6 @@ title: MATH
 
 [TOC]
 
-### `is_close`
-
-#### 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`.
-
-```fortran
-!> For `real` type
-abs(a - b) <= rtol*abs(b) + atol
-!> For `complex` type
-abs(a%re - b%re) <= rtol*abs(b%re) + atol
-abs(a%im - b%im) <= rtol*abs(b%im) + atol
-```
-
-#### Syntax
-
-`bool = [[forlab_math(module):is_close(interface)]] (a, b [, rtol, atol])`
-
-#### 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)`.
-
-`rtol`: Shall be a `real` scalar.
-This argument is `intent(in)` and `optional`, which is `1.0e-5` by default.
-
-`atol`: Shall be a `real` scalar.
-This argument is `intent(in)` and `optional`, which is `1.0e-8` 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`.
-
-#### Result value
-
-Returns a `logical` scalar/array.
-
-#### Example
-
-```fortran
-program demo_math_is_close
-    use forlab_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 *, all(is_close(x,[real :: 1, 2.1]))!! F
-    print *, is_close(2.0, 2.1, atol=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
-```
-
 ### `arange`
 
 #### Status
@@ -184,4 +120,126 @@ program demo_math_signum
     !>          (0.447213590,-0.894427180)
 
 end program demo_math_signum
+```
+
+
+### `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 forlab_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
+
+Impure 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 forlab_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
 ```

example/math/demo_math_all_close.f90

@@ -0,0 +1,14 @@
+program demo_math_all_close
+    use forlab_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

example/math/demo_math_is_close.f90

@@ -1,10 +1,9 @@
 program demo_math_is_close
-    use forlab_math, only: is_close
+    use forlab_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 *, all(is_close(x,[real :: 1, 2.1]))!! 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

fpm.toml

@@ -1,9 +1,9 @@
 name = "forlab"
 version = "1.0.1"
 license = "MIT"
-author = "forlab contributors"
-maintainer = "https://github.com/fortran-fans/forlab"
-copyright = "2016-2021 forlab contributors"
+author  = "FORLAB contributors"
+maintainer = "@Fortran-Fans/FORALB"
+copyright = "2016-2021 FORLAB contributors"
 description = "A Fortran module that provides a lot of functions for scientific computing"
 categories = ["numerical"]
 keywords = ["numerical", "easy-to-use"]
@@ -79,6 +79,10 @@ name = "math_is_close"
 source-dir = "test/math"
 main = "test_math_is_close.f90"
 [[test]]
+name = "math_all_close"
+source-dir = "test/math"
+main = "test_math_all_close.f90"
+[[test]]
 name = "math_arange"
 source-dir = "test/math"
 main = "test_math_arange.f90"

meta-src/common.fypp

@@ -39,6 +39,8 @@
 #! Default Kinds
 #:set DK = "sp"
 
+#:set MAXRANK = 4
+
 #:def ranksuffix(RANK)
 $:'' if RANK == 0 else '(' + ':' + ',:' * (RANK - 1) + ')'
 #:enddef ranksuffix

meta-src/forlab_math.fypp

@@ -1,5 +1,6 @@
 #:include 'common.fypp'
 module forlab_math
+
     use stdlib_kinds, only: sp, dp, qp, int8, int16, int32, int64
     use stdlib_optval, only: optval
     implicit none
@@ -8,7 +9,9 @@ module forlab_math
     public :: angle
     public :: cosd, sind,tand
     public :: acosd, asind, atand
-    public :: is_close, arange, signum
+    public :: arange, signum
+    
+    public :: is_close, all_close
 
     #:set CIR_NAME=["acos","asin","atan"]
     #:for l1 in CIR_NAME
@@ -47,19 +50,33 @@ module forlab_math
 
     !> Version: experimental
     !>
-    !> Determines whether the values of `a` and `b` are close.
-    !> ([Specification](../page/specs/forlab_logic.html#is_close))
+    !> Returns a boolean scalar/array where two scalar/arrays are element-wise equal within a tolerance.
+    !> ([Specification](../page/specs/forlab_math.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, 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
 
+    !> Version: experimental
+    !>
+    !> Returns a boolean scalar where two arrays are element-wise equal within a tolerance.
+    !> ([Specification](../page/specs/forlab_math.html#all_close))
+    interface all_close
+        #:set RC_KINDS_TYPES = REAL_KINDS_TYPES + CMPLX_KINDS_TYPES
+        #:for k1, t1 in RC_KINDS_TYPES
+        logical module function all_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
+        end function all_close_${t1[0]}$${k1}$
+        #:endfor
+    end interface all_close
+
     !> Version: experimental
     !>
     !> `arange` creates a rank-1 `array` of the `integer/real` type 

meta-src/forlab_math_all_close.fypp

@@ -0,0 +1,42 @@
+#:include "common.fypp"
+#:set RANKS = range(1, MAXRANK + 1)
+#:set RC_KINDS_TYPES = REAL_KINDS_TYPES + CMPLX_KINDS_TYPES
+
+submodule (forlab_math) forlab_math_all_close
+
+    implicit none
+    character(*), parameter :: error_1 = "*<ERROR>* The ranks of `a` and `b` in `all_close` are not equal."
+    character(*), parameter :: error_2 = "*<ERROR>* The rank of `a` in `all_close` is too large to be supported."
+    
+contains
+
+    #:def inrank(r1)
+        rank(${r1}$)
+            select rank(b)
+            rank(${r1}$)
+                close = all(is_close(a, b, rel_tol, abs_tol))
+            rank default
+                error stop error_1
+            end select
+    #:enddef
+
+    #:for k1, t1 in RC_KINDS_TYPES
+    logical module function all_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
+
+        select rank(a)
+
+        #:for r1 in RANKS
+        $:inrank(r1)
+        #:endfor
+
+        rank default
+            error stop error_2
+        end select
+
+    end function all_close_${t1[0]}$${k1}$
+    #:endfor
+
+end submodule forlab_math_all_close