feat!: support `@expected_qubits` hint in Clifford verifier by CalMacCQ · Pull Request #328 · Quantinuum/guppyft

CalMacCQ · 2026-09-08T10:04:11Z

closes #223

This PR allows the user to specify the number of qubits required by an impl_function passed to valid_clifford_implementation or valid_stabilizer_state_preparation with an @expected_qubits hint. This will allow them to check an impl_function that uses ancillas and avoid specifiying an impl_num_ancillas argument to valid_clifford_implementation or valid_stabilizer_state_preparation .

    @guppy
    @expected_qubits(7 + 14) # 7 for a Steane block, 14 ancillas
    def impl_func(arr: array[qubit, 7]) -> None:
        block = LogicalBlock(array(arr.take(i) for i in range(7)))

        a0 = prep_zero_non_ft()
        a1 = prep_zero_non_ft()
        knill_qec_cycle(block, a0, a1)

        block.put_into_array(arr)
    
    # no "impl_num_ancillas" arg needed here, specified instead as a decoration of the impl
    assert valid_clifford_implementation(specify_identity, impl_func, CODE_DEF)

impl_num_ancillas is now an optional argument (set to None by default). In the event that both impl_num_ancillas and @expected_qubits are specified, impl_num_ancillas will be used. This is consistent with the guppy/selene behaviour for @expected_qubits. See the test_hint_override function in test_verifier_steane.py

Note that we are annotating functions which are not entrypoints, therefore I am reading off the @expected_qubits metadata with the _get_num_func_qubits helper and pass it on. Not entirely happy with it. See #328 (comment).

BREAKING CHANGE:

The impl_num_ancillas arg to valid_stabilizer_state_preparation and valid_clifford_implementation is no longer an int. Its now of type int | None.

PabloAndresCQ

Looks good overall. I'll have a closer look when you mark it as ready for review. Request a re-review at that point.

PabloAndresCQ · 2026-09-08T14:55:01Z

    semantic_function: SemanticStabilizerState | SemanticStabilizerStateDouble,
    impl_function: ImplementationStabilizerState | ImplementationStabilizerStateDouble,
    code_definition: StabilizerCode,
-    impl_num_ancillas: int = 0,


We've agreed this should be kept as an optional parameter that overrides the @expected_qubits decorator if present. It should become impl_num_ancillas: int | None = None so that you can identify whether or not the user provided anything that is not None.

Just writing it here so we don't miss it.

…semantic simulation

This reverts commit 3cbece5.

CalMacCQ · 2026-09-16T12:31:45Z

+    if num_ancilla_qubits > 0:
+        return num_qubits + num_ancilla_qubits
+
+    metadata = func.wrapped.metadata._node_metadata  # type: ignore[attr-defined]


I don't like using ._node_metadata here.

As far as I understand it should also work to do the following with __guppy_metadata__ (more reliable?)

from guppylang.decorator import expected_qubits, guppy from guppylang.std.quantum import qubit, h @guppy @expected_qubits(8) def steane_impl_h(block: array[qubit, 7]) -> None: for i in range(len(block)): h(block[i]) num = steane_impl_h.wrapped.python_func.__guppy_metadata__['tket.hint.expected_qubits']

This example works but if I try and use this inside _get_num_func_qubits I get an error. I think this is becuase I should try-except on the AttributeError rather than using .get(). Not totally sure. Any ideas?

Would you prefer

using ._node_metadata and .get() as is done currently

