FEAT: add Mermaid graph rendering by Flomber · Pull Request #347 · ComPWA/qrules

Flomber · 2026-08-18T12:22:49Z

Closes #159

✨ New features

New qrules.io.asmermaid() function that renders Topology, MutableTransition, ReactionInfo, ProblemSet, QNProblemSet, and QNResult objects as Mermaid flowchart source. It mirrors the signature of asdot(), including strip_spin, collapse_graphs, the render_*_id flags, and figure_style/edge_style/node_style for styling the diagram, its edges, and its nodes.
qrules.io.write() now recognizes the .mmd file extension and writes Mermaid source, either from a graph-like object or from a string produced by asmermaid().
The documentation now renders Mermaid diagrams natively: sphinxcontrib-mermaid is enabled in docs/conf.py and docs/usage/visualize.ipynb shows Mermaid examples next to the existing Graphviz ones.

🐛 Bug fixes

Rule priorities in ProblemSet and QNProblemSet labels were sorted as strings, so 9 sorted above 100 and rules without a priority (NA) ended up at the top. Priorities are now parsed as numbers (negative values included) and NA sorts last.
collapse_graphs() iterated over its input twice, which silently produced an empty result when given a generator instead of a list. The input is now materialized first.
strip_projections() contained a dead freeze() branch whose result was immediately overwritten.

🔨 Maintenance

Label rendering that is shared between the Graphviz and Mermaid printers — as_string(), create_edge_label(), collapse_graphs(), get_particle_graphs(), and strip_projections() — moved out of qrules.io._dot into a new qrules.io._labels module, so both backends produce identical labels from a single implementation.

Squash commit messages

* DOC: show Mermaid examples in visualize notebook
* FEAT: write Mermaid source to `.mmd` files
* FIX: consume iterators in `collapse_graphs()`
* FIX: sort rule priorities numerically
* MAINT: move shared label rendering to `qrules.io._labels`

…tests and documentation

…mermaid in Jupyter notebooks - Updated the visualize_mermaid.ipynb to use asmermaid for generating Mermaid source directly. - Removed show_mermaid_markdown function and integrated its functionality into asmermaid. - Adjusted documentation and examples to reflect the new usage of asmermaid. - Cleaned up the io module by consolidating Mermaid-related functions and removing unnecessary code. - Enhanced tests to verify the new asmermaid functionality and removed tests related to the deprecated show_mermaid_markdown.

…ebook with few mermaid examples and fix references

…tic newline in visualize.ipynb

Flomber · 2026-08-20T13:11:32Z

Found issue with rendering long lines eg. in graph edges.

isospin_magnitude ∊ [0, 1/2, 1, 3/2 ]

gets displayed as

