Collections and Structs

Arrays

Fixed-size Guppy arrays are supported, including arrays created in ordinary @guppy functions, passed to other Guppy functions, or created from Python lists.

H-Series requires the qubit used by each quantum operation to be known during compilation. hugr-qir tries to make array indexing static by expanding loops and simplifying indices. Compilation fails if it cannot determine the qubit used by an operation.

An index does not have to be written as a literal. Some runtime choices can be expanded into a small number of branches with a known qubit in each branch. See Arrays for supported and unsupported examples.

Using @guppy.comptime is a useful alternative when array indices and loops can be decided while the program is compiled.

Array-backed collections

Stack and Queue from guppylang.std.collections can be used when their operations can be completely simplified during compilation. Fixed sequences of pushes and pops are a typical supported case.

Collection state that depends on runtime values is not generally supported. It can leave internal storage, loops, or dynamic qubit addressing in the program, which H-Series QIR cannot represent. Compilation fails when that state cannot be removed. Calling discard_empty() is still required for ownership checking, but does not by itself make a collection suitable for QIR.

PriorityQueue is currently unsupported, including for simple fixed sequences. Use a direct fixed-size array, tuple, struct, or individual variables when a collection cannot be simplified.

Tuples

Fixed-shape tuple operations are supported. Starred unpacking creates an array for the starred portion, which follows the usual array rules.

Structs

Structs are supported when their field types are supported. Array fields follow the usual array rules.

Where to look next