test: Add some example guppy-generated hugrs #904

aborgna-q · 2025-06-06T12:33:56Z

Adds guppy program examples described by @cqc-alec in Quantinuum/hugr#2246.

These are example programs intended to test compiler passes internally. We are not interested in testing guppy here but rather programs that resemble guppy's compilation output in their structure, hence why we use a pinned guppy version and don't enforce the artifacts to be up-to-date.

We also generate .mmd mermaid diagrams if the example defines a .generate_mmd marker file.

aborgna-q · 2025-06-06T13:17:02Z

false branches
branches that depend on function inputs (and get inlined)
Array indexing
Panic elision?

aborgna-q · 2025-06-10T11:18:01Z

~~Currently waiting for the model-loading error to be fixed, so we can generate non-empty mermaids.~~

acl-cqc

Thanks @aborgna-q ! Nice, mostly just inconsistencies in the README... and that versionning question

test_files/guppy_optimization/justfile

acl-cqc · 2025-08-18T09:41:05Z

test_files/guppy_optimization/simple_cx/simple_cx.opt.py

+
+@guppy
+def main() -> None:
+    pass


The idea is that the measurements are not returned here?? I mean, if so couldn't we elide any series of gates if we are not doing anything to measure them?

Right!
I added a result(.., measurement(q)) side-effect to all the scripts, so they don't get DCE'd.

test_files/guppy_optimization/README.md

acl-cqc · 2025-08-18T09:42:35Z

test_files/guppy_optimization/README.md

+
+Each example here contains:
+- A `.py` file that defines the guppy program
+- If possible, a `.flat.py` file that defines the same program using `comptime` or manual loop peeling.


You say "if possible" - and all examples have one except "simple_cx" - I don't see any reason why one couldn't define even that program using comptime - do you mean "if different"? (if the Hugr result is different, if the result of optimization is expected to be different?)

Or, perhaps we should just include a simple_cx_flat using comptime ?

I'll leave this for when we implement the tests. We can add the missing one if required.

acl-cqc · 2025-08-18T09:44:50Z

test_files/guppy_optimization/README.md

+Each example here contains:
+- A `.py` file that defines the guppy program
+- If possible, a `.flat.py` file that defines the same program using `comptime` or manual loop peeling.
+- A `.opt.py` file that defines the optimized version of the program, which we


Do we actually mean we expect identical Hugrs (the original optimized by compiler, and the hand-one without compiler optimization)?

I might just say "a hand-optimized version" and then (perhaps depending on what you mean here) "indicative of the greatest optimization we believe can be achieved"

test_files/guppy_optimization/README.md

acl-cqc · 2025-08-18T09:49:55Z

test_files/guppy_optimization/justfile

+    @# Find all examples in subdirectories and re-run them.
+    for example in $(find . -type f -name "*.py"); do
+        echo "Re-generating $example"
+        uvx --with 'guppylang==0.21.2' python "$example"


Presumably (inferring from, rather than finding in, the docs) this means guppylang does not need to be installed?

I expect that at some point we will want to have multiple .hugr files for different guppy versions. So I'm wondering whether we should include the version in the .hugr filename starting now. If you think it'll be ok to add this in a later PR, then ok.

Removed the version here and added uv script headers on each file instead.
Now each example defines the guppy and python versions it needs.

acl-cqc · 2025-08-18T09:52:38Z

test_files/guppy_optimization/false_branch/false_branch.opt.py

+
+
+program = main.compile()
+Path(argv[0]).with_suffix(".hugr").write_bytes(program.to_bytes())


An alternative might be to write the bytes to stdout and for justfile to redirect them to a computed filename. (Avoids some duplication of output-filename-computation, but indeed writing bytes to stdout is a bit messy!) This might be better if we want to include guppy version in the filename, as per other comment...?

Yeah, I though about having a utils.py file too, but that's problematic when you have standalone python files.

Co-authored-by: Alan Lawrence <[email protected]>

acl-cqc

Nice @aborgna-q! Thanks :).

Like the scheme where the /// script specifies the version for each example.

One thought - do we actually want to check the .mmd's in? Seems like it introduces extra variation/fragility from the mermaid-generator; if the hugr hasn't changed but the mermaid has, we probably don't care here, and if the hugr has changed but the mermaid hasn't, well, thankfully the hugr having changed will probably make some noise ;). Otherwise, we could just .gitignore them?

