docs: add quantum and qsystem gate definitions #912

CalMacCQ · 2025-04-08T17:07:04Z

Adding some gate definitions and doctests to the qsystem and quantum docs

added docstrings for everything along with matrix definitions of the gates (as in pytket OpType)

Theres quite a lot of freedom in convention for how we respresent this (captialisation etc). Would be interested in your thoughts.

Regarding functional gates I've just mentioned that they are the same as the std.quantum variants with different syntax. Would crosslink to the docs but would rather link to the offfical docs when they are public.

closes #857

codecov-commenter · 2025-04-08T17:09:56Z

Codecov Report

Attention: Patch coverage is 83.82353% with 11 lines in your changes missing coverage. Please review.

Project coverage is 92.29%. Comparing base (2217bbc) to head (1188e13).
Report is 27 commits behind head on main.

Files with missing lines	Patch %	Lines
guppylang/std/quantum/functional.py	18.18%	9 Missing ⚠️
guppylang/std/quantum/__init__.py	95.55%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #912      +/-   ##
==========================================
+ Coverage   92.26%   92.29%   +0.03%     
==========================================
  Files         106      112       +6     
  Lines       10406    10909     +503     
==========================================
+ Hits         9601    10069     +468     
- Misses        805      840      +35

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

guppylang/std/qsystem/__init__.py

ss2165 · 2025-04-17T09:00:08Z

Increasingly it looks like it would be handy to have a utility that defines and compiles a single function. To be used in exmamples, doc tests, prototyping, etc. @mark-koch are you opposed to adding a dedicated decorator for this? (prompted by having to call compile() at the end of the doctest)
Don't duplicate docs, cross-link to the non-functional one in each case. e.g. "Functional variant of zz_phase, see guppylang.std.qsystem.zz_phase"

mark-koch · 2025-04-17T09:23:01Z

are you opposed to adding a dedicated decorator for this?

If we use this in all examples then that's what people will copy and use themselves. So I think we have to be careful that this doesn't become an anti-pattern. In particular, it would be bad if people slapped that decorator on every function.

Also, where would you get the compiled Hugr from? Returning it from the decorator would make it hard to use those functions for comptime

ss2165 · 2025-04-17T09:31:39Z

we have to be careful that this doesn't become an anti-pattern

yes good point, what about a kwarg to @guppy that makes it clear that this is a thing you shouldn't do normally? Or a check kwarg that only does the checking stage and not compilation to hugr?

guppylang/std/qsystem/__init__.py

cqc-alec · 2025-07-04T09:42:51Z

guppylang/std/qsystem/functional.py

