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

[jalvesz]

This PR introduces support for the matrix market format. A big shoutout and the credit to @Mahmood-Sinan who took an initial draft by myself and put it into its current shape.

Key details:

Interfaces:
dense: call load_mm( filename, matrix [, iostat, iomsg] )
sparse (coo like): call load_mm( filename, index, data [, iostat, iomsg])

dense: call save_mm( filename, matrix [, comment, format, symmetry, iostat, iomsg] )
sparse (coo like): call save_mm( filename, index, data [, comment, format, symmetry, iostat, iomsg] )

On implementation:

• Whilst at first we thought about using the COO_type class to pass sparse matrices, we then went back on that point to reduce unnecessary dependencies.
• When loading, the procedure always returns a full matrix with respect to symmetry, applying hermitianness or skewness if such is the label in the file.
• The loading routines uses access=stream and to_num_from_stream for fast reading

Previous art and references

• https://math.nist.gov/MatrixMarket/mmio/f/mmiof77.html
• https://www.researchgate.net/publication/2630533_The_Matrix_Market_Exchange_Formats_Initial_Design
  SciPy:
• https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.mmwrite.html
• https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.mmread.html
  Julia
• https://juliapackages.com/p/matrixmarket

[Copilot]

Pull request overview

This PR adds comprehensive support for the Matrix Market exchange format to the Fortran stdlib. The Matrix Market format is a widely-used ASCII format for representing sparse and dense matrices, developed at NIST.

Changes:

• Adds load_mm and save_mm interfaces supporting both dense arrays and sparse COO (coordinate) format
• Supports real, complex, and integer data types across multiple precision levels
• Implements symmetry handling (general, symmetric, skew-symmetric, hermitian)

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
src/io/stdlib_io_mm.fypp	Main module defining the public interfaces for load_mm and save_mm
src/io/stdlib_io_mm_load.fypp	Submodule implementing matrix loading from Matrix Market files with header parsing and format detection
src/io/stdlib_io_mm_save.fypp	Submodule implementing matrix saving to Matrix Market files with header generation
src/io/CMakeLists.txt	Adds new source files and stdlib_constants dependency to the io library build
test/io/test_io_mm.f90	Basic test program for Matrix Market loading functionality
test/io/test_*.mtx	Test fixture files in Matrix Market format for different data types
test/io/CMakeLists.txt	Adds io_mm test to the test suite
example/io/example_matrix_market.f90	Example demonstrating dense and sparse matrix I/O
example/io/CMakeLists.txt	Adds matrix_market example to the build
doc/specs/stdlib_io.md	Documentation for the new Matrix Market I/O functionality

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The indentation is incorrect starting from line 248. Lines 248-259 should be indented one level further since they are inside the subroutine but after the early return on line 247. This appears to be a logic error - the code after "if(header%symmetry==MS_general) return" is unreachable for general matrices but is incorrectly at the same indentation level, suggesting it should always execute. The indentation should reflect that this code block only runs when symmetry is not general.

[Copilot]

Similar to the dense load function, this coordinate load function has error handling issues. When operations fail (file open, header read, allocation, parsing), the function returns without properly setting iostat or iomsg for the caller. For instance, line 158 returns on file open error but iostat remains 0 (from line 153). This applies to multiple error paths throughout lines 153-217. Errors should be properly propagated to optional iostat/iomsg parameters or trigger error_stop when they are not present.

Suggested change

	#:endif
	#:endif
	if (stat /= 0) then
	if (present(iostat)) then
	iostat = stat
	end if
	if (present(iomsg)) then
	write(iomsg, '(a,i0)') 'Error reading Matrix Market coordinate data at entry ', i
	end if
	if (.not. present(iostat)) then
	call error_stop('Error reading Matrix Market coordinate data')
	end if
	return
	end if

[Mahmood-Sinan]

This has been updated

[Copilot]

