📝 Use PyGraphviz for documentation diagrams

.readthedocs.yaml

@@ -13,7 +13,6 @@ build:
   apt_packages:
     - cmake
     - doxygen
-    - graphviz
   jobs:
     pre_build:
       # Build the C++ API docs before Sphinx starts

docs/conf.py

@@ -130,6 +130,7 @@ def format_url(self, _e: Entry) -> HRef:  # ruff:ignore[no-self-use]
 autoapi_add_toctree_entry = False
 autoapi_ignore = [
     "*/**/_version.py",
+    "*/mqt/ddsim/utils.py",
 ]
 autoapi_options = [
     "members",

docs/simulators/CircuitSimulator.md

@@ -98,15 +98,17 @@ However, due to the nature of decision diagrams, the simulator can generally
 sample from the output distribution of much larger circuits than can be fully
 represented in memory.
 
-If [Graphviz](https://www.graphviz.org/) is installed, use
-{py:meth}`~mqt.core.dd.VectorDD.to_svg` to export the final decision diagram as
-SVG. IPython can display the resulting file in a notebook. The following shows
-the default configuration options for the export.
+Use `to_svg` to render a decision diagram as SVG. It uses
+[PyGraphviz](https://pygraphviz.github.io/documentation/stable/install.html) 2
+or later when installed, or the `dot` command otherwise. IPython can display the
+resulting file in a notebook.
 
 ```{code-cell} ipython3
 from IPython.display import SVG
 
-dd.to_svg("bell_state.svg", colored=True, edge_labels=False, classic=False, memory=False, format_as_polar=True)
+from mqt.ddsim.utils import to_svg
+
+to_svg(dd, "bell_state.svg", colored=True, edge_labels=False, classic=False, memory=False, format_as_polar=True)
 
 SVG(filename="bell_state.svg")
 ```

docs/simulators/UnitarySimulator.md

@@ -51,11 +51,17 @@ qc.x(0)
 qc.draw(output="mpl", style="iqp")
 ```
 
+Use `to_svg` to render a decision diagram as SVG. It uses
+[PyGraphviz](https://pygraphviz.github.io/documentation/stable/install.html) 2
+or later when installed, or the `dot` command otherwise. IPython can display the
+resulting file in a notebook.
+
 ```{code-cell} ipython3
 from IPython.display import SVG
 from mqt.core import load
 
 from mqt.ddsim import UnitarySimulator
+from mqt.ddsim.utils import to_svg
 
 # Create the simulator
 circ = load(qc)
@@ -66,7 +72,7 @@ sim.construct()
 
 # Get the decision diagram representation of the unitary
 dd = sim.get_constructed_dd()
-dd.to_svg("unitary.svg", colored=True, edge_labels=True, classic=False)
+to_svg(dd, "unitary.svg", colored=True, edge_labels=True, classic=False)
 
 SVG(filename="unitary.svg")
 ```
@@ -102,6 +108,7 @@ from IPython.display import SVG
 from mqt.core import load
 
 from mqt.ddsim import UnitarySimulator
+from mqt.ddsim.utils import to_svg
 
 # Create the simulator
 circ = load(qc)
@@ -112,7 +119,7 @@ sim.construct()
 
 # Get the decision diagram representation of the unitary
 dd = sim.get_constructed_dd()
-dd.to_svg("unitary.svg", colored=True, edge_labels=True, classic=False)
+to_svg(dd, "unitary.svg", colored=True, edge_labels=True, classic=False)
 
 SVG(filename="unitary.svg")
 ```
@@ -142,6 +149,7 @@ from IPython.display import SVG
 from mqt.core import load
 
 from mqt.ddsim import UnitarySimulator
+from mqt.ddsim.utils import to_svg
 
 # Create the simulator
 circ = load(qc)
@@ -152,7 +160,7 @@ sim.construct()
 
 # Get the decision diagram representation of the unitary
 dd = sim.get_constructed_dd()
-dd.to_svg("unitary.svg", colored=True, edge_labels=True, classic=False)
+to_svg(dd, "unitary.svg", colored=True, edge_labels=True, classic=False)
 
 SVG(filename="unitary.svg")
 ```
@@ -186,6 +194,7 @@ from IPython.display import SVG
 from mqt.core import load
 
 from mqt.ddsim import UnitarySimulator
+from mqt.ddsim.utils import to_svg
 
 # Create the simulator
 circ = load(qc)
@@ -196,7 +205,7 @@ sim.construct()
 
 # Get the decision diagram representation of the unitary
 dd = sim.get_constructed_dd()
-dd.to_svg("unitary.svg", colored=True, edge_labels=True, classic=False)
+to_svg(dd, "unitary.svg", colored=True, edge_labels=True, classic=False)
 
 SVG(filename="unitary.svg")
 ```
@@ -231,6 +240,7 @@ from IPython.display import SVG
 from mqt.core import load
 
 from mqt.ddsim import UnitarySimulator
+from mqt.ddsim.utils import to_svg
 
 # Create the simulator
 circ = load(qc)
@@ -241,7 +251,7 @@ sim.construct()
 
 # Get the decision diagram representation of the unitary
 dd = sim.get_constructed_dd()
-dd.to_svg("unitary.svg", colored=True, edge_labels=True, classic=False)
+to_svg(dd, "unitary.svg", colored=True, edge_labels=True, classic=False)
 
 SVG(filename="unitary.svg")
 ```
@@ -283,6 +293,7 @@ from IPython.display import SVG
 from mqt.core import load
 
 from mqt.ddsim import UnitarySimulator
+from mqt.ddsim.utils import to_svg
 
 # Create the simulator
 circ = load(qc)
@@ -293,7 +304,7 @@ sim.construct()
 
 # Get the decision diagram representation of the unitary
 dd = sim.get_constructed_dd()
-dd.to_svg("unitary.svg", colored=True, edge_labels=True, classic=False)
+to_svg(dd, "unitary.svg", colored=True, edge_labels=True, classic=False)
 
 SVG(filename="unitary.svg")
 ```
@@ -361,6 +372,7 @@ from mqt.core import load
 from qiskit import QuantumCircuit
 
 from mqt.ddsim import UnitarySimulatorMode, UnitarySimulator
+from mqt.ddsim.utils import to_svg
 
 qc = QuantumCircuit(3)
 qc.h(2)
@@ -377,7 +389,7 @@ sim.construct()
 
 # Get the decision diagram representation of the unitary
 dd = sim.get_constructed_dd()
-dd.to_svg("unitary.svg", colored=True, edge_labels=True, classic=False)
+to_svg(dd, "unitary.svg", colored=True, edge_labels=True, classic=False)
 
 SVG(filename="unitary.svg")
 ```

pyproject.toml

@@ -88,6 +88,7 @@ docs = [
   "breathe>=4.36",
   "furo>=2025.12.19",
   "myst-nb>=1.4",
+  "pygraphviz>=2",
   "qiskit[visualization]>=2.1",
   "sphinx>=9",
   "sphinx-autoapi>=3.6",

python/mqt/ddsim/utils.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+# Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+"""Utilities for documentation examples."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mqt.core.dd import MatrixDD, VectorDD
+
+
+def to_svg(dd: VectorDD | MatrixDD, filename: str, **options: bool) -> None:
+    """Render a decision diagram as SVG with PyGraphviz.
+
+    Remove once the minimum MQT Core version includes PyGraphviz-backed `to_svg()`.
+    See https://github.com/munich-quantum-toolkit/ddsim/issues/1013.
+
+    Args:
+        dd: Decision diagram to render.
+        filename: Output SVG filename.
+        **options: Options passed to `dd.to_dot()`.
+    """
+    # PyGraphviz is an optional documentation dependency.
+    from pygraphviz import AGraph  # ruff: ignore[import-outside-top-level] # ty: ignore[unresolved-import]
+
+    AGraph(dd.to_dot(**options)).draw(filename, prog="dot", format="svg")