Merge branch 'fortran-lang:master' into sparse

Author: jalvesz

.github/workflows/CI.yml

@@ -169,7 +169,7 @@ jobs:
         cxx: [icpc]
     env:
       MACOS_HPCKIT_URL: >-
-        https://registrationcenter-download.intel.com/akdlm/irc_nas/18242/m_HPCKit_p_2021.4.0.3389_offline.dmg
+        https://registrationcenter-download.intel.com/akdlm/IRC_NAS/a99cb1c5-5af6-4824-9811-ae172d24e594/m_HPCKit_p_2023.1.0.44543.dmg
       MACOS_FORTRAN_COMPONENTS: all
       FC: ${{ matrix.fc }}
       CC: ${{ matrix.cc }}

CHANGELOG.md

@@ -1,3 +1,65 @@
+# Version 0.4.0
+
+Full release notes available at [v0.4.0] tag.
+
+[v0.4.0]: https://github.com/fortran-lang/stdlib/releases/tag/v0.4.0
+
+- new module `stdlib_str2num`
+  [#743](https://github.com/fortran-lang/stdlib/pull/743)
+  - new procedures: `to_num`, `to_num_from_stream`
+
+Changes to existing scripts and modules
+
+- change in .gitignore
+  - addition of the file extensions `.dat` and `.stream`
+    [#768](https://github.com/fortran-lang/stdlib/pull/768)
+  - addition of `.gitignore` to `stdlib-fpm`
+    [#769](https://github.com/fortran-lang/stdlib/pull/769)
+- change in CI/CD
+  - support of GCC 13
+    [#737](https://github.com/fortran-lang/stdlib/pull/737)
+  - support of Intel compiler `ifx`
+    [#752](https://github.com/fortran-lang/stdlib/pull/752)
+- change in script `fpm-deployment.sh`
+  - changes to facilitate `fypp` preprocessing for the `fpm` deployment
+    [#758](https://github.com/fortran-lang/stdlib/pull/758)
+- change in module `stdlib_ascii`
+  - Improved procedures `to_lower` and `to_upper`
+    [#733](https://github.com/fortran-lang/stdlib/pull/733)
+- change in module `stdlib_bitsets`
+  - initialization in `bitset_type`
+    [#753](https://github.com/fortran-lang/stdlib/pull/753)
+  - improved procedure `bit_count_large`
+    [#756](https://github.com/fortran-lang/stdlib/pull/756)
+- change in module `stdlib_hashmaps`
+  - new procedure `get_all_keys`
+    [#741](https://github.com/fortran-lang/stdlib/pull/741)
+  - new file permissions
+    [#762](https://github.com/fortran-lang/stdlib/pull/762)
+- change in module `stdlib_math`
+  - new procedure `meshgrid`
+    [#764](https://github.com/fortran-lang/stdlib/pull/764)
+- change in module `stdlib_specialfunctions_gamma`
+  - fix procedure `gamma`
+    [#730](https://github.com/fortran-lang/stdlib/pull/730)
+- change in module `stdlib_string_type`
+  - fix procedure `move`
+    [#736](https://github.com/fortran-lang/stdlib/pull/736)
+    [#773](https://github.com/fortran-lang/stdlib/pull/773)
+- change in `SpookyV2Test.cpp`
+  - Fix undefined use of <cstdint> types
+    [#747](https://github.com/fortran-lang/stdlib/pull/747)
+
+Changes to the existing documentation
+
+- change in the specs `stdlib_hashmaps`
+  - Correction of an intent of the variable "conflict"
+    [#739](https://github.com/fortran-lang/stdlib/pull/739)
+- change in README.md
+  - instructions to build `stdlib` with `fpm` through the `fpm-deployment.sh` script
+    [#757](https://github.com/fortran-lang/stdlib/pull/757)
+
+
 # Version 0.3.0
 
 Full release notes available at [v0.3.0] tag.

README.md

@@ -92,7 +92,7 @@ GCC Fortran | 10, 11, 12, 13 | macOS 12.6.3 (21G419) | x86_64
 GCC Fortran (MSYS) | 13 | Windows Server 2022 (10.0.20348 Build 1547) | x86_64
 GCC Fortran (MinGW) | 13 | Windows Server 2022 (10.0.20348 Build 1547) | x86_64, i686
 Intel oneAPI LLVM | 2024.0 | Ubuntu 22.04.2 LTS | x86_64
-Intel oneAPI classic | 2021.1 | macOS 12.6.3 (21G419) | x86_64
+Intel oneAPI classic | 2023.1 | macOS 12.6.3 (21G419) | x86_64
 
 The following combinations are known to work, but they are not tested in the CI:
 

VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

doc/specs/stdlib_math.md

@@ -554,3 +554,59 @@ When both `prepend` and `append` are not present, the result `y` has one fewer e
 ```fortran
 {!example/math/example_diff.f90!}
 ```
+
+### `meshgrid` subroutine
+
+#### Description
+
+Computes a list of coordinate matrices from coordinate vectors.
+
+For $n \geq 1$ coordinate vectors $(x_1, x_2, ..., x_n)$ of sizes $(s_1, s_2, ..., s_n)$, `meshgrid` computes $n$ coordinate matrices $(X_1, X_2, ..., X_n)$ with identical shape corresponding to the selected indexing:
+- Cartesian indexing (default behavior): the shape of the coordinate matrices is $(s_2, s_1, s_3, s_4, ... s_n)$.
+- matrix indexing: the shape of the coordinate matrices is $(s_1, s_2, s_3, s_4, ... s_n)$.
+
+#### Syntax
+
+For a 2D problem in Cartesian indexing:
+`call [[stdlib_math(module):meshgrid(interface)]](x, y, xm, ym)`
+
+For a 3D problem in Cartesian indexing:
+`call [[stdlib_math(module):meshgrid(interface)]](x, y, z, xm, ym, zm)`
+
+For a 3D problem in matrix indexing:
+`call [[stdlib_math(module):meshgrid(interface)]](x, y, z, xm, ym, zm, indexing="ij")`
+
+The subroutine can be called in `n`-dimensional situations, as long as `n` is inferior to the maximum allowed array rank.
+
+#### Status
+
+Experimental.
+
+#### Class
+
+Subroutine.
+
+#### Arguments
+
+For a `n`-dimensional problem, with `n >= 1`:
+
+`x1, x2, ..., xn`: The coordinate vectors.
+Shall be `real/integer` and `rank-1` arrays.
+These arguments are `intent(in)`.
+
+`xm1, xm2, ..., xmn`: The coordinate matrices.
+Shall be arrays of type `real` or `integer` of adequate shape:
+- for Cartesian indexing, the shape of the coordinate matrices must be `[size(x2), size(x1), size(x3), ..., size(xn)]`.
+- for matrix indexing, the shape of the coordinate matrices must be `[size(x1), size(x2), size(x3), ..., size(xn)]`.
+
+These argument are `intent(out)`.
+
+`indexing`: the selected indexing.
+Shall be an `integer` equal to `stdlib_meshgrid_xy` for Cartesian indexing (default), or `stdlib_meshgrid_ij` for matrix indexing. `stdlib_meshgrid_xy` and `stdlib_meshgrid_ij` are public constants defined in the module.
+This argument is `intent(in)` and `optional`, and is equal to `stdlib_meshgrid_xy` by default.
+
+#### Example
+
+```fortran
+{!example/math/example_meshgrid.f90!}
+```

example/math/CMakeLists.txt

@@ -13,3 +13,4 @@ ADD_EXAMPLE(math_argd)
 ADD_EXAMPLE(math_arg)
 ADD_EXAMPLE(math_argpi)
 ADD_EXAMPLE(math_is_close)
+ADD_EXAMPLE(meshgrid)

example/math/example_meshgrid.f90

@@ -0,0 +1,37 @@
+program example_meshgrid
+
+    use stdlib_math, only: meshgrid, linspace, stdlib_meshgrid_ij
+    use stdlib_kinds, only: sp
+
+    implicit none
+
+    integer, parameter :: nx = 3, ny = 2
+    real(sp) :: x(nx), y(ny), &
+            xm_cart(ny, nx), ym_cart(ny, nx), &
+            xm_mat(nx, ny), ym_mat(nx, ny)
+
+    x = linspace(0_sp, 1_sp, nx)
+    y = linspace(0_sp, 1_sp, ny)
+
+    call meshgrid(x, y, xm_cart, ym_cart)
+    print *, "xm_cart = "
+    call print_2d_array(xm_cart)
+    print *, "ym_cart = "
+    call print_2d_array(ym_cart)
+
+    call meshgrid(x, y, xm_mat, ym_mat, indexing=stdlib_meshgrid_ij)
+    print *, "xm_mat = "
+    call print_2d_array(xm_mat)
+    print *, "ym_mat = "
+    call print_2d_array(ym_mat)
+
+contains
+    subroutine print_2d_array(array)
+        real(sp), intent(in) :: array(:, :)
+        integer :: i
+
+        do i = 1, size(array, dim=1)
+            print *, array(i, :)
+        end do
+    end subroutine
+end program example_meshgrid

src/CMakeLists.txt

@@ -58,6 +58,7 @@ set(fppFiles
     stdlib_math_is_close.fypp
     stdlib_math_all_close.fypp
     stdlib_math_diff.fypp
+    stdlib_math_meshgrid.fypp
     stdlib_str2num.fypp
     stdlib_string_type.fypp
     stdlib_string_type_constructor.fypp

src/stdlib_math.fypp

@@ -14,7 +14,8 @@ module stdlib_math
     public :: EULERS_NUMBER_QP
 #:endif
     public :: DEFAULT_LINSPACE_LENGTH, DEFAULT_LOGSPACE_BASE, DEFAULT_LOGSPACE_LENGTH
-    public :: arange, arg, argd, argpi, is_close, all_close, diff
+    public :: stdlib_meshgrid_ij, stdlib_meshgrid_xy
+    public :: arange, arg, argd, argpi, is_close, all_close, diff, meshgrid
 
     integer, parameter :: DEFAULT_LINSPACE_LENGTH = 100
     integer, parameter :: DEFAULT_LOGSPACE_LENGTH = 50
@@ -32,6 +33,9 @@ module stdlib_math
     real(kind=${k1}$), parameter :: PI_${k1}$ = acos(-1.0_${k1}$)
     #:endfor
 
+    !> Values for optional argument `indexing` of `meshgrid`
+    integer, parameter :: stdlib_meshgrid_xy = 0, stdlib_meshgrid_ij = 1
+
     interface clip
     #:for k1, t1 in IR_KINDS_TYPES
         module procedure clip_${k1}$
@@ -382,6 +386,30 @@ module stdlib_math
         #:endfor
     end interface diff
 
+
+    !> Version: experimental
+    !>
+    !> Computes a list of coordinate matrices from coordinate vectors.
+    !> ([Specification](../page/specs/stdlib_math.html#meshgrid))
+    interface meshgrid
+        #:set RANKS = range(1, MAXRANK + 1)
+        #:for k1, t1 in IR_KINDS_TYPES
+        #:for rank in RANKS
+        #:set RName = rname("meshgrid", rank, t1, k1)
+        module subroutine ${RName}$(&
+                ${"".join(f"x{i}, " for i in range(1, rank + 1))}$ &
+                ${"".join(f"xm{i}, " for i in range(1, rank + 1))}$ &
+                indexing &
+        )
+            #:for i in range(1, rank + 1)
+            ${t1}$, intent(in) :: x${i}$(:)
+            ${t1}$, intent(out) :: xm${i}$ ${ranksuffix(rank)}$
+            #:endfor
+            integer, intent(in), optional :: indexing
+        end subroutine ${RName}$
+        #:endfor
+        #:endfor
+    end interface meshgrid
 contains
 
     #:for k1, t1 in IR_KINDS_TYPES

src/stdlib_math_meshgrid.fypp

@@ -0,0 +1,50 @@
+#:include "common.fypp"
+#:set IR_KINDS_TYPES = INT_KINDS_TYPES + REAL_KINDS_TYPES
+#:set RANKS = range(1, MAXRANK + 1)
+
+#:def meshgrid_loop(indices)
+  #:for j in reversed(indices)
+  do i${j}$ = 1, size(x${j}$)
+  #:endfor
+  #:for j in indices
+  xm${j}$(${"".join(f"i{j}," for j in indices).removesuffix(",")}$) = &
+          x${j}$(i${j}$)
+  #:endfor
+  #:for j in indices
+  end do
+  #:endfor
+#:enddef
+
+submodule(stdlib_math) stdlib_math_meshgrid
+
+    use stdlib_error, only: error_stop
+
+contains
+
+    #:for k1, t1 in IR_KINDS_TYPES
+    #:for rank in RANKS
+    #:if rank == 1
+      #:set XY_INDICES = [1]
+      #:set IJ_INDICES = [1]
+    #:else
+      #:set XY_INDICES = [2, 1] + [j for j in range(3, rank + 1)]
+      #:set IJ_INDICES = [1, 2] + [j for j in range(3, rank + 1)]
+    #:endif
+    #: set RName = rname("meshgrid", rank, t1, k1)
+    module procedure ${RName}$
+
+        integer :: ${"".join(f"i{j}," for j in range(1, rank + 1)).removesuffix(",")}$
+
+        select case (optval(indexing, stdlib_meshgrid_xy))
+        case (stdlib_meshgrid_xy)
+            $:meshgrid_loop(XY_INDICES)
+        case (stdlib_meshgrid_ij)
+            $:meshgrid_loop(IJ_INDICES)
+        case default
+            call error_stop("ERROR (meshgrid): unexpected indexing.")
+        end select
+    end procedure
+    #:endfor
+    #:endfor
+
+end submodule