Optimizer

Optimization configuration for Guppy compilation.

Guppy applies a predefined set of optimization passes when compiling a program using the TKET compiler.

These passes clean up artifacts introduced by the compiler and may simplify both classical and quantum operations when calling compile(), compile_function(), or emulator().

Use with_opt_level() before compiling or creating an emulator to select a different OptimizationLevel. The method can be chained before compiling or creating an emulator.

Choosing an optimization level

Pass a member of OptimizationLevel to with_opt_level():

from guppylang import OptimizationLevel, guppy
from guppylang.std.builtins import output
from guppylang.std.quantum import h, measure, qubit

@guppy
def main() -> None:
    q = qubit()
    h(q)
    h(q)
    if measure(q):
        output("result", 2 + 2)
    else:
        output("result", 3 + 3)

# Classical optimization will keep the self-inverse Hadamard gates.
package = main.with_opt_level(OptimizationLevel.Classical).compile()

The available levels are:

• OptimizationLevel.Default applies Guppy’s standard optimization level. This may include both classical and quantum optimizations that do not alter the program’s gateset. Calling main.compile() or main.emulator(...) directly uses this level.

• OptimizationLevel.Classical restricts optimization to classical operations. The program will execute the same quantum operations as the original source, but may have a simplified control flow structure.

• OptimizationLevel.Minimal applies only structural rewrites needed to produce executable output. This is useful for low-level program analysis or when more control over the optimization passes is desired.

See OptimizationLevel for more details.

Note that gate rebasing or other program transformations may still be performed further down the compilation pipeline where required. For example, emulators may require a specific gateset when targeting a particular architecture.

with_minimal_opt() is shorthand for selecting OptimizationLevel.Minimal. It disables optional optimizations on the program.

emulator = main.with_minimal_opt().emulator(n_qubits=1)

Running custom passes

Use OptimizerInstance.with_optimization() to append any HUGR ComposablePass to an optimization pipeline. For example, the following starts with minimal optimization and then runs tket’s function-inlining pass:

from tket.passes import InlineFunctions

# Apply a tket pass to inline Guppy functions
package = main.with_minimal_opt().with_optimization(InlineFunctions()).compile()

package = (
    main.with_minimal_opt().with_optimization(passes.InlineFunctions())
    .compile()
)

Multiple custom passes can be added by chaining with_optimization() calls. They run in the order they are added, after the passes supplied by the selected optimization level:

package = (
    main.with_opt_level(OptimizationLevel.Classical)
    .with_optimization(first_pass)
    .with_optimization(second_pass)
    .compile()
)

OptimizerInstance	Builder used to configure optimizations for compiling a Guppy program.
OptimizationLevel	Optimization level used when compiling a Guppy program.