Matrix Market support (#1515)

* Matrix Market support

* Changes

Adding sparse and dense test and fixing lint

* Changes based on comments

* Downgrade nalgebra-sparse to 0.10 for MSRV reasons

* Add universal functions

* Add signatures to make stubs tests pass

* Update release note to have the correct name of the methods

* Docstrings for write methods

* Finalize docstrings

---------

Co-authored-by: Ivan Carvalho <[email protected]>

Author: Krishn1412

Cargo.lock

@@ -66,6 +66,7 @@ rustworkx-core = { path = "rustworkx-core", version = "=0.17.1" }
 flate2 = "1.0.35"
 pest = "=2.7.15"
 pest_derive = "=2.7.15"
+nalgebra-sparse = { version = "=0.10", features = ["io"] }
 
 [dependencies.pyo3]
 version = "0.24"

Cargo.toml

@@ -60,3 +60,4 @@ the functions from the explicitly typed based on the data type.
    rustworkx.digraph_dijkstra_search
    rustworkx.digraph_node_link_json
    rustworkx.digraph_longest_simple_path
+   rustworkx.digraph_write_matrix_market

docs/source/api/pydigraph_api_functions.rst

@@ -61,3 +61,4 @@ typed API based on the data type.
    rustworkx.graph_dijkstra_search
    rustworkx.graph_node_link_json
    rustworkx.graph_longest_simple_path
+   rustworkx.graph_write_matrix_market

docs/source/api/pygraph_api_functions.rst

@@ -11,3 +11,6 @@ Serialization
    rustworkx.write_graphml
    rustworkx.from_node_link_json_file
    rustworkx.parse_node_link_json
+   rustworkx.write_matrix_market
+   rustworkx.read_matrix_market
+   rustworkx.read_matrix_market_file

docs/source/api/serialization.rst

@@ -0,0 +1,7 @@
+features:
+  - |
+    Added support for reading and writing matrices in the Matrix Market (MM) format via the new
+    :func:`~rustworkx.read_matrix_market`, :func:`~rustworkx.read_matrix_market_file`,
+    and :func:`~rustworkx.write_matrix_market` functions.
+    These functions enable importing and exporting sparse matrices in COO (Coordinate) format, either from
+    a file or directly from an in-memory string.

releasenotes/notes/matrix-market-d205bac2d147bfee.yaml

@@ -2313,6 +2313,30 @@ def write_graphml(graph, path, /, keys=None, compression=None):
     raise TypeError(f"Invalid Input Type {type(graph)} for graph")
 
 
+@_rustworkx_dispatch
+def write_matrix_market(graph, /, path=None):
+    """Write a graph to Matrix Market format.
+
+    Matrix Market is a human-readable ASCII file format for storing sparse matrices
+    as coordinate format (row, column, value) triplets. The graph is converted to a
+    coordinate (COO) sparse matrix representation where edges become non-zero entries.
+
+    For more information about Matrix Market format, see:
+    https://math.nist.gov/MatrixMarket/formats.html
+
+    :param graph: The graph to write in Matrix Market format. This can be a
+        :class:`~rustworkx.PyGraph` or :class:`~rustworkx.PyDiGraph`.
+    :param path: Optional file path to write the output. If not specified,
+        returns the Matrix Market content as a string.
+    :returns: None if a file path was provided, otherwise returns the Matrix Market
+        formatted content as a string.
+    :rtype: Optional[str]
+    :raises ValueError: when the graph cannot be converted to a valid COO matrix.
+    :raises IOError: when an error occurs during file I/O or format serialization.
+    """
+    raise TypeError(f"Invalid Input Type {type(graph)} for graph")
+
+
 @_rustworkx_dispatch
 def bfs_layers(graph, sources=None):
     """Return the BFS layers of a graph as a list of lists.

rustworkx/__init__.py

@@ -170,6 +170,10 @@ from .rustworkx import digraph_node_link_json as digraph_node_link_json
 from .rustworkx import graph_node_link_json as graph_node_link_json
 from .rustworkx import from_node_link_json_file as from_node_link_json_file
 from .rustworkx import from_dot as from_dot
+from .rustworkx import graph_write_matrix_market as graph_write_matrix_market
+from .rustworkx import digraph_write_matrix_market as digraph_write_matrix_market
+from .rustworkx import read_matrix_market_file as read_matrix_market_file
+from .rustworkx import read_matrix_market as read_matrix_market
 from .rustworkx import parse_node_link_json as parse_node_link_json
 from .rustworkx import hyperbolic_greedy_routing as hyperbolic_greedy_routing
 from .rustworkx import hyperbolic_greedy_success_rate as hyperbolic_greedy_success_rate
@@ -677,6 +681,11 @@ def write_graphml(
     keys: list[GraphMLKey] | None = ...,
     compression: str | None = ...,
 ) -> None: ...
+def write_matrix_market(
+    graph: PyGraph | PyDiGraph,
+    /,
+    path: str | None = ...,
+) -> None: ...
 def bfs_layers(
     graph: PyGraph | PyDiGraph,
     sources: Sequence[int] | None = ...,

rustworkx/__init__.pyi

@@ -754,6 +754,18 @@ def from_node_link_json_file(
 def from_dot(
     dot_str: str,
 ) -> PyDiGraph[_S, _T] | PyGraph[_S, _T]: ...
+def read_matrix_market(contents: str) -> PyGraph | PyDiGraph: ...
+def read_matrix_market_file(path: str) -> PyGraph | PyDiGraph: ...
+def graph_write_matrix_market(
+    graph: PyGraph,
+    /,
+    path: str | None = ...,
+) -> str | None: ...
+def digraph_write_matrix_market(
+    graph: PyDiGraph,
+    /,
+    path: str | None = ...,
+) -> str | None: ...
 
 # Geometry
 

rustworkx/rustworkx.pyi

@@ -31,6 +31,7 @@ mod layout;
 mod line_graph;
 mod link_analysis;
 mod matching;
+mod matrix_market;
 mod planar;
 mod random_graph;
 mod score;
@@ -61,6 +62,7 @@ use link_analysis::*;
 use dot_parser::*;
 use geometry::*;
 use matching::*;
+use matrix_market::*;
 use planar::*;
 use random_graph::*;
 use shortest_path::*;
@@ -688,6 +690,10 @@ fn rustworkx(py: Python<'_>, m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(pagerank))?;
     m.add_wrapped(wrap_pyfunction!(hits))?;
     m.add_wrapped(wrap_pyfunction!(from_dot))?;
+    m.add_wrapped(wrap_pyfunction!(digraph_write_matrix_market))?;
+    m.add_wrapped(wrap_pyfunction!(graph_write_matrix_market))?;
+    m.add_wrapped(wrap_pyfunction!(read_matrix_market))?;
+    m.add_wrapped(wrap_pyfunction!(read_matrix_market_file))?;
     m.add_class::<digraph::PyDiGraph>()?;
     m.add_class::<graph::PyGraph>()?;
     m.add_class::<toposort::TopologicalSorter>()?;