FEAT: add Mermaid graph rendering

.cspell.json

@@ -148,6 +148,7 @@
   "useGitignore": true,
   "version": "0.2",
   "words": [
+    "asmermaid",
     "blatt",
     "bosonic",
     "bottomness",

.gitignore

@@ -1,6 +1,7 @@
 # Output files
 *.gv
 *.json
+*.mmd
 *.npy
 *.pdf
 *.pickle

.pre-commit-config.yaml

@@ -50,7 +50,7 @@ repos:
             metadata.vscode
 
   - repo: https://github.com/ComPWA/nbhooks
-    rev: 0.0.1
+    rev: 0.0.2
     hooks:
       - id: colab-toc-visible
       - id: fix-nbformat-version

docs/conf.py

@@ -168,6 +168,7 @@ def __get_newtypes(some_type: type) -> list:
     "sphinx_pybtex_etal_style",
     "sphinx_thebe",
     "sphinx_togglebutton",
+    "sphinxcontrib.mermaid",
     "sphinxcontrib.bibtex",
 ]
 generate_apidoc_package_path = f"../src/{PACKAGE}"
@@ -268,6 +269,7 @@ def __get_newtypes(some_type: type) -> list:
     "smartquotes",
     "substitution",
 ]
+myst_fence_as_directive = ["mermaid"]
 myst_heading_anchors = 2
 myst_substitutions = {
     "branch": BRANCH,
@@ -284,6 +286,7 @@ def __get_newtypes(some_type: type) -> list:
 nb_execution_show_tb = True
 nb_execution_timeout = -1
 nb_output_stderr = "remove"
+nb_render_markdown_format = "myst"
 nitpick_ignore = [
     ("py:class", "StrPath"),
 ]

docs/usage/visualize.ipynb

@@ -35,7 +35,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The {mod}`~qrules.io` module allows you to convert {class}`.MutableTransition`, {class}`.Topology` instances, and {class}`.ProblemSet`s to [DOT language](https://graphviz.org/doc/info/lang.html) with {func}`.asdot`. You can visualize its output with third-party libraries, such as [Graphviz](https://graphviz.org). This is particularly useful after running {meth}`~.StateTransitionManager.find_solutions`, which produces a {class}`.ReactionInfo` object with a {class}`.list` of {class}`.MutableTransition` instances (see {doc}`/usage/reaction`)."
+    "The {mod}`~qrules.io` module allows you to convert {class}`.MutableTransition`, {class}`.Topology` instances, and {class}`.ProblemSet`s to [DOT language](https://graphviz.org/doc/info/lang.html) with {func}`.asdot`. You can visualize its output with third-party libraries, such as [Graphviz](https://graphviz.org). This is particularly useful after running {meth}`~.StateTransitionManager.find_solutions`, which produces a {class}`.ReactionInfo` object with a {class}`.list` of {class}`.MutableTransition` instances (see {doc}`/usage/reaction`).\n",
+    "\n",
+    "In addition, the same objects can be converted to [Mermaid language](https://mermaid.ai/open-source/intro/syntax-reference.html) with {func}`.asmermaid`. We include a few Mermaid examples to demonstrate that this renderer is implemented and working as well."
    ]
   },
   {
@@ -49,7 +51,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "First of all, here are is an example of how to visualize a group of {class}`.Topology` instances. We use {func}`.create_isobar_topologies` and {func}`.create_n_body_topology` to create a few standard topologies."
+    "First of all, here is an example of how to visualize a group of {class}`.Topology` instances. We use {func}`.create_isobar_topologies` and {func}`.create_n_body_topology` to create a few standard topologies."
    ]
   },
   {
@@ -66,7 +68,7 @@
    "outputs": [],
    "source": [
     "import graphviz\n",
-    "from IPython.display import display\n",
+    "from IPython.display import Markdown, display\n",
     "\n",
     "import qrules\n",
     "from qrules.conservation_rules import (\n",
@@ -152,6 +154,32 @@
     "display(graphviz.Source(dot))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "or analogously for {func}`.asmermaid`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "source = qrules.io.asmermaid(\n",
+    "    topologies[0],\n",
+    "    render_final_state_id=False,\n",
+    "    render_resonance_id=True,\n",
+    "    render_node=False,\n",
+    ")\n",
+    "Markdown(f\"\"\"\n",
+    "```mermaid\n",
+    "{source}\n",
+    "```\n",
+    "\"\"\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -216,6 +244,31 @@
     "graphviz.Source(dot)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In Mermaid, a {class}`.ProblemSet` is rendered as follows:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "source = qrules.io.asmermaid(problem_set, render_node=True)\n",
+    "Markdown(f\"\"\"\n",
+    "```mermaid\n",
+    "{source}\n",
+    "```\n",
+    "\"\"\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -244,7 +297,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The list of solutions consist of a {obj}`tuple` of a {obj}`.QNProblemSet` (compare {ref}`problem-sets`) and a {obj}`.QNResult`:"
+    "The list of solutions consists of a {obj}`tuple` of a {obj}`.QNProblemSet` (compare {ref}`problem-sets`) and a {obj}`.QNResult`:"
    ]
   },
   {
@@ -389,6 +442,56 @@
     "graphviz.Source(dot)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In Mermaid, the {class}`.QNProblemSet` is rendered as follows:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "source = qrules.io.asmermaid(qn_problem_set, render_node=True)\n",
+    "Markdown(f\"\"\"\n",
+    "```mermaid\n",
+    "{source}\n",
+    "```\n",
+    "\"\"\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And analogously, the filtered {class}`.QNResult` can be visualized:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "source = qrules.io.asmermaid(filtered_qn_result, render_node=True)\n",
+    "Markdown(f\"\"\"\n",
+    "```mermaid\n",
+    "{source}\n",
+    "```\n",
+    "\"\"\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -431,7 +534,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dot = qrules.io.asdot(reaction.transitions[::50][:3])  # just some selection"
+    "some_transitions = reaction.transitions[::50][:3]\n",
+    "dot = qrules.io.asdot(some_transitions)"
    ]
   },
   {
@@ -449,9 +553,7 @@
    "source": [
     "import graphviz\n",
     "\n",
-    "dot = qrules.io.asdot(\n",
-    "    reaction.transitions[::50][:3], render_node=False\n",
-    ")  # just some selection\n",
+    "dot = qrules.io.asdot(some_transitions, render_node=False)\n",
     "graphviz.Source(dot)"
    ]
   },