acl-cqc · 2025-09-01T10:40:39Z

test_files/guppy_optimization/justfile

+    echo "Re-generating hugr diagrams"
+    cargo install hugr-cli
+    # Find directories containing a `.generate_mmd` file
+    for dir in $(find . -type f -name ".generate_mmd" -exec dirname {} \;); do


snazzy!! 👍

aborgna-q · 2025-09-01T15:15:39Z

Added the .mmds to a local gitignore.
Now the diagrams have to be generated on-demand by running just mermaid

Add test pass runs over the circuits from #904. Some notable issues: - The constant folding pass (and DCE) fails on some cases, leaving unconnected qubit ports. Quantinuum/hugr#2557 Should be fixed on Quantinuum/hugr#2560 - (Requires Hugr `0.22.4` / `0.23` release) - The basic-block merge rewrite should define a composable pass. Quantinuum/hugr#2556 - We are missing a simple `InlineCFG` pass to unwrap simple linear CFGs. (Either single blocks, or it can be conbined with `merge_bbs`). Quantinuum/hugr#945 If we fix those, we should be able to `assert!` that some of the examples here optimize to the identity. We'll need to call pytket optimisations for the rest. - ~Requires a `hugr 0.22.3` release with this fix: Quantinuum/hugr#2549 - Requires #1118

aborgna-q requested a review from a team as a code owner June 6, 2025 12:33

aborgna-q requested a review from doug-q June 6, 2025 12:33

aborgna-q mentioned this pull request Jun 6, 2025

Sample programs that "must" be optimized/flattened Quantinuum/hugr#2246

Closed

aborgna-q marked this pull request as draft June 6, 2025 12:34

aborgna-q removed the request for review from doug-q June 6, 2025 12:35

aborgna-q force-pushed the ab/guppy-generated-hugrs branch from 58623d5 to 1ccc8ac Compare June 10, 2025 11:15

aborgna-q added 5 commits August 13, 2025 10:19

test: Add some example guppy-generated hugrs

18805eb

Limit which examples get mermaid graphs

d79433d

true/false branches

c40af14

Use guppy 0.20

dc2dfa3

Update to guppy 0.21.2 and regenerate

2dde95a

aborgna-q force-pushed the ab/guppy-generated-hugrs branch from 1696695 to 2dde95a Compare August 13, 2025 09:25

aborgna-q requested a review from acl-cqc August 13, 2025 09:39

aborgna-q marked this pull request as ready for review August 13, 2025 09:46

Use default envelope config

2f43126

aborgna-q force-pushed the ab/guppy-generated-hugrs branch from fdb1dbf to 2f43126 Compare August 13, 2025 09:55

acl-cqc reviewed Aug 18, 2025

View reviewed changes

Update test_files/guppy_optimization/README.md

6c3cc59

Co-authored-by: Alan Lawrence <[email protected]>

This was referenced Aug 20, 2025

Add BorrowArray example Hugrs #1055

Open

Benchmarks using fixed-Hugr inputs #1056

Open

aborgna-q added 3 commits August 20, 2025 14:02

Use uv scripts to pin guppy version per-file

e660138

Add side effects to avoid the scripts being DCE'd

606dd34

README comments

4049250

aborgna-q requested a review from acl-cqc August 20, 2025 13:47

acl-cqc approved these changes Sep 1, 2025

View reviewed changes

Don't commit generated mermaids

979f08c

aborgna-q enabled auto-merge September 1, 2025 15:15

aborgna-q added this pull request to the merge queue Sep 1, 2025

Merged via the queue into main with commit ab81422 Sep 1, 2025
16 checks passed

aborgna-q deleted the ab/guppy-generated-hugrs branch September 1, 2025 15:20

aborgna-q mentioned this pull request Sep 15, 2025

test: Optimize and validate guppy hugr examples #1116

Merged



		program = main.compile()
		Path(argv[0]).with_suffix(".hugr").write_bytes(program.to_bytes())

test: Add some example guppy-generated hugrs #904

test: Add some example guppy-generated hugrs #904

Uh oh!

Conversation

aborgna-q commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aborgna-q commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aborgna-q commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

acl-cqc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

acl-cqc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aborgna-q commented Sep 1, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aborgna-q commented Jun 6, 2025 •

edited

Loading

aborgna-q commented Jun 6, 2025 •

edited

Loading

aborgna-q commented Jun 10, 2025 •

edited

Loading