refactor spmv as submodule to keep parameters private, rework specs

Author: jalvesz

doc/specs/stdlib_sparse.md

@@ -24,19 +24,19 @@ The parent `sparse_type` is as an abstract derived type holding the basic common
 ```Fortran
 type, public, abstract :: sparse_type
     integer :: nrows   !! number of rows
-    integer :: ncols   !> number of columns
-    integer :: nnz     !> number of non-zero values
-    integer :: storage !> assumed storage symmetry
+    integer :: ncols   !! number of columns
+    integer :: nnz     !! number of non-zero values
+    integer :: storage !! assumed storage symmetry
 end type
 ```
 
 The storage integer label should be assigned from the module's internal enumerator containing the following three enums:
 
 ```Fortran
 enum, bind(C)
-    enumerator :: sparse_full  !> Full Sparse matrix (no symmetry considerations)
-    enumerator :: sparse_lower !> Symmetric Sparse matrix with triangular inferior storage
-    enumerator :: sparse_upper !> Symmetric Sparse matrix with triangular supperior storage
+    enumerator :: sparse_full  !! Full Sparse matrix (no symmetry considerations)
+    enumerator :: sparse_lower !! Symmetric Sparse matrix with triangular inferior storage
+    enumerator :: sparse_upper !! Symmetric Sparse matrix with triangular supperior storage
 end enum
 ```
 In the following, all sparse kinds will be presented in two main flavors: a data-less type `<matrix>_type` useful for topological graph operations. And real/complex valued types `<matrix>_<kind>` containing the `data` buffer for the matrix values. The following rectangular matrix will be used to showcase how each sparse matrix holds the data internally:
