feat(io): Add support for the matrix market exchange format

doc/specs/stdlib_io.md

@@ -321,3 +321,136 @@ Exceptions trigger an `error stop` unless the optional `err` argument is provide
 {!example/io/example_get_file.f90!}
 ```
 
+## Matrix Market Format I/O
+
+### Status
+
+Experimental
+
+### Description
+
+The Matrix Market I/O module provides support for reading and writing matrices in the Matrix Market format, a simple ASCII format for sparse and dense matrices developed at NIST. The format supports real, complex, and integer matrices with various symmetry properties.
+
+### `load_mm` - load a matrix from Matrix Market file
+
+Loads a 2D matrix from a Matrix Market format file. Symmetric matrices are expanded to full storage.
+
+#### Syntax
+
+- To load a matrix of `array` format:
+
+`call ` [[stdlib_io_mm(module):load_mm(interface)]] `(filename, matrix [, iostat, iomsg])`
+
+- To load a matrix of `coordinate` format:
+
+`call ` [[stdlib_io_mm(module):load_mm(interface)]] `(filename, index, data [, iostat, iomsg])`
+
+#### Arguments
+
+**`Array` format**
+
+`call ` [[stdlib_io_mm(module):load_mm(interface)]] `(filename, matrix [, iostat, iomsg])`
+
+- `filename`: Shall be a character expression containing the Matrix Market file name to read from.
+
+- `matrix`: Shall be an allocatable rank-2 array of type `real`, `complex`, or `integer` that will contain the loaded matrix.
+
+- `iostat` (optional): Shall be a scalar of type `integer` that receives the error status. Zero indicates success.
+
+- `iomsg` (optional): Shall be an allocatable character string that receives the error message if iostat is non-zero.
+
+**`Coordinate` format**
+
+`call ` [[stdlib_io_mm(module):load_mm(interface)]] `(filename, index, data [, iostat, iomsg])`
+
+- `filename`: Shall be a character expression containing the Matrix Market file name to read from.
+
+- `index`: Shall be an allocatable rank-2 array of type `integer` that will contain the indices of the loaded matrix.
+
+- `data`: Shall be an allocatable rank-1 array of type `real`, `complex`, or `integer` that will contain the values of the loaded matrix.
+
+- `iostat` (optional): Shall be a scalar of type `integer` that receives the error status. Zero indicates success.
+
+- `iomsg` (optional): Shall be an allocatable character string that receives the error message if iostat is non-zero.
+
+### `save_mm` - save a matrix to Matrix Market file
+
+Saves a 2D matrix to Matrix Market format file.
+
+#### Syntax
+
+- To save a matrix of `array` format:
+
+`call ` [[stdlib_io_mm(module):save_mm(interface)]] `(filename, matrix [, comment, format, symmetry, iostat, iomsg])`
+
+- To save a matrix of `coordinate` format:
+
+`call ` [[stdlib_io_mm(module):save_mm(interface)]] `(filename, index, data [, comment, format, symmetry, iostat, iomsg])`
+
+#### Arguments
+
+**`Array` format**
+
+`call ` [[stdlib_io_mm(module):save_mm(interface)]] `(filename, matrix [, comment, format, symmetry, iostat, iomsg])`
+
+- `filename`: Shall be a character expression containing the Matrix Market file name to write to.
+
+- `matrix`: Shall be a rank-2 array of type `real`, `complex`, or `integer` to save.
+
+- `comment` (optional): Shall be a character expression containing additional comments for the file header.
+
+- `format` (optional): Shall be a character expression specifying how entries are written.
+
+- `symmetry` (optional): Shall be a character expression defining the symmetry of the matrix. Allowed values: `auto`, `general`, `symmetric`, `skew-symmetric`, `hermitian`.
+    - `auto`: Detects the symmetry automatically, falls back to `general` if no symmetry is found.
+    - `general`: all entries are stored
+    - `symmetric` / `hermitian`: only the lower triangle (including diagonal) is stored
+    - `skew-symmetric`: only the strictly lower triangle (excluding diagonal) is stored
+
+  Default: `general`
+
+- `iostat` (optional): Shall be a scalar of type `integer` that receives the error status. Zero indicates success.
+
+- `iomsg` (optional): Shall be an allocatable character string that receives the error message if iostat is non-zero.
+
+**`Coordinate` format**
+
+`call ` [[stdlib_io_mm(module):save_mm(interface)]] `(filename, index, data [, comment, format, symmetry, iostat, iomsg])`
+
+- `filename`: Shall be a character expression containing the Matrix Market file name to write to.
+
+- `index`: Shall be a rank-2 `integer` array of shape `(2, n)` specifying the indices of the entries. 
+    - index(1,:) shall contain row indices
+    - index(2,:) shall contain column indices
+
+- `data`: Shall be a rank-1 array of type `real`, `complex`, or `integer` to save. 
+    - If `size(data) == n`, the values for each index are written.
+    - If `size(data) == 1`, a `pattern` matrix is written (no explicit values)
+
+- `comment` (optional): Shall be a character expression containing additional comments for the file header.
+
+- `format` (optional): Shall be a character expression specifying how entries are written.
+
+- `symmetry` (optional): Shall be a character expression defining the symmetry of the matrix. Allowed values: `general`, `symmetric`, `skew-symmetric`, `hermitian`. 
+    - `general`: all entries are stored
+    - `symmetric` / `hermitian`: only the lower triangle (including diagonal) is stored
+    - `skew-symmetric`: only the strictly lower triangle (excluding diagonal) is stored
+
+- `iostat` (optional): Shall be a scalar of type `integer` that receives the error status. Zero indicates success.
+
+- `iomsg` (optional): Shall be an allocatable character string that receives the error message if iostat is non-zero.
+
+### Matrix Market Format Details
+
+The Matrix Market format supports:
+
+- **Object types**: Currently only `matrix` is supported
+- **Formats**: `coordinate` (sparse) and `array` (dense)  
+- **Data types**: `real`, `complex`, `integer`, `pattern`
+- **Symmetry**: `general`, `symmetric`, `skew-symmetric`, `hermitian`, `auto` (Currently only supported for `array` format)
+
+### Example
+
+```fortran
+{!example/io/example_matrix_market.f90!}
+```

example/io/CMakeLists.txt

@@ -3,6 +3,7 @@ ADD_EXAMPLE(fmt_constants)
 ADD_EXAMPLE(get_file)
 ADD_EXAMPLE(loadnpy)
 ADD_EXAMPLE(loadtxt)
+ADD_EXAMPLE(matrix_market)
 ADD_EXAMPLE(open)
 ADD_EXAMPLE(savenpy)
 ADD_EXAMPLE(savetxt)

example/io/example_matrix_market.f90

@@ -0,0 +1,88 @@
+program example_matrix_market
+    use stdlib_io_mm, only : load_mm, save_mm
+    use stdlib_kinds, only : dp
+    implicit none
+
+    real(dp), allocatable :: matrix(:,:), matrix2(:,:)
+    integer, allocatable  :: index(:,:)
+    complex(dp), allocatable :: data(:)
+    character(len=*), parameter :: dense_filename = "example_dense.mtx"
+    character(len=*), parameter :: sparse_filename = "example_sparse.mtx"
+    integer :: iostat, i
+    character(len=:), allocatable :: iomsg
+
+    ! Create a test dense matrix
+    allocate(matrix(3,3))
+    matrix = reshape([1.0_dp, 2.0_dp, 3.0_dp, &
+                      4.0_dp, 5.0_dp, 6.0_dp, &
+                      7.0_dp, 8.0_dp, 9.0_dp], [3,3])
+
+    print *, "=== Dense Matrix Example ==="
+    print *, "Original dense matrix:"
+    call print_matrix(matrix)
+
+    ! Save dense matrix to Matrix Market file
+    call save_mm(dense_filename, matrix, format="ES24.15E2", symmetry="general", iostat=iostat, iomsg=iomsg)
+    if (iostat /= 0) then
+        print *, "Error saving dense matrix: ", iomsg
+        stop 1
+    end if
+
+    print *, "Dense matrix saved to ", dense_filename
+
+    ! Load dense matrix from Matrix Market file  
+    call load_mm(dense_filename, matrix2, iostat=iostat, iomsg=iomsg)
+    if (iostat /= 0) then
+        print *, "Error loading dense matrix: ", iomsg
+        stop 1
+    end if
+
+    print *, "Loaded dense matrix:"
+    call print_matrix(matrix2)
+
+    print *, "=== Sparse Matrix Example ==="
+    ! Create a test sparse matrix
+    allocate(index(2,6))
+    allocate(data(6))
+    index(:,1) = [1,1]; data(1) = (10.0_dp, -1.5_dp)
+    index(:,2) = [2,2]; data(2) = (20.0_dp, 2.0_dp)
+    index(:,3) = [3,3]; data(3) = (30.0_dp, 3.0_dp)
+    index(:,4) = [4,4]; data(4) = (40.0_dp, -4.0_dp)
+    index(:,5) = [1,4]; data(5) = ( 5.0_dp, -7.5_dp)
+    index(:,6) = [3,1]; data(6) = (15.0_dp, 25.0_dp)
+
+    ! Save sparse matrix to Matrix Market file
+    call save_mm(sparse_filename, index, data, format="ES24.15E2", symmetry="general", iostat=iostat, iomsg=iomsg)
+    if (iostat /= 0) then
+        print *, "Error saving sparse matrix: ", iomsg
+        stop 1
+    end if
+
+    print *, "Sparse matrix saved to ", sparse_filename
+
+    ! Load sparse matrix from Matrix Market file
+    call load_mm(sparse_filename, index, data, iostat=iostat, iomsg=iomsg)
+    if (iostat /= 0) then
+        print *, "Error loading sparse matrix: ", iomsg
+        stop 1
+    end if
+
+    print *, "Loaded sparse matrix (COO format):"
+    print *, "Data (row, col, value):"
+    do i = 1, size(data)
+        print *, index(1,i), index(2,i), data(i)
+    end do
+
+contains
+
+    subroutine print_matrix(mat)
+        real(dp), intent(in) :: mat(:,:)
+        integer :: i
+
+        do i = 1, size(mat, 1)
+            print *, mat(i, :)
+        end do
+        print *
+    end subroutine print_matrix
+
+end program example_matrix_market

src/io/CMakeLists.txt

@@ -3,6 +3,9 @@ set(io_fppFiles
     stdlib_io_npy.fypp
     stdlib_io_npy_load.fypp
     stdlib_io_npy_save.fypp
+    stdlib_io_mm.fypp
+    stdlib_io_mm_load.fypp
+    stdlib_io_mm_save.fypp
     )
 
 set(io_cppFiles

src/io/stdlib_io_mm.fypp

@@ -0,0 +1,94 @@
+! SPDX-Identifier: MIT
+
+#:include "common.fypp"
+#: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 I_KINDS_TYPES  = list(zip(INT_KINDS,   INT_TYPES, INT_KINDS))
+#:set RCI_KINDS_TYPES = R_KINDS_TYPES + C_KINDS_TYPES + I_KINDS_TYPES
+
+!> The Matrix Market (MM) format is a simple, human-readable, ASCII format for sparse
+!> and dense matrices. The format was developed at NIST (National Institute of Standards
+!> and Technology) for the Matrix Market, a repository of test matrices for use in
+!> comparative studies of algorithms for numerical linear algebra.
+!>
+!> For more information, see: https://math.nist.gov/MatrixMarket/formats.html
+module stdlib_io_mm
+    use stdlib_kinds, only : int8, int16, int32, int64, sp, dp, xdp, qp
+    implicit none
+    private
+
+    type, public :: mm_header_type
+        integer :: object
+        integer :: format
+        integer :: qualifier
+        integer :: symmetry
+        character(len=1024), allocatable :: comments(:)
+    end type mm_header_type
+
+    !> Version: experimental
+    !>
+    !> Load a matrix from a Matrix Market file
+    !> ([Specification](../page/specs/stdlib_io.html#load_mm))
+    interface load_mm
+        #:for k, t, s in RCI_KINDS_TYPES
+        module subroutine load_mm_dense_${s}$(filename, matrix, iostat, iomsg)
+            !> Name of the Matrix Market file to load from
+            character(len=*), intent(in) :: filename
+            !> Matrix to be loaded from the Matrix Market file
+            ${t}$, allocatable, intent(out) :: matrix(:,:)
+            !> Error status of loading, zero on success
+            integer, intent(out), optional :: iostat
+            !> Associated error message in case of non-zero status code
+            character(len=:), allocatable, intent(out), optional :: iomsg
+        end subroutine
+        #:endfor
+        #:for k, t, s in RCI_KINDS_TYPES
+        module subroutine load_mm_coo_${s}$(filename, index, data, iostat, iomsg)
+            !> Name of the Matrix Market file to load from
+            character(len=*), intent(in) :: filename
+            !> Matrix indices to be read from the Matrix Market file
+            integer, allocatable, intent(out) :: index(:,:)
+            !> Matrix data to be read from the Matrix Market file
+            ${t}$, allocatable, intent(out) :: data(:)
+            !> Error status of loading, zero on success
+            integer, intent(out), optional :: iostat
+            !> Associated error message in case of non-zero status code
+            character(len=:), allocatable, intent(out), optional :: iomsg
+        end subroutine
+        #:endfor
+    end interface
+    public :: load_mm
+
+    !> Version: experimental
+    !>
+    !> Save a matrix to a Matrix Market file
+    !> ([Specification](../page/specs/stdlib_io.html#save_mm))
+    interface save_mm
+        #:for k, t, s in RCI_KINDS_TYPES
+        module subroutine save_mm_dense_${s}$(filename, matrix, comment, format, symmetry, iostat, iomsg)
+        character(len=*), intent(in) :: filename
+        ${t}$, intent(in) :: matrix(:,:)
+        character(len=*), intent(in), optional :: comment
+        character(len=*), intent(in), optional :: format
+        character(len=*), intent(in), optional :: symmetry
+        integer, intent(out), optional :: iostat
+        character(len=:), allocatable, intent(out), optional :: iomsg
+        end subroutine
+        #:endfor
+
+        #:for k, t, s in RCI_KINDS_TYPES
+        module subroutine save_mm_coo_${s}$(filename, index, data, comment, format, symmetry, iostat, iomsg)
+        character(len=*), intent(in) :: filename
+        integer, intent(in) :: index(:,:)
+        ${t}$, intent(in) :: data(:)
+        character(len=*), intent(in), optional :: comment
+        character(len=*), intent(in), optional :: format
+        character(len=*), intent(in), optional :: symmetry
+        integer, intent(out), optional :: iostat
+        character(len=:), allocatable, intent(out), optional :: iomsg
+        end subroutine
+        #:endfor
+    end interface save_mm
+    public :: save_mm
+
+end module stdlib_io_mm