Merge pull request #420 from ejovo13/lin_log_space

First implementation of real-valued linspace.

Author: jvdp1

doc/specs/stdlib_math.md

@@ -19,7 +19,7 @@ title: math
 
 #### Description
 
-Returns a value which lies in the given interval [`xmin`, `xmax`] (interval is `xmin` and `xmax` inclusive) and is closest to the input value `x`.  
+Returns a value which lies in the given interval [`xmin`, `xmax`] (interval is `xmin` and `xmax` inclusive) and is closest to the input value `x`.
 
 #### Syntax
 
@@ -35,8 +35,8 @@ Elemental function.
 
 #### Argument(s)
 
-`x`: scalar of either `integer` or `real` type. This argument is `intent(in)`.  
-`xmin`: scalar of either `integer` or `real` type. This argument is `intent(in)`.  
+`x`: scalar of either `integer` or `real` type. This argument is `intent(in)`.
+`xmin`: scalar of either `integer` or `real` type. This argument is `intent(in)`.
 `xmax`: scalar of either `integer` or `real` type, which must be greater than or equal to `xmin`. This argument is `intent(in)`.
 
 Note: All arguments must have same `type` and same `kind`.
@@ -90,3 +90,188 @@ program demo_clip_real
   ! clipped_value <- 3.02500010
 end program demo_clip_real
 ```
+
+### `linspace` - Create a linearly spaced rank one array
+
+#### Description
+
+Returns a linearly spaced rank 1 array from [`start`, `end`]. Optionally, you can specify the length of the returned array by passing `n`.
+
+#### Syntax
+
+`res = [[stdlib_math(module):linspace(interface)]] (start, end [, n])`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Function.
+
+#### Argument(s)
+
+`start`: Shall be scalar of any numeric type or kind. This argument is `intent(in)`.
+`end`: Shall be the same `type` and `kind` as `start`. This argument is `intent(in)`.
+`n`: Shall be an integer specifying the length of the output. This argument is `optional` and `intent(in)`.
+
+#### Output value or Result value
+
+The output is a rank 1 array whose length is either 100 (default value) or `n`.
+
+If `n` == 1, return a rank 1 array whose only element is `end`.
+If `n` <= 0, return a rank 1 array with length 0.
+
+If `start`/`end` are `real` or `complex` types, the `result` will be of the same type and kind as `start`/`end`.
+If `start`/`end` are `integer` types, the `result` will default to a `real(dp)` array.
+
+#### Examples
+
+##### Example 1:
+
+Here inputs are of type `complex` and kind `dp`
+```fortran
+program demo_linspace_complex
+  use stdlib_math, only: linspace
+  use stdlib_kinds, only: dp
+  implicit none
+
+  complex(dp) :: start = complex(10.0_dp, 5.0_dp)
+  complex(dp) :: end = complex(-10.0_dp, 15.0_dp)
+
+  complex(dp) :: z(11)
+
+  z = linspace(start, end, 11)
+end program demo_linspace_complex
+```
+
+##### Example 2:
+
+Here inputs are of type `integer` and kind `int16`, with the result defaulting to `real(dp)`.
+```fortran
+program demo_linspace_int16
+  use stdlib_math, only: linspace
+  use stdlib_kinds, only: int16, dp
+  implicit none
+
+  integer(int16) :: start = 10_int16
+  integer(int16) :: end = 23_int16
+
+  real(dp) :: r(15)
+
+  r = linspace(start, end, 15)
+end program demo_linspace_int16
+```
+
+### `logspace` - Create a logarithmically spaced rank one array
+
+#### Description
+
+Returns a logarithmically spaced rank 1 array from [`base`^`start`, `base`^`end`]. The default size of the array is 50. Optionally, you can specify the length of the returned array by passing `n`. You can also specify the `base` used to compute the range (default 10).
+
+#### Syntax
+
+`res = [[stdlib_math(module):logspace(interface)]] (start, end [, n [, base]])`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Function.
+
+#### Argument(s)
+
+`start`: Shall be a scalar of any numeric type. All kinds are supported for real and complex arguments. For integers, only the default kind is currently implemented. This argument is `intent(in)`.
+`end`: Shall be the same `type` and `kind` as `start`. This argument is `intent(in)`.
+`n`: Shall be an integer specifying the length of the output. This argument is `optional` and `intent(in)`.
+`base` : Shall be a scalar of any numeric type. All kinds are supported for real and complex arguments. For integers, only the default kind is currently implemented. This argument is `optional` and `intent(in)`.
+
+#### Output value or Result value
+
+The output is a rank 1 array whose length is either 50 (default value) or `n`.
+
+If `n` == 1, return a rank 1 array whose only element is `base`^`end`.
+If `n` <= 0, return a rank 1 array with length 0
+
+The `type` and `kind` of the output is dependent on the `type` and `kind` of the passed parameters.
+
+For function calls where the `base` is not specified: `logspace(start, end)`/`logspace(start, end, n)`, the `type` and `kind` of
+the output follows the same scheme as above for `linspace`.
+>If `start`/`end` are `real` or `complex` types, the `result` will be the same type and kind as `start`/`end`.
+>If `start`/`end` are integer types, the `result` will default to a `real(dp)` array.
+
+For function calls where the `base` is specified, the `type` and `kind` of the result is in accordance with the following table:
+
+| `start`/`end` | `n` | `base` | `output` |
+| ------------- | --- | ------ | -------- |
+| `real(KIND)` | `Integer` | `real(KIND)` | `real(KIND)` |
+| "          " | "       " | `complex(KIND)` | `complex(KIND)` |
+| "          " | "       " | `Integer` | `real(KIND)` |
+| `complex(KIND)` | "       " | `real(KIND)` | `complex(KIND)` |
+| "             " | "       " | `complex(KIND)` | `complex(KIND)` |
+| "             " | "       " | `Integer` | `complex(KIND)` |
+| `Integer` | "        " | `real(KIND)` | `real(KIND)` |
+| "              " | "        " | `complex(KIND)` | `complex(KIND)` |
+| "              " | "        " | `Integer` | `Integer` |
+
+#### Examples
+
+##### Example 1:
+
+Here inputs are of type `complex` and kind `dp`. `n` and `base` is not specified and thus default to 50 and 10, respectively.
+```fortran
+program demo_logspace_complex
+  use stdlib_math, only: logspace
+  use stdlib_kinds, only: dp
+  implicit none
+
+  complex(dp) :: start = (10.0_dp, 5.0_dp)
+  complex(dp) :: end = (-10.0_dp, 15.0_dp)
+
+  complex(dp) :: z(11) ! Complex values raised to complex powers results in complex values
+
+  z = logspace(start, end, 11)
+end program demo_logspace_complex
+```
+
+##### Example 2:
+
+Here inputs are of type `integer` and default kind. `base` is not specified and thus defaults to 10.
+```fortran
+program demo_logspace_int
+  use stdlib_math, only: logspace
+  use stdlib_kinds, only: dp
+  implicit none
+
+  integer :: start = 10
+  integer :: end = 23
+  integer :: n = 15
+
+  real(dp) :: r(n) ! Integer values raised to real powers results in real values
+
+  r = logspace(start, end, n)
+end program demo_logspace_int
+```
+
+##### Example 3:
+
+Here `start`/`end` are of type `real` and double precision. `base` is type `complex` and also double precision.
+```fortran
+program demo_logspace_rstart_cbase
+  use stdlib_math, only: logspace
+  use stdlib_kinds, only: dp
+  implicit none
+
+  real(dp) :: start = 0.0_dp
+  real(dp) :: end = 3.0_dp
+  integer :: n = 4
+  complex(dp) :: base = (0.0_dp, 1.0_dp)
+
+  complex(dp) :: z(n) ! complex values raised to real powers result in complex values
+
+  z = logspace(start, end, n, base)
+
+end program demo_logspace_rstart_cbase
+```

src/CMakeLists.txt

@@ -29,6 +29,8 @@ set(fppFiles
     stdlib_quadrature_simps.fypp
     stdlib_stats_distribution_PRNG.fypp
     stdlib_math.fypp
+    stdlib_math_linspace.fypp
+    stdlib_math_logspace.fypp
     stdlib_string_type.fypp
 )
 

src/Makefile.manual

@@ -25,6 +25,8 @@ SRCFYPP =\
         stdlib_stats_moment_scalar.fypp \
         stdlib_stats_var.fypp \
         stdlib_math.fypp \
+		stdlib_math_linspace.fypp \
+		stdlib_math_logspace.fypp \
         stdlib_stats_distribution_PRNG.fypp \
         stdlib_string_type.fypp
 
@@ -73,6 +75,7 @@ stdlib_error.o: stdlib_optval.o
 stdlib_specialfunctions.o: stdlib_kinds.o
 stdlib_specialfunctions_legendre.o: stdlib_kinds.o stdlib_specialfunctions.o
 stdlib_io.o: \
+	stdlib_ascii.o \
 	stdlib_error.o \
 	stdlib_optval.o \
 	stdlib_kinds.o
@@ -141,4 +144,8 @@ stdlib_strings.o: stdlib_ascii.o \
     stdlib_string_type.o \
 	stdlib_optval.o
 stdlib_math.o: stdlib_kinds.o
+stdlib_math_linspace.o: \
+	stdlib_math.o
+stdlib_math_logspace.o: \
+	stdlib_math_linspace.o
 stdlib_linalg_outer_product.o: stdlib_linalg.o