Avoid using ._node_metadata and use __guppy_metadata__ but use a try-except on the AttributeError (or whatever else is needed to make __guppy_metadata__ work reliably. __hasattr__ would probably work as well actually.

we could compile the function and read the metadata from the HUGR. However this doesn't seem ideal either as we wouldn't compile the function otherwise as it isn't an entrypoint.

CalMacCQ · 2026-09-16T12:33:40Z

-    states_dict: dict[str, SeleneStimState] = _invoke_selene_stim(
-        main, num_selene_qubits
-    )
+    states_dict: dict[str, SeleneStimState] = _invoke_selene_stim(main, num_qubits)


I could technically use an expected_qubits hint on the main function. This would require refactoring _invoke_selene_stim to respect the hint though. I think this requires making use of the Guppy .emulator() interface rather than selene_sim.

Why would adding expected_qubits be required? Is there a reason to have a helper function to invoke selene rather than just using .emulator() already?

Using @expected_qubits on main isn't necessary, its merely an option.

Yes tbh we should use the guppy .emulator() interface instead and get rid of/modify _invoke_selene_stim. Extracting state outputs for stabilizer simulation with the Guppy interface is undocumented (also untested in guppylang seemingly?). I was going to do some cleanup to use the Guppy interface directly. Would you prefer this to be done here or in a follow up PR?

CalMacCQ · 2026-09-16T12:53:34Z

+    # If the user specifies an impl_num_ancillas argument in
+    # valid_clifford_implementation or valid_stabilizer_state_preparation this
+    #  will override any @expected_qubits metadata.
+    if num_ancilla_qubits > 0:


Maybe if num_ancilla_qubits: is better? Although people shouldn't be passing negative values.

hsemenenko

Some initial comments.

hsemenenko · 2026-09-16T13:52:27Z

There's a comment from Pablo that the default should be int | None = None. Is there a reason that it's not? Someone may want to override the number of ancillas to be 0, but if the default is 0 that's not possible.

hsemenenko · 2026-09-16T15:36:30Z

+    num_qubits: int,
+    num_ancilla_qubits: int = 0,


Is it necessary to have both inputs here (and other _compute functions)? It seems like num_qubits could already be the total number of qubits required.

hsemenenko · 2026-09-16T15:38:49Z

+    if num_ancilla_qubits > 0:
+        return num_qubits + num_ancilla_qubits
+
+    metadata = func.wrapped.metadata._node_metadata  # type: ignore[attr-defined]


Perhaps this is better?

Suggested change

metadata = func.wrapped.metadata._node_metadata # type: ignore[attr-defined]

assert isinstance(func.wrapped, RawFunctionDef)

metadata = func.wrapped.metadata["tket.hint.expected_qubits"]

Building on this I thought I was getting somewhere with

assert isinstance(func.wrapped, RawFunctionDef) assert isinstance(func.wrapped.metadata, FunctionMetadata) num_hinted_qubits: int | None func.wrapped.metadata.get_expected_qubits()

However if I use this my code seems to hang when running the test suite which is really strange.

Seems to work now... idk what was going wrong earlier.

hsemenenko · 2026-09-16T18:22:16Z

-    states_dict: dict[str, SeleneStimState] = _invoke_selene_stim(
-        main, num_selene_qubits
-    )
+    states_dict: dict[str, SeleneStimState] = _invoke_selene_stim(main, num_qubits)


Why would adding expected_qubits be required? Is there a reason to have a helper function to invoke selene rather than just using .emulator() already?

hsemenenko · 2026-09-16T18:29:52Z


    @guppy
    @no_type_check
+    @expected_qubits(7 + 14)


Or add a comment why the 7 and 14 should be separate.

Suggested change

@expected_qubits(7 + 14)

@expected_qubits(21)

hsemenenko · 2026-09-16T18:31:39Z

 from typing import no_type_check

-from guppylang import guppy
+from guppylang.decorator import expected_qubits, guppy


This seems unconventional

Suggested change

from guppylang.decorator import expected_qubits, guppy

from guppylang import guppy

from guppylang.decorator import expected_qubits

hsemenenko · 2026-09-16T18:34:31Z

+def test_zero_ancilla_override() -> None:
+    assert valid_clifford_implementation(
+        steane.specify_h,
+        steane.implement_h_wasted_qubit,
+        code_definition=steane.STEANE_DEF,
+        impl_num_ancillas=0,
+    )


This doesn't seem to test that the number of qubits is actually overridden.

Would you prefer that I removed it? I can Perhaps change it to an example where the hint has enough qubits but the impl_num_ancillas=0 overrides the ancillas leading to a selene panic. I an add a test that this panic happens.

github-actions · 2026-09-17T12:27:57Z

This PR contains breaking changes to the public Python API.

Breaking changes summary

src/guppyft/verify/_verify.py:512: valid_clifford_implementation(impl_num_ancillas):
Parameter default was changed:
Old: 0
New: None

src/guppyft/verify/_verify.py:340: valid_stabilizer_state_preparation(impl_num_ancillas):
Parameter default was changed:
Old: 0
New: None

CalMacCQ · 2026-09-17T13:00:54Z

+
+    impl_num_qubits = num_blocks * code_definition.num_physical_qubits
+
+    if num_hinted_qubits and not impl_num_ancillas:


Same logic in the _compute_clifford_tableaux function attempted to refactor this into a helper but something weird was going on casuing one of the tests to fail.

something like

def _add_impl_qubits( impl_num_qubits: int, num_physical_qubits: int, impl_num_ancillas: int | None, num_hinted_qubits: int | None, ) -> None: if num_hinted_qubits and not impl_num_ancillas: impl_num_qubits += num_hinted_qubits - num_physical_qubits if impl_num_ancillas is not None: impl_num_qubits += impl_num_ancillas

Should work but test_steane_ft_zero_state fails which I'm puzzled by.

cqc-alec · 2026-09-17T13:08:42Z

            parameters, stabilizer generators, and logical operators.
        impl_num_ancillas: The number of ancilla qubits used in the implementation.
-            Defaults to zero.
+            Defaults to None.


Should document what the semantics is when omitting the argument (or passing None): is there a default? Is it zero? ...

From discussion IRL, if the argument is omitted or None, the value is inferred from the @expected_qubits annotation. (Should document this and also add a test.)

I realised that most of the tests I've modified to use @expected_qubits satisfy this. I.e. If we specify @expected_qubits and not impl_num_ancillas then the number specified in @expected_qubits is used. I got confused

See the changes to test_verifier_steane.py

cqc-alec · 2026-09-17T13:11:09Z

             parameters, stabilizer generators and logical operators.
         impl_num_ancillas: The number of ancilla qubits used in the implementation.
-             Defaults to zero.
+            Defaults to None.


CalMacCQ added 4 commits September 7, 2026 22:24

remove impl_num_ancillas arg

2e80272

read hint from metadata

5ef5de2

fixup qubit number

3b1045d

update tests to use expected_qubits hint

72a567e

CalMacCQ requested review from a team and PabloAndresCQ and removed request for a team September 8, 2026 10:04

CalMacCQ marked this pull request as draft September 8, 2026 10:04

CalMacCQ added 3 commits September 8, 2026 11:10

use no_type_check instead of type: ignore

c380236

rename things for clarity

22114cf

num_selene_qubits -> default_num_qubits

7a48b77

CalMacCQ changed the title ~~feat!: remove impl_num_ancillas arg from verifier, use @expected_qubits hint instead.~~ feat!: use @expected_qubits hint in Clifford verifier Sep 8, 2026

PabloAndresCQ reviewed Sep 8, 2026

View reviewed changes

restore ancillas arg

e35e71c

CalMacCQ changed the title ~~feat!: use @expected_qubits hint in Clifford verifier~~ feat: support @expected_qubits hint in Clifford verifier Sep 15, 2026

CalMacCQ and others added 15 commits September 15, 2026 10:51

Merge branch 'main' into cm/expected_qubits_hint

2190aff

update notebook arg

b295822

add override test

3aa169f

match Guppy hint overriding behaviour

74b4942

fix qubits arg

512cb9d

relay on default value for specifying the number of ancillas used in …

d9a7c62

…semantic simulation

default_num_qubits -> num_qubits

824ba92

Merge branch 'main' into cm/expected_qubits_hint

7396271

fix bad merge

050b41b

document ancilla arg

840b0a2

num_qubits -> n_qubits

3cbece5

Revert "num_qubits -> n_qubits"

9716e75

This reverts commit 3cbece5.

comments

e975eda

refactor _get_num_func_qubits

afbee15

comment

1de2d6d

CalMacCQ added 2 commits September 16, 2026 13:13

use _invoke_selene_stim and @expected_qubits consistently

beb349f

remove internal use of @expected_qubits for now

f2cf7a0

CalMacCQ commented Sep 16, 2026

View reviewed changes

use int coercion

97879b7

CalMacCQ marked this pull request as ready for review September 16, 2026 12:47

CalMacCQ requested a review from a team as a code owner September 16, 2026 12:47

CalMacCQ requested review from PabloAndresCQ and hsemenenko and removed request for PabloAndresCQ September 16, 2026 12:47

CalMacCQ commented Sep 16, 2026

View reviewed changes

CalMacCQ added 2 commits September 16, 2026 13:54

minor changes to steane primitive tests

9222aa3

add a zero ancillas override test

7aaa728

hsemenenko reviewed Sep 16, 2026

View reviewed changes

CalMacCQ added 4 commits September 17, 2026 10:59

ancillas comment

b835f0d

extract hint earlier on

1c370a8

more refactoring

31f6660

fix ancilla docstrings

1c010ba

decorator imports

9d54bb2

CalMacCQ changed the title ~~feat: support @expected_qubits hint in Clifford verifier~~ feat!: support @expected_qubits hint in Clifford verifier Sep 17, 2026

CalMacCQ added 2 commits September 17, 2026 13:52

spacing

f1c4612

comment

7afb597

CalMacCQ requested a review from hsemenenko September 17, 2026 12:59

CalMacCQ commented Sep 17, 2026

View reviewed changes

cqc-alec reviewed Sep 17, 2026

View reviewed changes

change number of qubits again

526e45a

CalMacCQ mentioned this pull request Sep 17, 2026

refactor!: make ancillas argument optional, rename to n_impl_ancillas #412

Merged

CalMacCQ marked this pull request as draft September 17, 2026 16:27

	metadata = func.wrapped.metadata._node_metadata # type: ignore[attr-defined]
	assert isinstance(func.wrapped, RawFunctionDef)
	metadata = func.wrapped.metadata["tket.hint.expected_qubits"]

	from guppylang.decorator import expected_qubits, guppy
	from guppylang import guppy
	from guppylang.decorator import expected_qubits


		impl_num_qubits = num_blocks * code_definition.num_physical_qubits

		if num_hinted_qubits and not impl_num_ancillas:

Conversation

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

Uh oh!

Uh oh!

PabloAndresCQ left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CalMacCQ Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CalMacCQ Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CalMacCQ Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hsemenenko left a comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CalMacCQ Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CalMacCQ Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CalMacCQ commented Sep 8, 2026 •

edited

Loading

CalMacCQ Sep 16, 2026 •

edited

Loading

CalMacCQ Sep 16, 2026 •

edited

Loading

CalMacCQ Sep 17, 2026 •

edited

Loading

CalMacCQ Sep 17, 2026 •

edited

Loading

github-actions Bot commented Sep 17, 2026 •

edited

Loading

CalMacCQ Sep 17, 2026 •

edited

Loading