@@ -471,6 +573,22 @@
     "qrules.io.write(reaction, \"decay_topologies_with_spin.gv\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Or you can serialize a mermaid string to file with {func}`.io.write`. The file extension for a mermaid file is `.mmd`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "qrules.io.write(reaction, \"decay_topologies_with_spin.mmd\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -538,6 +656,27 @@
     "graphviz.Source(dot)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The above examples also work with {func}`.asmermaid`, for example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "source = qrules.io.asmermaid(reaction, collapse_graphs=True, render_node=False)\n",
+    "Markdown(f\"\"\"\n",
+    "```mermaid\n",
+    "{source}\n",
+    "```\n",
+    "\"\"\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -726,6 +865,41 @@
     ")\n",
     "display(graphviz.Source(dot))"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "{func}`.asmermaid` also accepts styling arguments, for example `node_style`, `edge_style`, and `figure_style`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "source = qrules.io.asmermaid(\n",
+    "    reaction.transitions[0],\n",
+    "    render_node=True,\n",
+    "    figure_style={\"bgcolor\": \"white\"},\n",
+    "    edge_style={\n",
+    "        \"color\": \"red\",\n",
+    "        \"fontcolor\": \"blue\",\n",
+    "        \"fontsize\": 25,\n",
+    "    },\n",
+    "    node_style={\n",
+    "        \"color\": \"gray\",\n",
+    "        \"fill\": \"lightgray\",\n",
+    "        \"stroke\": \"black\",\n",
+    "    },\n",
+    ")\n",
+    "Markdown(f\"\"\"\n",
+    "```mermaid\n",
+    "{source}\n",
+    "```\n",
+    "\"\"\")"
+   ]
   }
  ],
  "metadata": {
@@ -747,7 +921,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.12"
+   "version": "3.13.15"
   }
  },
  "nbformat": 4,

pyproject.toml

@@ -79,6 +79,7 @@ doc = [
     "sphinx-thebe",
     "sphinx-togglebutton",
     "sphinxcontrib-bibtex >=2",
+    "sphinxcontrib-mermaid",
     { include-group = "notebooks" },
 ]
 jupyter = [