docs: add modifier documentation by nicolaassolini-qntm · Pull Request #182 · Quantinuum/guppy-docs

nicolaassolini-qntm · 2026-07-13T16:54:45Z

closes #98

…ctions, modifiers on classical functions

nicolaassolini-qntm · 2026-07-14T09:56:24Z

@CalMacCQ I think the page is almost ready, a part of the QFT example (and a section about @compite with flags?) If you want to take a look now before adding the final examples, I think it can be useful.

Copilot

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

nicolaassolini-qntm · 2026-07-14T13:52:22Z

@CalMacCQ, I also added a Grover example. I think it is ready now. We only miss Unitary callable but I would add them when we are sure that they are not going to be experimental anymore

…tion

nicolaassolini-qntm · 2026-07-16T12:24:25Z

We have to wait for Quantinuum/guppylang#2061 to be merged

CalMacCQ

This is a great start. Thanks for this.

I have yet to read this thoroughly but here are some quick comments.

I'll take another look tomorrow.

Co-authored-by: Callum Macpherson <93673602+CalMacCQ@users.noreply.github.com>

dunc-go · 2026-07-17T13:10:49Z

+
+## Control flow
+
+When a controlled block contains control flow, the control is pushed to every quantum operation produced by the branch or loop. Evaluating the classical condition and loop bounds is not controlled. For instance, the following two programs are equivalent:


the guppy logic here is so clean and demonstrative you could maybe reverse this section - 'These are equivalent.. this is because classical conditioning and loops are not part of the with control modification'

I see, but I'm sure how to organize the session 🤔

dunc-go

Really appreciate the effort here.

Top level comment: I think this page should be split into 3 pages.
One is a top level explanation of the syntax and general properties of modifiers and maybe function flags. Then I think each modifier (control and syntax for now) can have their own pages with their specific properties (forbiddens etc) and then finally a 3rd page with examples such the conjugation box and the grovers.

CalMacCQ · 2026-07-20T19:08:41Z

+    h(q)
+    with control(c):
+        x(q)
+    bit_c =measure(c)


Nit:

Suggested change

bit_c =measure(c)

bit_c = measure(c)

CalMacCQ · 2026-07-20T19:09:31Z

+from guppylang.std.quantum import qubit, x, h, measure
+
+@guppy
+def controlled_x() -> None:


I wouldn't use CX here. In general people should be using modifiers for gates which do not exist in std.quantum

CalMacCQ · 2026-07-20T19:10:43Z

+controlled_inverse.check()
+```
+
+Here we take the S gate and modify it with control and dagger. This gate has a known form of control and daggering, and the operations are compatible. Therefore, when we check the program (compile), the code passes. When applied, this function acts as a C-S^\dag gate


Suggested change

Here we take the S gate and modify it with control and dagger. This gate has a known form of control and daggering, and the operations are compatible. Therefore, when we check the program (compile), the code passes. When applied, this function acts as a C-S^\dag gate

Here we take the $S$ gate and modify it with control and dagger. This gate has a known form of control and daggering, and the operations are compatible. Therefore, we can successfully type check the program. When applied, this function acts as a $CS^\dagger$ gate

I am not sure what this sentance means

"This gate has a known form of control and daggering, and the operations are compatible"

Is this just saying that the gate is unitary and therefore we can add a control to it?

CalMacCQ · 2026-07-20T19:14:13Z

+
+invert_rotations.check()
+```
+


I don't think qasm should be necesary here. I think just the three backticks should be fine.

CalMacCQ · 2026-07-20T19:14:59Z

+    with dagger:
+        output("value", True)
+
+output_in_dagger.check()


I think in rc2 this will give an error as expected.

CalMacCQ · 2026-07-20T19:15:27Z

+C[U] = (I \otimes V)\, C[A]\, (I \otimes V^\dagger).
+$$
+
+This avoids controlling every operation in `V` and can substantially reduce the number of controlled, entangling gates.


Suggested change

This avoids controlling every operation in `V` and can substantially reduce the number of controlled, entangling gates.

This avoids controlling every operation in $V$ and can substantially reduce the number of controlled, entangling gates.

CalMacCQ · 2026-07-20T19:19:38Z

+U = V A V^\dagger.
+$$
+
+The first part computes a basis change, `A` performs the action, and the final part uncomputes the basis change. This is a conjugation box.


Suggested change

The first part computes a basis change, `A` performs the action, and the final part uncomputes the basis change. This is a conjugation box.

The first part computes a basis change, `A` performs the action, and the final part uncomputes the basis change. This is a conjugation pattern.

CalMacCQ · 2026-07-20T19:20:07Z

+controlled_conjugation.check()
+```
+
+#### Conjugation box with Pauli gadget


Suggested change

#### Conjugation box with Pauli gadget

#### Conjugation pattern with Pauli exponential

CalMacCQ · 2026-07-20T19:20:43Z

+
+The resulting quantum operations are equivalent to:
+
+```qasm


Is the qasm annotation needed here?

CalMacCQ · 2026-07-20T19:23:40Z

+
+## Syntax
+
+Use modifiers in a `with` statement.


Suggested change

Use modifiers in a `with` statement.

We can make use of modifiers inside a context manager using the `with` keyword.

CalMacCQ · 2026-07-20T19:24:41Z

+
+Use modifiers in a `with` statement.
+
+Start with the simplest form: a single modifier on a single operation.


Suggested change

Start with the simplest form: a single modifier on a single operation.

Let’s start with a simple example of a controlled single-qubit operation. We will realize this with the `control` modifier.

CalMacCQ · 2026-07-20T19:29:49Z

+from guppylang.std.quantum import rz
+
+@guppy
+def invert_rotations(q: qubit) -> None:


This example snippet seems to not execute without error on C.I.

nicolaassolini-qntm added 2 commits July 13, 2026 16:56

modifier base

456d3fc

syntax

4e2bcdd

nicolaassolini-qntm changed the title ~~doc: add modifier documentation~~ docs: add modifier documentation Jul 13, 2026

nicolaassolini-qntm added 8 commits July 13, 2026 18:02

Function flags

2edc65b

Add modifiers section to language guide index

6836528

fixed modifiers examples

071afe7

added function flags, first coj box, more structured forbidden instru…

a463d40

…ctions, modifiers on classical functions

Add conjugation box example with Pauli gadget to modifiers documentation

310deaa

Add conjugation box example using functions to modifiers documentation

c1844f3

complete loading sections

b957e7c

little fixes

311aadb

nicolaassolini-qntm marked this pull request as ready for review July 14, 2026 09:54

nicolaassolini-qntm requested a review from CalMacCQ as a code owner July 14, 2026 09:54

nicolaassolini-qntm requested a review from Copilot July 14, 2026 12:10

Copilot started reviewing on behalf of nicolaassolini-qntm July 14, 2026 12:10 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

nicolaassolini-qntm added 3 commits July 14, 2026 13:24

added comptime section

aa7fcba

fixed comptime

2ddfe49

Add Grover search example to modifiers documentation

ae18645

Merge remote-tracking branch 'origin/main' into na/modifier-documenta…

2f8a6d2

…tion

added new flags explanation

b255702

CalMacCQ reviewed Jul 16, 2026

View reviewed changes

CalMacCQ requested a review from dunc-go July 16, 2026 17:03

Update sphinx/language_guide/modifiers.md

b7aaef6

Co-authored-by: Callum Macpherson <93673602+CalMacCQ@users.noreply.github.com>