+"""Guppy standard module for functional qsystem native operations. For the mathematical
+definitions of these gates, see the guppylang.std.qsystem documentation.
+
+These gates are the same as those in the std.qsystem but use functional syntax.


Suggested change

These gates are the same as those in the std.qsystem but use functional syntax.

These gates are the same as those in std.qsystem but use functional syntax.

guppylang/std/quantum/__init__.py

guppylang/std/qsystem/__init__.py

Co-authored-by: Alec Edgington <[email protected]>

cqc-alec

I started going through the changes but found that my comments had been marked as resolved but not addressed. Is this due to git issues?

guppylang/std/qsystem/__init__.py

CalMacCQ · 2025-07-17T08:41:04Z

I started going through the changes but found that my comments had been marked as resolved but not addressed. Is this due to git issues?

Hmm strange. I don't know why the changes were not applied. Will fix, sorry.

Co-authored-by: Alec Edgington <[email protected]>

cqc-alec

Still some not-addressed things.

guppylang/std/qsystem/__init__.py

guppylang/std/quantum/__init__.py

cqc-alec

Just one correction missed I think.

guppylang/std/quantum/functional.py

Co-authored-by: Alec Edgington <[email protected]>

guppylang/std/qsystem/__init__.py

guppylang/std/quantum/__init__.py

Co-authored-by: Alec Edgington <[email protected]>

@Custom

🤖 I have created a release *beep* *boop* --- ## [0.21.0](guppylang-v0.20.0...guppylang-v0.21.0) (2025-08-04) ### ⚠ BREAKING CHANGES * All compiler-internal and non-userfacing functionality is moved into a new `guppylang_internals` package * `guppy.compile(foo)` and `guppy.check(foo)` replaced with `foo.check()` and `foo.compile()` * default HUGR output uses compressed binary encoding. * `guppylang.tracing.object.GuppyDefinition` moved to `guppylang.defs.GuppyDefinition` `guppylang.tracing.object.TypeVarGuppyDefinition` moved and renamed to `guppylang.defs.GuppyTypeVarDefinition` * All `to_hugr` methods on types, arguments, and parameters now require a `ToHugrContext` `CompileableDef.compile_outer` now requires a `ToHugrContext` `guppy.hugr_op` now passes the compiler context to the function generating the op `CheckedFunctionDef` now implements `MonomorphizableDef` instead of `CompileableDef` `CompilerContext.build_compiled_def` now requires an instantiation for the definition's type parameters The `ToHugrContext` protocol now requires two additional methods: `type_var_to_hugr` and `const_var_to_hugr` `CompilerContext.{compiled, worklist}` and `CompilationEngine.compiled` are now indexed by a tuple of `DefId` and optional `PartiallyMonomorphizedArgs` * comptime code that previously used constant integers outside i64 will now fail to compile. * Capturing closures are now disabled by default. Enabling them requires calling `guppylang.enable_experimental_features()`, however note that they are not supported throughout the stack. ### Features * Add `Future` type ([#1075](#1075)) ([5ad7673](5ad7673)) * add error when constant integer out of bounds ([#1084](#1084)) ([eee77ae](eee77ae)) * Add guppy version metadata to hugr entrypoint ([#1039](#1039)) ([0eafbd9](0eafbd9)), closes [#1037](#1037) * Add manual registration of extensions ([#1045](#1045)) ([4b42936](4b42936)) * add qsystem op for measure leaked ([#1057](#1057)) ([c555727](c555727)) * add selene via optional feature and use for testing ([#1081](#1081)) ([cefc70e](cefc70e)) * Add support for V and Vdg. ([#1094](#1094)) ([6b0d44a](6b0d44a)) * Allow indexing on tuples ([#1038](#1038)) ([0e9097e](0e9097e)), closes [#711](#711) * Declare WASM modules in guppy ([#942](#942)) ([e1240fb](e1240fb)) * Extend comptime arguments to arbitrary non-linear types ([#1110](#1110)) ([384dd8c](384dd8c)) * Make decorator return types more precise ([#1115](#1115)) ([c84e8b1](c84e8b1)) * set hugr entrypoint to compiled function ([#1063](#1063)) ([16bd267](16bd267)) * store used extensions and versions in HUGR metadata ([#1049](#1049)) ([a9a300c](a9a300c)), closes [#1048](#1048) * Support arbitrary const generics via monomorphisation ([#1033](#1033)) ([bcf9865](bcf9865)) * Support Python 3.12 generic syntax ([#1051](#1051)) ([ab2e118](ab2e118)), closes [#823](#823) * Top level compile + emulate Interface ([#1127](#1127)) ([5e2f595](5e2f595)) * update to hugr-py v0.13 ([#1083](#1083)) ([8f071c8](8f071c8)) * use `core.` prefix for metadata keys ([#1055](#1055)) ([2bf0d68](2bf0d68)) ### Bug Fixes * Allow array comprehension syntax in comptime functions ([#1068](#1068)) ([da8f04a](da8f04a)), closes [#1067](#1067) * Allow struct redefinitions for Python < 3.13 ([#1108](#1108)) ([959a4e4](959a4e4)), closes [#1107](#1107) * Correctly detect `[@Custom](https://github.com/custom)_guppy_decorator` in nested scopes ([#1086](#1086)) ([678583c](678583c)) * Fix diagnostics rendering for comptime entrypoints ([#1099](#1099)) ([fdd2676](fdd2676)), closes [#1097](#1097) * Fix frame lookup for Python 3.12 annotation scopes ([#1120](#1120)) ([a69e489](a69e489)), closes [#1116](#1116) * Fix hugr conversion and bounds checks on numeric literals ([#1100](#1100)) ([73d5e92](73d5e92)) * Fix Jupyter notebook diagnostic rendering ([#1109](#1109)) ([6002474](6002474)) * Fix nested function definitions in Python 3.12 ([#1064](#1064)) ([090f920](090f920)) * Stop showing temporary variables in comptime diagnostics ([#1112](#1112)) ([63854c5](63854c5)), closes [#1111](#1111) * support comptime entrypoint ([#1079](#1079)) ([721e3dd](721e3dd)) * Turn capturing closures into experimental feature ([#1065](#1065)) ([a959b18](a959b18)) ### Documentation * add docstrings for emulator module ([#1131](#1131)) ([b33e065](b33e065)) * add quantum and qsystem gate definitions ([#912](#912)) ([32a4bbc](32a4bbc)) * Fix docstrings ([#1128](#1128)) ([0aded85](0aded85)) * Improve RNG docs ([#1043](#1043)) ([8640f06](8640f06)) * replace `compile_module` usage in README ([#1041](#1041)) ([03ccf3a](03ccf3a)) * Update guppy examples ([#1121](#1121)) ([b994655](b994655)) ### Code Refactoring * Split up into `guppylang_internals` package ([#1126](#1126)) ([81d50c0](81d50c0)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: Seyon Sivarajah <[email protected]>

CalMacCQ added 5 commits April 8, 2025 17:39

docs: add some docstrings for qsystem gates

b977d66

fix a typo

0f20f61

minor fixes

0d538b7

edit measure docstring

a43628e

add a doctest

c5b1928

CalMacCQ requested a review from a team as a code owner April 8, 2025 17:07

CalMacCQ requested a review from tatiana-s April 8, 2025 17:07

CalMacCQ marked this pull request as draft April 8, 2025 17:07

qartik reviewed Apr 8, 2025

View reviewed changes

guppylang/std/qsystem/__init__.py Show resolved Hide resolved

CalMacCQ added 9 commits April 17, 2025 11:05

Merge branch 'main' into cm/qsystem_gates

9252486

rm whitespace

311af2c

Merge branch 'main' into cm/qsystem_gates

e7c6052

update ZZPhase

a0662d3

add module docstring for qsystem.functional

1001436

add a bunch of gate defs to std.quantum

e01cbc1

more definitions

e96b130

small addition

7f317bc

add docstrings for functional modules

39c60ce

CalMacCQ removed the request for review from tatiana-s July 2, 2025 14:15

CalMacCQ marked this pull request as ready for review July 2, 2025 14:15

CalMacCQ requested review from cqc-alec and ss2165 July 2, 2025 14:15

fix ch syntax

d1abab9

CalMacCQ changed the title ~~docs: add qsystem gate definitions~~ docs: add quantum and qsystem gate definitions Jul 2, 2025

cqc-alec requested changes Jul 4, 2025

View reviewed changes

Update guppylang/std/qsystem/__init__.py

c2a83d7

Co-authored-by: Alec Edgington <[email protected]>

cqc-alec requested changes Jul 17, 2025

View reviewed changes

guppylang/std/qsystem/__init__.py Outdated Show resolved Hide resolved

guppylang/std/qsystem/__init__.py Outdated Show resolved Hide resolved

guppylang/std/qsystem/__init__.py Outdated Show resolved Hide resolved

CalMacCQ and others added 3 commits July 17, 2025 12:06

Update guppylang/std/qsystem/__init__.py

cab6315

Co-authored-by: Alec Edgington <[email protected]>

zz_max consistency

6c5eca5

CRz fix

3483b5e

CalMacCQ requested a review from cqc-alec July 17, 2025 11:14

cqc-alec requested changes Jul 17, 2025

View reviewed changes

guppylang/std/qsystem/__init__.py Outdated Show resolved Hide resolved

guppylang/std/qsystem/__init__.py Outdated Show resolved Hide resolved

guppylang/std/quantum/__init__.py Outdated Show resolved Hide resolved

CalMacCQ added 2 commits July 17, 2025 14:02

don't use pi factors in matrix definitions for parametrised gates

e683ab0

fix ry definition

72983c2

CalMacCQ requested a review from cqc-alec July 17, 2025 13:12

cqc-alec reviewed Jul 17, 2025

View reviewed changes

guppylang/std/quantum/functional.py Outdated Show resolved Hide resolved

Update guppylang/std/quantum/functional.py

7581a8e

Co-authored-by: Alec Edgington <[email protected]>

cqc-alec approved these changes Jul 17, 2025

View reviewed changes

CalMacCQ enabled auto-merge July 17, 2025 13:26

cqc-alec requested changes Jul 17, 2025

View reviewed changes

guppylang/std/qsystem/__init__.py Outdated Show resolved Hide resolved

cqc-alec requested changes Jul 17, 2025

View reviewed changes

guppylang/std/quantum/__init__.py Outdated Show resolved Hide resolved

guppylang/std/quantum/__init__.py Outdated Show resolved Hide resolved

CalMacCQ disabled auto-merge July 17, 2025 14:12

CalMacCQ and others added 3 commits July 17, 2025 15:12

Update guppylang/std/quantum/__init__.py

e1f8b10

Co-authored-by: Alec Edgington <[email protected]>

Update guppylang/std/quantum/__init__.py

06d64ef

Co-authored-by: Alec Edgington <[email protected]>

fix missing pi factors

1188e13

cqc-alec approved these changes Jul 17, 2025

View reviewed changes

CalMacCQ enabled auto-merge July 17, 2025 14:35

ss2165 approved these changes Jul 17, 2025

View reviewed changes

CalMacCQ added this pull request to the merge queue Jul 17, 2025

Merged via the queue into main with commit 32a4bbc Jul 17, 2025
5 checks passed

CalMacCQ deleted the cm/qsystem_gates branch July 17, 2025 17:26

hugrbot mentioned this pull request Jul 17, 2025

chore(main): release 0.21.0 #1042

Closed

hugrbot mentioned this pull request Aug 4, 2025

chore: release guppylang 0.21.0 #1135

Merged

	These gates are the same as those in the std.qsystem but use functional syntax.
	These gates are the same as those in std.qsystem but use functional syntax.

docs: add quantum and qsystem gate definitions #912

docs: add quantum and qsystem gate definitions #912

Uh oh!

Conversation

CalMacCQ commented Apr 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Apr 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

ss2165 commented Apr 17, 2025

Uh oh!

mark-koch commented Apr 17, 2025

Uh oh!

ss2165 commented Apr 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cqc-alec Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cqc-alec left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CalMacCQ commented Jul 17, 2025

Uh oh!

cqc-alec left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cqc-alec left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

CalMacCQ commented Apr 8, 2025 •

edited

Loading

codecov-commenter commented Apr 8, 2025 •

edited

Loading