isospin_magnitude ∊ [0, 1/2, 1, 3/2

redeboer

Good job! 💯
Some smaller comments below.

One general thought I had: it seems that Mermaid (as opposed to Graphviz) supports LaTeX, even if not for all backends. Rewriting the example of #159:

```mermaid
graph LR
    A["$$J/\psi$$"] --> N0[ ]
    N0 --> N1["$$f_0(980)$$"]
    N0 --> 0[$$\gamma$$]
    N1 --> 1[$$\pi^0$$]
    N1 --> 2[$$\pi^0$$]
    style A fill:#FFFFFF, stroke:#FFFFFF;
    style N0 fill:#FFFFFF, stroke:#FFFFFF;
    style N1 fill:#FFFFFF, stroke:#FFFFFF;
    style 0 fill:#FFFFFF, stroke:#FFFFFF;
    style 1 fill:#FFFFFF, stroke:#FFFFFF;
    style 2 fill:#FFFFFF, stroke:#FFFFFF;
```

Maybe worth posting a follow-up issue. Similarly to #348, one could select LaTeX as rendering with a flag, for instance.

Rendering on Sphinx

Rendering on VS Code Jupyter

Rendering on Jupyter Lab

Rendering on GitHub ❌

graph LR
    A["$$J/\psi$$"] --> N0[ ]
    N0 --> N1["$$f_0(980)$$"]
    N0 --> 0[$$\gamma$$]
    N1 --> 1[$$\pi^0$$]
    N1 --> 2[$$\pi^0$$]
    style A fill:#FFFFFF, stroke:#FFFFFF;
    style N0 fill:#FFFFFF, stroke:#FFFFFF;
    style N1 fill:#FFFFFF, stroke:#FFFFFF;
    style 0 fill:#FFFFFF, stroke:#FFFFFF;
    style 1 fill:#FFFFFF, stroke:#FFFFFF;
    style 2 fill:#FFFFFF, stroke:#FFFFFF;

…bled and also switched edge style from arrows to lines

redeboer · 2026-08-21T09:49:37Z

+    def __init__(
+        self,
+        *,
+        render_node: bool | None = None,
+        render_final_state_id: bool = True,
+        render_resonance_id: bool = False,
+        render_initial_state_id: bool = False,
+        strip_spin: bool = False,
+        collapse_graphs: bool = False,
+        figure_style: dict[str, Any] | None = None,
+        edge_style: dict[str, Any] | None = None,
+        node_style: dict[str, Any] | None = None,
+    ) -> None:
+        self.render_node = render_node
+        self.render_final_state_id = render_final_state_id
+        self.render_resonance_id = render_resonance_id
+        self.render_initial_state_id = render_initial_state_id
+        self.strip_spin = strip_spin
+        self.collapse_graphs = collapse_graphs
+        self.figure_style = dict(figure_style) if figure_style else {}
+        self.edge_style = dict(edge_style) if edge_style else {}
+        self.node_style = dict(node_style) if node_style else {}


Better to declare this class with @attrs.define to reduce boilerplate code, just like GraphPrinter, which is declared with @define(on_setattr=_check_booleans).

Does this definition satisfies this?
Also AI mentioned, that in the definition of the GraphvizPrinter class has the weakness, that it also accepts invalid constructor combinations.
Should this also be fixed? A shared attrs validator was a recommendation.

Does this definition satisfies this?

Yes, looks good!

Also AI mentioned, that in the definition of the GraphvizPrinter class has the weakness, that it also accepts invalid constructor combinations.

You mean that GraphPrinter does not set kw_only=True? Or because its fields have different validators/converts?

Since it makes sense to rename GraphPrinter to GraphvizPrinter now, I am considering if this is something of a larger issue that should be handled separately. But these modules are private (due to the underscore), so renaming GraphPrinter is technically not a breaking change and fits well with the intentions of rest of this PR (an extension of the io module with a new printer).

So yeah, I think it's a good idea to do that additional cleanup in this PR.

…y into seperate _labels.py module

Flomber · 2026-08-21T17:24:51Z

Except for checking the width of the edge labels, the issue might be ready to be closed. 🎊
I also tried to make the label boxes transparent, but this didn't quiet work out, so I stoped trying 😞

redeboer

Looks good! But let's discuss your comment #347 (comment) about the GraphPrinter class next week. It may be worth fixing that in this PR too.

redeboer · 2026-08-21T19:12:52Z

+    def __init__(
+        self,
+        *,
+        render_node: bool | None = None,
+        render_final_state_id: bool = True,
+        render_resonance_id: bool = False,
+        render_initial_state_id: bool = False,
+        strip_spin: bool = False,
+        collapse_graphs: bool = False,
+        figure_style: dict[str, Any] | None = None,
+        edge_style: dict[str, Any] | None = None,
+        node_style: dict[str, Any] | None = None,
+    ) -> None:
+        self.render_node = render_node
+        self.render_final_state_id = render_final_state_id
+        self.render_resonance_id = render_resonance_id
+        self.render_initial_state_id = render_initial_state_id
+        self.strip_spin = strip_spin
+        self.collapse_graphs = collapse_graphs
+        self.figure_style = dict(figure_style) if figure_style else {}
+        self.edge_style = dict(edge_style) if edge_style else {}
+        self.node_style = dict(node_style) if node_style else {}


Does this definition satisfies this?

Yes, looks good!

Also AI mentioned, that in the definition of the GraphvizPrinter class has the weakness, that it also accepts invalid constructor combinations.

You mean that GraphPrinter does not set kw_only=True? Or because its fields have different validators/converts?

Since it makes sense to rename GraphPrinter to GraphvizPrinter now, I am considering if this is something of a larger issue that should be handled separately. But these modules are private (due to the underscore), so renaming GraphPrinter is technically not a breaking change and fits well with the intentions of rest of this PR (an extension of the io module with a new printer).

So yeah, I think it's a good idea to do that additional cleanup in this PR.

Add Mermaid graph rendering parallel to Graphvis rendering including …

cb8e20a

…tests and documentation

Flomber requested a review from redeboer August 18, 2026 12:22

Flomber added the ✨ Feature New feature added to the package label Aug 18, 2026

Flomber and others added 6 commits August 18, 2026 14:35

Merge branch 'main' into Mermaidrendering

8f2ca31

MAINT: implement pre-commit autofixes

b3f2da9

MAINT: implement updates from formatters

646781c

MAINT: implement pre-commit autofixes

cfa59e8

MAINT: implement updates from formatters

7e9a03b

redeboer changed the title ~~Add Mermaid graph rendering parallel to Graphvis rendering including …~~ FEAT: add Mermaid graph rendering Aug 19, 2026

redeboer and others added 3 commits August 19, 2026 15:26

MAINT: fix mypy problem

85e300e

Fix references of old visualize notebook

67f9520

MAINT: implement updates from formatters

83829af

This comment was marked as resolved.

Sign in to view

Flomber and others added 4 commits August 19, 2026 16:32

Fix rendering issue on website

d79c997

MAINT: implement pre-commit autofixes

93f9260

MAINT: implement updates from formatters

e04753f

Kick CI

3dc6947

redeboer requested changes Aug 19, 2026

View reviewed changes

Comment thread docs/usage/visualize.ipynb

Comment thread docs/usage.ipynb Outdated

redeboer mentioned this pull request Aug 19, 2026

Trailing newline in a cell is not stripped ComPWA/nbhooks#7

Closed

redeboer reviewed Aug 19, 2026

View reviewed changes

Comment thread docs/usage/visualize_mermaid.ipynb

redeboer mentioned this pull request Aug 19, 2026

FIX: strip trailing newlines from notebook cells ComPWA/nbhooks#8

Merged

redeboer and others added 5 commits August 19, 2026 17:36

DX: strip newlines with ComPWA/nbhooks@68b087e

9f83bde

Add mermaid examples into 'visualize_dot.ipynb'

2c1e010

Replace visualize_dot and visualize_mermaid with merged visualize not…

f5f606b

…ebook with few mermaid examples and fix references

Fix double reference of visualize.ipynb in usage.ipynb and add stylis…

b8d5971

…tic newline in visualize.ipynb

MAINT: reduce diff

4c59a19

redeboer force-pushed the Mermaidrendering branch from b024f39 to 4c59a19 Compare August 20, 2026 13:15

redeboer added 2 commits August 20, 2026 15:35

MAINT: minor formatting issues

0f8b6c2

DOC: hide input cells of Mermaid examples

c47bf92

redeboer requested changes Aug 20, 2026

View reviewed changes

Comment thread pyproject.toml Outdated

Comment thread .cspell.json Outdated

Comment thread docs/usage/visualize.ipynb

Comment thread docs/usage/visualize.ipynb

Comment thread docs/usage/visualize_mermaid.ipynb

redeboer assigned Flomber Aug 20, 2026

redeboer requested changes Aug 20, 2026

View reviewed changes

Comment thread src/qrules/io/_mermaid.py

Flomber added 2 commits August 20, 2026 17:42

Remove unnecessary dependencies

42b2552

Fix issue with node and node id beeing rendered, when flags were disa…

9329393

…bled and also switched edge style from arrows to lines

redeboer mentioned this pull request Aug 20, 2026

LaTeX in Mermaid labels #349

Open

reduce diff

9b30be0

redeboer requested changes Aug 21, 2026

View reviewed changes

ComPWA deleted a comment from review-notebook-app Bot Aug 21, 2026

Flomber added 8 commits August 21, 2026 16:52

Merge functions for rendering labels etc. from _dot.py and _mermaid.p…

b41e903

…y into seperate _labels.py module

Make escape label translation more stable

2a31073

Define MermaidPrinter class with a constructor

8c3eed0

Make styling mapping module-level based

e9a7366

Remove redundant freeze in func strip_projections

d2cc85f

Fix priority sorting issue

ed8b685

Fix iteration issue in {func} collapse_graphs

34b69a9

Add style of rendering shown in #159 (comment)

6d36ff2

redeboer added 4 commits August 21, 2026 21:38

DX: add doctest to __extract_priority()

d9b1f1a

MAINT: reduce diff

b4fcd8f

MAINT: unpack tuple

a8003fe

MAINT: reorganize tests to match module structure

cf9abf0

redeboer added 🔨 Maintenance Maintenance and upkeep improvements 🐛 Bug Something isn't working labels Aug 21, 2026

redeboer reviewed Aug 21, 2026

View reviewed changes

Uh oh!

Conversation

Flomber commented Aug 18, 2026 • edited by redeboer Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✨ New features

🐛 Bug fixes

🔨 Maintenance

Squash commit messages

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Flomber commented Aug 20, 2026

Uh oh!

redeboer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

redeboer Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

Flomber Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

redeboer Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Flomber commented Aug 21, 2026

Uh oh!

redeboer left a comment

Choose a reason for hiding this comment

Uh oh!

redeboer Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Flomber commented Aug 18, 2026 •

edited by redeboer

Loading