The variable nnz is declared on line 65 but is passed uninitialized to write_mm_header on line 118. For array format (MM_ARRAY), the nnz parameter should not be used, but passing an uninitialized variable is problematic. Either initialize nnz to 0 or modify write_mm_header to not require this parameter for array format.

Suggested change

	! Write header
	! Write header
	nnz = 0

[Copilot]

The documentation only describes the dense matrix interface for load_mm and save_mm, but doesn't document the sparse (COO) interface that accepts separate index and data parameters. The COO interface should be documented as an alternative syntax for loading and saving sparse matrices.

[Copilot]

When file operations fail, the function returns without properly setting iostat or iomsg for the caller. For example, on line 67, if the file cannot be opened, err is non-zero but iostat is never updated. The caller will receive iostat=0 (from line 62) even though the operation failed. Similar issues exist on lines 81, 100, 102, 107, and 117. Consider properly propagating errors to optional iostat/iomsg parameters or calling error_stop when they are not present.

[Copilot]

Line 236 silently returns when index has incorrect dimensions (size(index, dim=1)/=2), but doesn't set iostat or iomsg to indicate an error occurred. The caller will receive iostat=0 (success) even though the operation failed due to invalid input. This should set an appropriate error status and message before returning, or call error_stop when iostat is not present.

Suggested change

	if(size(index, dim=1)/=2) return
	if (size(index, dim=1) /= 2) then
	if (present(iostat)) then
	iostat = 1
	if (present(iomsg)) iomsg = "Invalid index dimensions: first dimension must be 2"
	return
	else
	call error_stop("Invalid index dimensions: first dimension must be 2")
	end if
	end if

[Copilot]

The documentation describes a parameter called header_info on lines 342 and 350, but the actual interface uses three separate optional parameters: comment, format, and symmetry. The documentation should be updated to match the actual API. Additionally, line 358 mentions automatic format selection based on sparsity, but this feature is not implemented in the current code.

[Copilot]

The stdlib_constants dependency is added to the target_link_libraries on line 19, but it appears to only be needed for the unused import in stdlib_io_mm_save.fypp. If the unused import on line 15 of stdlib_io_mm_save.fypp is removed, this dependency can also be removed.

Suggested change

	target_link_libraries(${PROJECT_NAME}_io PUBLIC ${PROJECT_NAME}_core ${PROJECT_NAME}_constants ${PROJECT_NAME}_strings)
	target_link_libraries(${PROJECT_NAME}_io PUBLIC ${PROJECT_NAME}_core ${PROJECT_NAME}_strings)

[Copilot]

read_mm_header never sets err non-zero when header parsing fails, so callers treat invalid or partial Matrix Market headers as successfully parsed even though fields like header%format and header%symmetry may be left uninitialized. In load_mm_coo_*, these unvalidated enum fields are then used to choose allocation sizes and to decide whether to expand symmetric/skew/Her mitian entries, which can lead to writes past the end of the index/data arrays when header%symmetry holds an unexpected value (for example, when the symmetry qualifier is missing in the header line). This allows a malformed Matrix Market file to trigger heap/stack corruption in any application that calls load_mm on untrusted input; you should ensure parse failures set err and/or initialize and validate header fields before they are used to control allocations and indexing.

[Mahmood-Sinan]

This has been updated

[codecov]

Codecov Report

❌ Patch coverage is 0% with 49 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.60%. Comparing base (b1670f0) to head (d6a4403).

Files with missing lines	Patch %	Lines
example/io/example_matrix_market.f90	0.00%	49 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1108      +/-   ##
==========================================
- Coverage   68.84%   68.60%   -0.25%     
==========================================
  Files         408      409       +1     
  Lines       13726    13775      +49     
  Branches     1552     1556       +4     
==========================================
  Hits         9450     9450              
- Misses       4276     4325      +49     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jvdp1]

Are these matrices "public domain"? Material (code, data?) related to Sparskit and similar are often licensed under (Lesser) GPL, which is not compatible with the MIT license of stdlib

