Fix Qiskit#840: Add GraphML serializer (Qiskit#1464)

* Fix Qiskit#840: Add GraphML serializer

This commit adds a GraphML serializer:

```python
def write_graphml(
    graphs: list[PyGraph | PyDiGraph],
    keys: list[tuple[str, Domain, str, Type, Any]],
    path: str,
    /,
    compression: str | None = ...,
) -> None: ...
```

`keys` is a list of tuples: id, domain, name of the key, type, and
default value. This commit also introduces the
`read_graphml_with_keys` function, which returns the key definitions
in the same format, along with the list of parsed graphs.

The implementation preserves the ids of graphs, nodes, and edges when
possible. If some ids conflict, fresh ids are generated in the written
GraphML file. The `read_graphml` function has also been updated to
store the graph id in the graph attributes, just like node and edge
ids are stored in the corresponding attributes.

The `write_graphml` function supports gzip compression, as does
`read_graphml`.

Note that the JSON node-link serializer (the other part of Qiskit#840) was
already implemented in Qiskit#1091.

Compared to Qiskit#1462:

- Keys are passed explicitly instead of being inferred (which allows
to use the types `float` and `int`, and to use default values);

- Attributes for graphs, nodes, and edges are taken from the weight of elements, instead of relying on callbacks. This allows write_graphml to act as a proper reciprocal of read_graphml. Round-trip tests have been added.

- IDs are taken from attributes when possible, instead of being generated from indices.

- Multiple graphs can be written to the same file.

- Gzip compression is supported.

- Tests have been added.

Regarding @IvanIsCoding's
comment (Qiskit#1462 (comment)),
about using https://github.com/jonasbb/petgraph-graphml:

- Rustworkx's `graphml.rs` introduces an internal `Graph` data
structure, which is used for `read_graphml`. It is natural to
have `write_graphml` rely on the same data structure.

- `petgraph-graphml` generates ids from indices, which prevents us
from preserving ids accross the `read_graphml`/`write_graphml` round
trip.

* Fix clippy comments

* Prefix types with GraphML

Suggested by @IvanIsCoding: Qiskit#1464 (comment)

* Black

* Add release notes

* Fix stubs error

* Add documentation

* Remove read_graphml_with_keys / write_graphml for single graph only

* Use `DictMap` everywhere

Suggested by @IvanIsCoding: Qiskit#1464 (comment)

* rustfmt and clippy

* Remove unused math module (ruff check)

* Use `from __future__ import annotations` for Python <3.10

* Add stub for `write_graphml`

* Remove `read_graphml_with_keys` from documentation

* Apply suggestions from code review

* Update rustworkx/__init__.py

* Apply suggestions from code review

---------

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

Author: 2 people

docs/source/api/serialization.rst

@@ -8,5 +8,6 @@ Serialization
 
    rustworkx.node_link_json
    rustworkx.read_graphml
+   rustworkx.write_graphml
    rustworkx.from_node_link_json_file
    rustworkx.parse_node_link_json

releasenotes/notes/write_graphml-624c10b6f7592ee1.yaml

@@ -0,0 +1,9 @@
+---
+features:
+  - |
+    Added a new function :func:`~rustworkx.write_graphml` that writes
+    a list of rustworkx graph objects to a file in GraphML format.
+other:
+  - |
+    When graphs read with :func:`~rustworkx.read_graphml` include IDs,
+    these IDs are now stored in the graph attributes.

rustworkx/__init__.py

@@ -2279,3 +2279,9 @@ def single_source_all_shortest_paths(
         For most use cases, consider using `dijkstra_shortest_paths` for a single shortest path, which runs much faster.
     """
     raise TypeError(f"Invalid Input Type {type(graph)} for graph")
+
+
+@_rustworkx_dispatch
+def write_graphml(graph, path, /, keys=None, compression=None):
+    """ """
+    raise TypeError(f"Invalid Input Type {type(graph)} for graph")

rustworkx/__init__.pyi

@@ -163,6 +163,9 @@ from .rustworkx import directed_barabasi_albert_graph as directed_barabasi_alber
 from .rustworkx import undirected_random_bipartite_graph as undirected_random_bipartite_graph
 from .rustworkx import directed_random_bipartite_graph as directed_random_bipartite_graph
 from .rustworkx import read_graphml as read_graphml
+from .rustworkx import graph_write_graphml as graph_write_graphml
+from .rustworkx import digraph_write_graphml as digraph_write_graphml
+from .rustworkx import GraphMLKey as GraphMLKey
 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
@@ -662,3 +665,10 @@ def is_bipartite(graph: PyGraph[_S, _T] | PyDiGraph[_S, _T]) -> bool: ...
 def condensation(
     graph: PyDiGraph | PyGraph, /, sccs: list[int] | None = ...
 ) -> PyDiGraph | PyGraph: ...
+def write_graphml(
+    graph: PyGraph | PyDiGraph,
+    path: str,
+    /,
+    keys: list[GraphMLKey] | None = ...,
+    compression: str | None = ...,
+) -> None: ...

rustworkx/rustworkx.pyi

@@ -68,6 +68,30 @@ class ColoringStrategy:
     Saturation: Any
     IndependentSet: Any
 
+@final
+class GraphMLDomain:
+    Node: GraphMLDomain
+    Edge: GraphMLDomain
+    Graph: GraphMLDomain
+    All: GraphMLDomain
+
+@final
+class GraphMLType:
+    Boolean: GraphMLType
+    Int: GraphMLType
+    Float: GraphMLType
+    Double: GraphMLType
+    String: GraphMLType
+    Long: GraphMLType
+
+@final
+class GraphMLKey:
+    id: str
+    domain: GraphMLDomain
+    name: str
+    ty: GraphMLType
+    default: Any
+
 # Cartesian product
 
 def digraph_cartesian_product(
@@ -685,6 +709,20 @@ def read_graphml(
     /,
     compression: str | None = ...,
 ) -> list[PyGraph | PyDiGraph]: ...
+def graph_write_graphml(
+    graph: PyGraph,
+    path: str,
+    /,
+    keys: list[GraphMLKey] | None = ...,
+    compression: str | None = ...,
+) -> None: ...
+def digraph_write_graphml(
+    graph: PyDiGraph,
+    path: str,
+    /,
+    keys: list[GraphMLKey] | None = ...,
+    compression: str | None = ...,
+) -> None: ...
 def digraph_node_link_json(
     graph: PyDiGraph[_S, _T],
     /,