Merge pull request #624 from zoziha/minor_update

[stdlib_math] Minor update to `stdlib_math` module and document

Author: jvdp1

API-doc-FORD-file.md

@@ -2,6 +2,7 @@
 project: Fortran-lang/stdlib
 summary: A community driven standard library for (modern) Fortran
 src_dir: src
+include: src
 exclude_dir: src/tests
 output_dir: API-doc
 page_dir: doc

CHANGELOG.md

@@ -52,6 +52,9 @@ Changes to existing modules
 - change in module `stdlib_io`
   - Modified format constants, and made public
   [#617](https://github.com/fortran-lang/stdlib/pull/617)
+- change in module `stdlib_math`
+    - Minor update to `stdlib_math` module and document
+    [#624](https://github.com/fortran-lang/stdlib/pull/624)
 
 
 # Version 0.1.0

doc/specs/stdlib_math.md

@@ -320,7 +320,7 @@ program demo_logspace_rstart_cbase
 
 end program demo_logspace_rstart_cbase
 ```
-### `arange`
+### `arange` function
 
 #### Status
 
@@ -332,7 +332,7 @@ Pure function.
 
 #### Description
 
-Creates a one-dimensional `array` of the `integer/real` type with fixed-spaced values of given spacing, within a given interval.
+Creates a rank-1 `array` of the `integer/real` type with fixed-spaced values of given spacing, within a given interval.
 
 #### Syntax
 
@@ -360,7 +360,7 @@ If `step < 0`, the `step` argument will be corrected to `abs(step)` by the inter
 
 #### Return value
 
-Returns a one-dimensional `array` of fixed-spaced values.
+Returns a rank-1 `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`.
@@ -371,25 +371,25 @@ For `real` type arguments, the length of the result vector is `floor((end - star
 program demo_math_arange
     use stdlib_math, only: arange
 
-    print *, arange(3)                 !! [1,2,3]
-    print *, arange(-1)                !! [1,0,-1]
-    print *, arange(0,2)               !! [0,1,2]
-    print *, arange(1,-1)              !! [1,0,-1]
-    print *, arange(0, 2, 2)           !! [0,2]
+    print *, arange(3)                 ! [1,2,3]
+    print *, arange(-1)                ! [1,0,-1]
+    print *, arange(0,2)               ! [0,1,2]
+    print *, arange(1,-1)              ! [1,0,-1]
+    print *, arange(0, 2, 2)           ! [0,2]
 
-    print *, arange(3.0)               !! [1.0,2.0,3.0]
-    print *, arange(0.0,5.0)           !! [0.0,1.0,2.0,3.0,4.0,5.0]
-    print *, arange(0.0,6.0,2.5)       !! [0.0,2.5,5.0]
+    print *, arange(3.0)               ! [1.0,2.0,3.0]
+    print *, arange(0.0,5.0)           ! [0.0,1.0,2.0,3.0,4.0,5.0]
+    print *, arange(0.0,6.0,2.5)       ! [0.0,2.5,5.0]
 
-    print *, (1.0,1.0)*arange(3)       !! [(1.0,1.0),(2.0,2.0),[3.0,3.0]]
+    print *, (1.0,1.0)*arange(3)       ! [(1.0,1.0),(2.0,2.0),[3.0,3.0]]
 
-    print *, arange(0.0,2.0,-2.0)      !! [0.0,2.0].     Not recommended: `step` argument is negative!
-    print *, arange(0.0,2.0,0.0)       !! [0.0,1.0,2.0]. Not recommended: `step` argument is zero!
+    print *, arange(0.0,2.0,-2.0)      ! [0.0,2.0].     Not recommended: `step` argument is negative!
+    print *, arange(0.0,2.0,0.0)       ! [0.0,1.0,2.0]. Not recommended: `step` argument is zero!
 
 end program demo_math_arange
 ```
 
-### `arg` - Computes the phase angle in radian of a complex scalar
+### `arg` function
 
 #### Status
 
@@ -424,13 +424,14 @@ Notes: Although the angle of the complex number `0` is undefined, `arg((0,0))` r
 ```fortran
 program demo_math_arg
     use stdlib_math, only: arg
-    print *, arg((0.0, 0.0))                  !! 0.0
-    print *, arg((3.0, 4.0))                  !! 0.927
-    print *, arg(2.0*exp((0.0, 0.5)))         !! 0.5
+    print *, arg((0.0, 0.0))                  ! 0.0
+    print *, arg((3.0, 4.0))                  ! 0.927
+    print *, arg(2.0*exp((0.0, 0.5)))         ! 0.5
+    print *, arg([(0.0, 1.0), (1.0, 0.0), (0.0, -1.0), (-1.0, 0.0)])  ! [π/2, 0.0, -π/2, π]
 end program demo_math_arg
 ```
 
-### `argd` - Computes the phase angle in degree of a complex scalar
+### `argd` function
 
 #### Status
 
@@ -465,13 +466,14 @@ Notes: Although the angle of the complex number `0` is undefined, `argd((0,0))`
 ```fortran
 program demo_math_argd
     use stdlib_math, only: argd
-    print *, argd((0.0, 0.0))                  !! 0.0
-    print *, argd((3.0, 4.0))                  !! 53.1°
-    print *, argd(2.0*exp((0.0, 0.5)))         !! 28.64°
+    print *, argd((0.0, 0.0))                  ! 0.0°
+    print *, argd((3.0, 4.0))                  ! 53.1°
+    print *, argd(2.0*exp((0.0, 0.5)))         ! 28.64°
+    print *, argd([(0.0, 1.0), (1.0, 0.0), (0.0, -1.0), (-1.0, 0.0)])  ! [90°, 0°, -90°, 180°]
 end program demo_math_argd
 ```
 
-### `argpi` - Computes the phase angle in circular of a complex scalar
+### `argpi` function
 
 #### Status
 
@@ -506,13 +508,14 @@ Notes: Although the angle of the complex number `0` is undefined, `argpi((0,0))`
 ```fortran
 program demo_math_argpi
     use stdlib_math, only: argpi
-    print *, argpi((0.0, 0.0))                  !! 0.0
-    print *, argpi((3.0, 4.0))                  !! 0.295
-    print *, argpi(2.0*exp((0.0, 0.5)))         !! 0.159
+    print *, argpi((0.0, 0.0))                  ! 0.0
+    print *, argpi((3.0, 4.0))                  ! 0.295
+    print *, argpi(2.0*exp((0.0, 0.5)))         ! 0.159
+    print *, argpi([(0.0, 1.0), (1.0, 0.0), (0.0, -1.0), (-1.0, 0.0)])  ! [0.5, 0.0, -0.5, 1.0]
 end program demo_math_argpi
 ```
 
-### `is_close`
+### `is_close` function
 
 #### Description
 
@@ -577,15 +580,15 @@ program demo_math_is_close
     y   = -3
     NAN = sqrt(y)
     
-    print *, is_close(x,[real :: 1, 2.1])       !! [T, F]
-    print *, is_close(2.0, 2.1, abs_tol=0.1)    !! T
-    print *, NAN, is_close(2.0, NAN), is_close(2.0, NAN, equal_nan=.true.)   !! NAN, F, F
-    print *, is_close(NAN, NAN), is_close(NAN, NAN, equal_nan=.true.)        !! F, T
+    print *, is_close(x,[real :: 1, 2.1])       ! [T, F]
+    print *, is_close(2.0, 2.1, abs_tol=0.1)    ! T
+    print *, NAN, is_close(2.0, NAN), is_close(2.0, NAN, equal_nan=.true.)   ! NAN, F, F
+    print *, is_close(NAN, NAN), is_close(NAN, NAN, equal_nan=.true.)        ! F, T
         
 end program demo_math_is_close
 ```
 
-### `all_close`
+### `all_close` function
 
 #### Description
 
@@ -643,29 +646,26 @@ program demo_math_all_close
     NAN = sqrt(y)
     z   = (1.0, 1.0)
     
-    print *, all_close(z+cmplx(1.0e-11, 1.0e-11), z)     !! T
+    print *, all_close(z+cmplx(1.0e-11, 1.0e-11), z)     ! T
     print *, NAN, all_close([NAN], [NAN]), all_close([NAN], [NAN], equal_nan=.true.) 
-                                                         !! NAN, F, T
+                                                         ! NAN, F, T
     
 end program demo_math_all_close
 ```
 
-### `diff`
+### `diff` function
 
 #### Description
 
 Computes differences between adjacent elements of an array.
 
 #### Syntax
 
-For a rank-1 array
-```fortran
-y = [[stdlib_math(module):diff(interface)]](x [, n, prepend, append])
-```
-and for a rank-2 array
-```fortran
-y = [[stdlib_math(module):diff(interface)]](x [, n, dim, prepend, append])
-```
+For a rank-1 array:  
+`y = [[stdlib_math(module):diff(interface)]](x [, n, prepend, append])`
+
+and for a rank-2 array:  
+`y = [[stdlib_math(module):diff(interface)]](x [, n, dim, prepend, append])`
 
 #### Status
 
@@ -696,8 +696,9 @@ Shall be a `real/integer` and `rank-1/rank-2` array.
 This argument is `intent(in)` and `optional`, which is no value by default.
 
 Note: 
-- The `x`, `prepend` and `append` arguments must have the same `type`, `kind` and `rank`.
-- If the value of `n` is less than or equal to `0` (which is not recommended), the return value of `diff` is `x`.
+
+- The `x`, `prepend` and `append` arguments must have the same `type`, `kind` and `rank`.  
+- If the value of `n` is less than or equal to `0` (which is not recommended), the return value of `diff` is `x`.  
 - If the value of `dim` is not equal to `1` or `2` (which is not recommended),
 `1` will be used by the internal process of `diff`.
 

src/stdlib_math.fypp

@@ -287,7 +287,7 @@ module stdlib_math
     !>
     !> `arange` creates a one-dimensional `array` of the `integer/real` type 
     !>  with fixed-spaced values of given spacing, within a given interval.
-    !> ([Specification](../page/specs/stdlib_math.html#arange))
+    !> ([Specification](../page/specs/stdlib_math.html#arange-function))
     interface arange
         #:set RI_KINDS_TYPES = REAL_KINDS_TYPES + INT_KINDS_TYPES
         #:for k1, t1 in RI_KINDS_TYPES
@@ -302,7 +302,7 @@ module stdlib_math
     !> Version: experimental
     !>
     !> `arg` computes the phase angle in the interval (-π,π].
-    !> ([Specification](../page/specs/stdlib_math.html#arg))
+    !> ([Specification](../page/specs/stdlib_math.html#arg-function))
     interface arg
         #:for k1 in CMPLX_KINDS
         procedure :: arg_${k1}$
@@ -312,7 +312,7 @@ module stdlib_math
     !> Version: experimental
     !>
     !> `argd` computes the phase angle of degree version in the interval (-180.0,180.0].
-    !> ([Specification](../page/specs/stdlib_math.html#argd))
+    !> ([Specification](../page/specs/stdlib_math.html#argd-function))
     interface argd
         #:for k1 in CMPLX_KINDS
         procedure :: argd_${k1}$
@@ -322,15 +322,15 @@ module stdlib_math
     !> Version: experimental
     !>
     !> `argpi` computes the phase angle of circular version in the interval (-1.0,1.0].
-    !> ([Specification](../page/specs/stdlib_math.html#argpi))
+    !> ([Specification](../page/specs/stdlib_math.html#argpi-function))
     interface argpi
         #:for k1 in CMPLX_KINDS
         procedure :: argpi_${k1}$
         #:endfor
     end interface argpi
 
     !> Returns a boolean scalar/array where two scalar/arrays are element-wise equal within a tolerance.
-    !> ([Specification](../page/specs/stdlib_math.html#is_close))
+    !> ([Specification](../page/specs/stdlib_math.html#is_close-function))
     interface is_close
         #:set RC_KINDS_TYPES = REAL_KINDS_TYPES + CMPLX_KINDS_TYPES
         #:for k1, t1 in RC_KINDS_TYPES
@@ -345,7 +345,7 @@ module stdlib_math
     !> Version: experimental
     !>
     !> Returns a boolean scalar where two arrays are element-wise equal within a tolerance.
-    !> ([Specification](../page/specs/stdlib_math.html#all_close))
+    !> ([Specification](../page/specs/stdlib_math.html#all_close-function))
     interface all_close
         #:set RC_KINDS_TYPES = REAL_KINDS_TYPES + CMPLX_KINDS_TYPES
         #:set RANKS = range(1, MAXRANK + 1)
@@ -363,7 +363,7 @@ module stdlib_math
     !> Version: experimental
     !>
     !> Computes differences between adjacent elements of an array.
-    !> ([Specification](../page/specs/stdlib_math.html#diff))
+    !> ([Specification](../page/specs/stdlib_math.html#diff-function))
     interface diff
         #:set RI_KINDS_TYPES = REAL_KINDS_TYPES + INT_KINDS_TYPES
         #:for k1, t1 in RI_KINDS_TYPES
@@ -409,17 +409,18 @@ contains
         ${t1}$, intent(in) :: z
         real(${k1}$) :: result
 
-        result = merge(0.0_${k1}$, atan2(z%im, z%re), z == (0.0_${k1}$, 0.0_${k1}$)) &
-                 *180.0_${k1}$/PI_${k1}$
+        result = merge(0.0_${k1}$, atan2(z%im, z%re)*180.0_${k1}$/PI_${k1}$, &
+                 z == (0.0_${k1}$, 0.0_${k1}$))
 
     end function argd_${k1}$
 
     elemental function argpi_${k1}$(z) result(result) 
         ${t1}$, intent(in) :: z
         real(${k1}$) :: result
 
-        result = merge(0.0_${k1}$, atan2(z%im, z%re), z == (0.0_${k1}$, 0.0_${k1}$)) &
-                 /PI_${k1}$
+        result = merge(0.0_${k1}$, atan2(z%im, z%re)/PI_${k1}$, &
+                 z == (0.0_${k1}$, 0.0_${k1}$))
+                 
 
     end function argpi_${k1}$
     #:endfor

src/tests/math/CMakeLists.txt

@@ -7,4 +7,3 @@ fypp_f90("${fyppFlags}" "${fppFiles}" outFiles)
 ADDTEST(stdlib_math)
 ADDTEST(linspace)
 ADDTEST(logspace)
-ADDTEST(math_arange)

src/tests/math/Makefile.manual

@@ -3,7 +3,6 @@ SRCFYPP = \
 SRCGEN = $(SRCFYPP:.fypp=.f90)
 
 PROGS_SRC = test_linspace.f90 test_logspace.f90 \
-            test_math_arange.f90 \
             $(SRCGEN)
 
 $(SRCGEN): %.f90: %.fypp ../../common.fypp