[Mahmood-Sinan]

Thanks for the review.
I could not get a solid answer, because https://math.nist.gov/MatrixMarket/data/SPARSKIT/fidap/fidap.html did not provide the name of license. If it is not possible, then maybe we can try dataset given in https://sparse.tamu.edu/ and the website says:

If you use this Collection as a data set, please cite the original ACM-TOMS paper:
Timothy A. Davis and Yifan Hu. 2011. The University of Florida Sparse Matrix Collection. ACM Transactions on Mathematical Software 38, 1, Article 1 (December 2011), 25 pages. DOI: https://doi.org/10.1145/2049662.2049663

Let me know what do you think. @jvdp1 @jalvesz

[jalvesz]

This is what is mentioned on the webpage:
"""
License
Overview
This website software (except for ssget) is under the MIT License. The matrices themselves are under the CC-BY 4.0 License.

Details
ssget (available in SuiteSparse/ssget in the ssget folder is under the BSD 3-clause License.

The matrices themselves are under the CC-BY 4.0 license Note that this license asks you to cite the source of the matrices. That citation can be made to these references:

Kolodziej et al., (2019). The SuiteSparse Matrix Collection Website Interface. Journal of Open Source Software, 4(35), 1244, DOI
Timothy A. Davis and Yifan Hu. 2011. The University of Florida sparse matrix collection. ACM Trans. Math. Softw. 38, 1, Article 1 (November 2011), 25 pages. DOI
You should also preserve the metadata in the matrices themselves, which includes additional citations for specific matrices. For example, the LAW set of matrices (from the Laboratory for Web Algorithmics, Universita degli Studi di Milano) includes specific instructions on how to properly cite the matrices. See sparse.tamu.edu/LAW for details. For the Matrix Market format, most of the metadata appears in the header of the *.mtx themselves.

Ideally, if you redistribute the matrices in your own applications, you should not change them at all. This is essential for repeatability of experiments that rely on these matrices. Modification is permitted under the CC-BY 4.0 License, but that license requires you to state the modifications you make. If you make any such modifications, please change the filename and matrix name to indicate that it differs from the copy of the matrix from sparse.tamu.edu. Carefully describe any modifications you make.
"""

Please note: I'm not legal expert or advisor so nothing I say next should be taken as reference and should be verified: The CC-BY 4.0 license is also a permissive license, so as long as the conditions are respected it might be possible to include matrices from their database as reference.

[Mahmood-Sinan]

Thanks for checking it out.
The CC-BY 4.0 License states that:

You are free to:
Share — copy and redistribute the material in any medium or format for any purpose, even commercially.
Adapt — remix, transform, and build upon the material for any purpose, even commercially.
The licensor cannot revoke these freedoms as long as you follow the license terms.
Under the following terms:
Attribution — You must give [appropriate credit](https://creativecommons.org/licenses/by/4.0/#ref-appropriate-credit), provide a link to the license, and [indicate if changes were made](https://creativecommons.org/licenses/by/4.0/#ref-indicate-changes). You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
No additional restrictions — You may not apply legal terms or [technological measures](https://creativecommons.org/licenses/by/4.0/#ref-technological-measures) that legally restrict others from doing anything the license permits.
Notices:
You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable [exception or limitation](https://creativecommons.org/licenses/by/4.0/#ref-exception-or-limitation).

No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as [publicity, privacy, or moral rights](https://creativecommons.org/licenses/by/4.0/#ref-publicity-privacy-or-moral-rights) may limit how you use the material.

So we can add a README.md file which includes proper attribution, license link and recommended citations. Let me know if this approach looks acceptable or if you would prefer any changes.

[jvdp1]

thank you @jalvesz for the detailed information. For some reasons, I completely missed them.

So we can add a README.md file which includes proper attribution, license link and recommended citations.

Yes, please do so.

Ideally, if you redistribute the matrices in your own applications, you should not change them at all.

I also suggest to follow this advice (if not done yet).