From 4be3371b350ea775d0dc2f39bf57a9765ac464a7 Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Mon, 22 Sep 2025 12:42:31 +0100 Subject: [PATCH 1/2] fix: improve misleading example in migration guide --- sphinx/migration_guide.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/sphinx/migration_guide.md b/sphinx/migration_guide.md index 5f508d6..955b84a 100644 --- a/sphinx/migration_guide.md +++ b/sphinx/migration_guide.md @@ -91,10 +91,23 @@ pytket_circ.add_gate(G_box, [0, 1]) pytket_circ.CCX(0, 1, 2) pytket_circ.add_gate(OpType.CnY, [0, 1, 2]) -guppy_func = guppy.load_pytket("circuit_func", pytket_circ) +# Load pytket circuit as a Guppy function. +circuit_func = guppy.load_pytket("circuit_func", pytket_circ) ``` -We will get an error if we try to invoke the Selene emulator as it cannot execute the opaque op. +We now have a Guppy function that takes three qubits as input. As this function has inputs, it cannot be an entrypoint to an executable program. We therefore have to call `circuit_func` inside a Guppy function which takes no arguments and allocates some qubits for it to use. + +```{code-cell} ipython3 +from guppylang.std.quantum import discard_array + +@guppy +def guppy_func() -> None: + qs = array(qubit() for _ in range(3)) + circuit_func(qs) + discard_array(qs) +``` + +We will get an error if we try to invoke the Selene emulator as it cannot execute the opaque op defining the `Unitary2qBox` in the call to `circuit_func`. ```{code-cell} ipython3 --- @@ -118,10 +131,10 @@ DecomposeBoxes().apply(pytket_circ) # Decompose the Unitary2qBox to primitive ga rebase_pass.apply(pytket_circ) # Convert all gates in pytket_circ to {H, Rz, CX} # Load rebased circuit as a Guppy function -guppy_func = guppy.load_pytket("guppy_func", pytket_circ) +new_circuit_func = guppy.load_pytket("guppy_func", pytket_circ) ``` -Now our compiled Guppy program should contain no opaque operations and is executable on the emulator. +Now our compiled Guppy program should contain no opaque operations and is executable on the emulator when called inside `guppy_func`. ## Compilation and optimization of quantum programs From 4cedeb4d1d89bd31cb447f13324f780086e99e53 Mon Sep 17 00:00:00 2001 From: CalMacCQ <93673602+CalMacCQ@users.noreply.github.com> Date: Mon, 22 Sep 2025 13:30:37 +0100 Subject: [PATCH 2/2] better crossreferncing --- sphinx/migration_guide.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/sphinx/migration_guide.md b/sphinx/migration_guide.md index 955b84a..d992923 100644 --- a/sphinx/migration_guide.md +++ b/sphinx/migration_guide.md @@ -17,7 +17,10 @@ Guppy is a compiled language which distinguishes it from Python. The user writes ## Loading pytket circuit as Guppy functions -A pytket [Circuit](inv:pytket#circuit_class) instance can be invoked as a Guppy function using the `guppy.load_pytket` method. This feature can be useful for making use of existing pytket circuits directly in Guppy without having to rewrite code from scratch. In the near term, it is also useful to synthesize circuits (e.g. state preparation, permutations) using pytket's higher level "box" constructs. These synthesized circuits can the be invoked as Guppy functions. + +[load_pytket_docs]: https://docs.quantinuum.com/guppy/api/decorator.html#guppylang.decorator.guppy.load_pytket + +A pytket [Circuit](inv:pytket#circuit_class) instance can be invoked as a Guppy function using the [guppy.load_pytket][load_pytket_docs] method. This feature can be useful for making use of existing pytket circuits directly in Guppy without having to rewrite code from scratch. In the near term, it is also useful to synthesize circuits (e.g. state preparation, permutations) using pytket's higher level "box" constructs. These synthesized circuits can the be invoked as Guppy functions. ### Basic Example @@ -43,8 +46,8 @@ qft_func = guppy.load_pytket("qft_func", qft2_circ) We now have a Guppy function called `qft_func` which we can compile or use as a subroutine in other functions. -Note that by default `guppy.load_pytket` will create Guppy functions which use arrays of qubits as inputs. This means that our `qft_func` above will have take an array of two qubits as input. -If we want the function to take two separate qubit arguments, we can specify `use_arrays=False` in `guppy.load_pytket`. Also note that by default, circuits with separate quantum registers become Guppy functions that take multiple arrays of qubits as input. +Note that by default [guppy.load_pytket][load_pytket_docs] will create Guppy functions which use arrays of qubits as inputs. This means that our `qft_func` above will have take an array of two qubits as input. +If we want the function to take two separate qubit arguments, we can specify `use_arrays=False` in [guppy.load_pytket][load_pytket_docs]. Also note that by default, circuits with separate quantum registers become Guppy functions that take multiple arrays of qubits as input. ### How to deal with operations unsupported by Guppy @@ -107,7 +110,7 @@ def guppy_func() -> None: discard_array(qs) ``` -We will get an error if we try to invoke the Selene emulator as it cannot execute the opaque op defining the `Unitary2qBox` in the call to `circuit_func`. +We will get an error if we try to invoke the Selene emulator as it cannot execute the opaque op defining the {py:class}`~pytket.circuit.Unitary2qBox` in the call to `circuit_func`. ```{code-cell} ipython3 --- @@ -119,7 +122,7 @@ sim_result = guppy_func.emulator(n_qubits=3).with_seed(2).run() The solution to handling operations which are not directly supported is to decompose these unsupported operations into gates from the supported extensions before loading the circuit. This can -be readily done with the `AutoRebase` pass from pytket. +be readily done with the {py:class}`~pytket.passes.AutoRebase` pass from pytket. ```{code-cell} ipython3 from pytket.passes import AutoRebase, DecomposeBoxes @@ -142,7 +145,7 @@ The pytket library contains many [compilation passes](https://docs.quantinuum.co As of August 2025, optimization of compiled Guppy programs is still at an early stage. When using `guppy.emulator()` the quantum program is converted to the [qsystem native instructions](api/generated/guppylang.std.qsystem.rst) with no further optimization. In the near term, it is planned to optimize regions of these programs with the kind of compiler passes that are already available in pytket using an updated version of the TKET compiler. -If you want to optimize your quantum program using pytket, you can create a pytket circuit and optimize it. This optimized program can then be loaded as a Guppy function by using `guppy.load_pytket`. +If you want to optimize your quantum program using pytket, you can create a pytket circuit and optimize it. This optimized program can then be loaded as a Guppy function by using [guppy.load_pytket][load_pytket_docs]. ## Execution of quantum programs