@@ -135,14 +135,14 @@ Experimental
 The Sliced ELLPACK format `SELLC` is a variation of the `ELLPACK` format. This modification reduces the storage size compared to the `ELLPACK` format but maintaining its efficient data access scheme. It can be seen as an intermediate format between `CSR` and `ELLPACK`. For more details read [the reference](https://arxiv.org/pdf/1307.6209v1)
 
 <!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
-## `add`/`at` - Sparse Matrix data accessors
+## `add`- sparse matrix data accessors
 
 ### Status
 
 Experimental
 
 ### Description
-Type-bound procedures to enable adding or requesting data in/from a sparse matrix.
+Type-bound procedures to enable adding data in a sparse matrix.
 
 ### Syntax
 
@@ -151,19 +151,32 @@ Type-bound procedures to enable adding or requesting data in/from a sparse matri
 
 ### Arguments
 
-`i`, `intent(in)`: Shall be an integer value or rank-1 array.
-`j`, `intent(in)`: Shall be an integer value or rank-1 array.
-`v`, `intent(in)`: Shall be a `real` or `complex` value or rank-2 array. The type shall be in accordance to the declared sparse matrix object.
+`i`: Shall be an integer value or rank-1 array. It is an `intent(in)` argument.
+
+`j`: Shall be an integer value or rank-1 array. It is an `intent(in)` argument.
+
+`v`: Shall be a `real` or `complex` value or rank-2 array. The type shall be in accordance to the declared sparse matrix object. It is an `intent(in)` argument.
+
+## `at`- sparse matrix data accessors
+
+### Status
+
+Experimental
+
+### Description
+Type-bound procedures to enable requesting data from a sparse matrix.
 
 ### Syntax
 
 `v = matrix%at(i,j)`
 
 ### Arguments
 
-`i`, `intent(in)` : Shall be an integer value.
-`j`, `intent(in)` : Shall be an integer value.
-`v`, `result`     : Shall be a `real` or `complex` value in accordance to the declared sparse matrix object. If the `ij` tuple is within the sparse pattern, `v` contains the value in the data buffer. If the `ij` tuple is outside the sparse pattern, `v` is equal `0`. If the `ij` tuple is outside the matrix pattern `(nrows,ncols)`, `v` is `NaN`.
+`i` : Shall be an integer value. It is an `intent(in)` argument.
+
+`j` : Shall be an integer value. It is an `intent(in)` argument.
+
+`v` : Shall be a `real` or `complex` value in accordance to the declared sparse matrix object. If the `ij` tuple is within the sparse pattern, `v` contains the value in the data buffer. If the `ij` tuple is outside the sparse pattern, `v` is equal `0`. If the `ij` tuple is outside the matrix pattern `(nrows,ncols)`, `v` is `NaN`.
 
 ## Example
 ```fortran
@@ -189,18 +202,18 @@ $$y=\alpha*M*x+\beta*y$$
 
 ### Arguments
 
-`matrix`, `intent(in)`: Shall be a `real` or `complex` sparse type matrix.
+`matrix`: Shall be a `real` or `complex` sparse type matrix. It is an `intent(in)` argument.
 
-`vec_x`, `intent(in)`: Shall be a rank-1 or rank-2 array of `real` or `complex` type array.
+`vec_x`: Shall be a rank-1 or rank-2 array of `real` or `complex` type array. It is an `intent(in)` argument.
 
-`vec_y`, `intent(inout)`: Shall be a rank-1 or rank-2 array of `real` or `complex` type array.
+`vec_y`: Shall be a rank-1 or rank-2 array of `real` or `complex` type array. . It is an `intent(inout)` argument.
 
-`alpha`, `intent(in)`, `optional` : Shall be a scalar value of the same type as `vec_x`. Default value `alpha=1`.
+`alpha`, `optional` : Shall be a scalar value of the same type as `vec_x`. Default value `alpha=1`. It is an `intent(in)` argument.
 
-`beta`, `intent(in)`, `optional` : Shall be a scalar value of the same type as `vec_x`. Default value `beta=0`.
+`beta`, `optional` : Shall be a scalar value of the same type as `vec_x`. Default value `beta=0`. It is an `intent(in)` argument.
 
 <!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
-## `sparse_conversion` - Sparse matrix to matrix conversions
+## Sparse matrix to matrix conversions
 
 ### Status
 
@@ -212,35 +225,35 @@ This module provides facility functions for converting between storage formats.
 
 ### Syntax
 
-`call ` [[stdlib_sparse_conversion(module):coo2ordered(interface)]] `(coo)`
+`call ` [[stdlib_sparse_conversion(module):coo2ordered(interface)]] `(coo[,sort_data])`
 
 ### Arguments
 
-`COO`, `intent(inout)`: Shall be any `COO` type. The same object will be returned with the arrays reallocated to the correct size after removing duplicates.
+`COO` : Shall be any `COO` type. The same object will be returned with the arrays reallocated to the correct size after removing duplicates. It is an `intent(inout)` argument.
 
-`sort_data`, `logical(in)`, `optional`:: Shall be an optional `logical` argument to determine whether data in the COO graph should be sorted while sorting the index array, default `.false.`.
+`sort_data`, `optional` : Shall be a `logical` argument to determine whether data in the COO graph should be sorted while sorting the index array, default `.false.`. It is an `intent(in)` argument.
 
 ### Syntax
 
 `call ` [[stdlib_sparse_conversion(module):from_ijv(interface)]] `(sparse,row,col[,data,nrows,ncols,num_nz_rows,chunk])`
 
 ### Arguments
 
-`sparse`, `intent(inout)`: Shall be a `COO`, `CSR`, `ELL` or `SELLC` type. The graph object will be returned with a canonical shape after sorting and removing duplicates from the `(row,col,data)` triplet. If the graph is `COO_type` no data buffer is allowed.
+`sparse` : Shall be a `COO`, `CSR`, `ELL` or `SELLC` type. The graph object will be returned with a canonical shape after sorting and removing duplicates from the `(row,col,data)` triplet. If the graph is `COO_type` no data buffer is allowed. It is an `intent(inout)` argument.
 
-`row`, `integer(in)`:: rows index array.
+`row` : rows index array. It is an `intent(in)` argument.
 
-`col`, `integer(in)`:: columns index array.
+`col` : columns index array. It is an `intent(in)` argument.
 
-`data`, `real/complex(in)`, `optional`:: `real` or `complex` data array.
+`data`, `optional`: `real` or `complex` data array. It is an `intent(in)` argument.
 
-`nrows`, `integer(in)`, `optional`:: number of rows, if not given it will be computed from the `row` array.
+`nrows`, `optional`: number of rows, if not given it will be computed from the `row` array. It is an `intent(in)` argument.
 
-`ncols`, `integer(in)`, `optional`:: number of columns, if not given it will be computed from the `col` array.
+`ncols`, `optional`: number of columns, if not given it will be computed from the `col` array. It is an `intent(in)` argument.
 
-`num_nz_rows`, `integer(in)`, `optional`:: number of non zeros per row, only valid in the case of an `ELL` matrix, by default it will computed from the largest row.
+`num_nz_rows`, `optional`: number of non zeros per row, only valid in the case of an `ELL` matrix, by default it will computed from the largest row. It is an `intent(in)` argument.
 
-`chunk`, `integer(in)`, `optional`:: chunk size, only valid in the case of a `SELLC` matrix, by default it will be taken from the `SELLC` default attribute chunk size.
+`chunk`, `optional`: chunk size, only valid in the case of a `SELLC` matrix, by default it will be taken from the `SELLC` default attribute chunk size. It is an `intent(in)` argument.
 
 ## Example
 ```fortran
@@ -253,51 +266,51 @@ This module provides facility functions for converting between storage formats.
 
 ### Arguments
 
-`dense`, `intent(in)`: Shall be a rank-2 array of `real` or `complex` type.
+`dense` : Shall be a rank-2 array of `real` or `complex` type. It is an `intent(in)` argument.
 
-`coo`, `intent(inout)`: Shall be a `COO` type of `real` or `complex` type.
+`coo` : Shall be a `COO` type of `real` or `complex` type. It is an `intent(out)` argument.
 
 ### Syntax
 
 `call ` [[stdlib_sparse_conversion(module):coo2dense(interface)]] `(coo,dense)`
 
 ### Arguments
 
-`coo`, `intent(in)`: Shall be a `COO` type of `real` or `complex` type.
+`coo` : Shall be a `COO` type of `real` or `complex` type. It is an `intent(in)` argument.
 
-`dense`, `intent(inout)`: Shall be a rank-2 array of `real` or `complex` type.
+`dense` : Shall be a rank-2 array of `real` or `complex` type. It is an `intent(out)` argument.
 
 ### Syntax
 
 `call ` [[stdlib_sparse_conversion(module):coo2csr(interface)]] `(coo,csr)`
 
 ### Arguments
 
-`coo`, `intent(in)`: Shall be a `COO` type of `real` or `complex` type.
+`coo` : Shall be a `COO` type of `real` or `complex` type. It is an `intent(in)` argument.
 
-`csr`, `intent(inout)`: Shall be a `CSR` type of `real` or `complex` type.
+`csr` : Shall be a `CSR` type of `real` or `complex` type. It is an `intent(out)` argument.
 
 ### Syntax
 
 `call ` [[stdlib_sparse_conversion(module):csr2coo(interface)]] `(csr,coo)`
 
 ### Arguments
 
-`csr`, `intent(in)`: Shall be a `CSR` type of `real` or `complex` type.
+`csr` : Shall be a `CSR` type of `real` or `complex` type. It is an `intent(in)` argument.
 
-`coo`, `intent(inout)`: Shall be a `COO` type of `real` or `complex` type.
+`coo` : Shall be a `COO` type of `real` or `complex` type. It is an `intent(out)` argument.
 
 ### Syntax
 
 `call ` [[stdlib_sparse_conversion(module):csr2sellc(interface)]] `(csr,sellc[,chunk])`
 
 ### Arguments
 
-`csr`, `intent(in)`: Shall be a `CSR` type of `real` or `complex` type.
+`csr` : Shall be a `CSR` type of `real` or `complex` type. It is an `intent(in)` argument.
 
-`sellc`, `intent(inout)`: Shall be a `SELLC` type of `real` or `complex` type.
+`sellc` : Shall be a `SELLC` type of `real` or `complex` type. It is an `intent(out)` argument.
 
-`chunk`, `intent(in)`, `optional`: chunk size for the Sliced ELLPACK format.
+`chunk`, `optional`: chunk size for the Sliced ELLPACK format. It is an `intent(in)` argument.
 
 ## Example
 ```fortran

src/stdlib_sparse.f90

@@ -1,5 +1,4 @@
 !! public API
 module stdlib_sparse
     use stdlib_sparse_kinds
-    use stdlib_sparse_spmv
 end module stdlib_sparse

src/stdlib_sparse_conversion.fypp

@@ -2,15 +2,15 @@
 #:set R_KINDS_TYPES = list(zip(REAL_KINDS, REAL_TYPES, REAL_SUFFIX))
 #:set C_KINDS_TYPES = list(zip(CMPLX_KINDS, CMPLX_TYPES, CMPLX_SUFFIX))
 #:set KINDS_TYPES = R_KINDS_TYPES+C_KINDS_TYPES
-!> The `stdlib_sparse_conversion` module provides sparse to sparse matrix conversion utilities.
-!>
+!! The `stdlib_sparse_conversion` submodule provides sparse to sparse matrix conversion utilities.
+!!
 ! This code was modified from https://github.com/jalvesz/FSPARSE by its author: Alves Jose
 submodule(stdlib_sparse_kinds) stdlib_sparse_conversion
     use stdlib_sorting, only: sort
     implicit none
 
-    !> Sort arrays of a COO matrix
-    !> 
+    !! Sort arrays of a COO matrix
+    !! 
     interface sort_coo
         module procedure sort_coo_unique
     #:for k1, t1, s1 in (KINDS_TYPES)
@@ -23,7 +23,7 @@ contains
     #:for k1, t1, s1 in (KINDS_TYPES)
     module subroutine dense2coo_${s1}$(dense,COO)
         ${t1}$, intent(in) :: dense(:,:)
-        type(COO_${s1}$), intent(inout) :: COO
+        type(COO_${s1}$), intent(out) :: COO
         integer :: num_rows, num_cols, nnz
         integer :: i, j, idx
 
@@ -51,7 +51,7 @@ contains
     #:for k1, t1, s1 in (KINDS_TYPES)
     module subroutine coo2dense_${s1}$(COO,dense)
         type(COO_${s1}$), intent(in) :: COO
-        ${t1}$, allocatable, intent(inout) :: dense(:,:)
+        ${t1}$, allocatable, intent(out) :: dense(:,:)
         integer :: idx
 
         if(.not.allocated(dense)) allocate(dense(COO%nrows,COO%nrows),source=zero_${s1}$)
@@ -64,8 +64,8 @@ contains
 
     #:for k1, t1, s1 in (KINDS_TYPES)
     module subroutine coo2csr_${s1}$(COO,CSR)
-        type(COO_${s1}$), intent(in)    :: COO
-        type(CSR_${s1}$), intent(inout) :: CSR
+        type(COO_${s1}$), intent(in)  :: COO
+        type(CSR_${s1}$), intent(out) :: CSR
         integer :: i
 
         CSR%nnz = COO%nnz; CSR%nrows = COO%nrows; CSR%ncols = COO%ncols
@@ -95,7 +95,7 @@ contains
     #:for k1, t1, s1 in (KINDS_TYPES)
     module subroutine csr2dense_${s1}$(CSR,dense)
         type(CSR_${s1}$), intent(in) :: CSR
-        ${t1}$, allocatable, intent(inout) :: dense(:,:)
+        ${t1}$, allocatable, intent(out) :: dense(:,:)
         integer :: i, j
 
         if(.not.allocated(dense)) allocate(dense(CSR%nrows,CSR%nrows),source=zero_${s1}$)
@@ -120,8 +120,8 @@ contains
 
     #:for k1, t1, s1 in (KINDS_TYPES)
     module subroutine csr2coo_${s1}$(CSR,COO)
-        type(CSR_${s1}$), intent(in)    :: CSR
-        type(COO_${s1}$), intent(inout) :: COO
+        type(CSR_${s1}$), intent(in)  :: CSR
+        type(COO_${s1}$), intent(out) :: COO
         integer :: i, j
 
         COO%nnz = CSR%nnz; COO%nrows = CSR%nrows; COO%ncols = CSR%ncols
@@ -146,9 +146,9 @@ contains
 
     #:for k1, t1, s1 in (KINDS_TYPES)
     module subroutine csr2ell_${s1}$(CSR,ELL,num_nz_rows)
-        type(CSR_${s1}$), intent(in)    :: CSR
-        type(ELL_${s1}$), intent(inout) :: ELL
-        integer, intent(in), optional :: num_nz_rows !> number of non zeros per row
+        type(CSR_${s1}$), intent(in)  :: CSR
+        type(ELL_${s1}$), intent(out) :: ELL
+        integer, intent(in), optional :: num_nz_rows !! number of non zeros per row
 
         integer :: i, j, num_nz_rows_, adr1, adr2
         !-------------------------------------------
@@ -176,10 +176,10 @@ contains
 
     #:for k1, t1, s1 in (KINDS_TYPES)
     module subroutine csr2sellc_${s1}$(CSR,SELLC,chunk)
-        !> csr2sellc: This function enables transfering data from a CSR matrix to a SELL-C matrix
-        !> This algorithm was gracefully provided by Ivan Privec and adapted by Jose Alves
-        type(CSR_${s1}$), intent(in)      :: CSR
-        type(SELLC_${s1}$), intent(inout) :: SELLC
+        !! csr2sellc: This function enables transfering data from a CSR matrix to a SELL-C matrix
+        !! This algorithm was gracefully provided by Ivan Privec and adapted by Jose Alves
+        type(CSR_${s1}$), intent(in)    :: CSR
+        type(SELLC_${s1}$), intent(out) :: SELLC
         integer, intent(in), optional :: chunk
         ${t1}$, parameter :: zero = zero_${s1}$
         integer :: i, j, num_chunks