qp.hint

hint(f_or_hints, hints=None)[source]

Attaches a compiler hint to applicable functionality.

Can be used as a decorator or applied directly:

  • @qp.hint({"num-iters": 10}) / qp.hint({"num-iters": 10})(f)

  • qp.hint(f, {"num-iters": 10})

Parameters:
  • f_or_hints – either a dictionary of hints (decorator form), or the object to annotate (direct form)

  • hints (dict[str, Any]) – dictionary of hints; required for the direct form

Returns:

A decorator when only a hint dictionary is passed, otherwise the hinted object.

Available Hints:

  • "num-iters": val — Both for_loop() and while_loop() support "num-iters" to indicate a heuristic number of loop iterations for the purposes of resource estimation with specs(). See Usage Details for more information.

  • "branch-prob" — The branches to cond() support "branch-prob" to indicate the probability that a branch will be selected.

Warning

By definition, the qjit() compiler may decide to completely ignore any instances of hint in a program; a compiler hint is something that does not affect program correctness, meaning that the compiler can safely ignore them and still provide correct results.

While close misspellings may be accepted (e.g., "num-iter"), spellings sufficiently far away from the target will be ignored.

“num-iters” with for and while loops

By hinting control flow like for_loop() and while_loop(), profiling with analyze() can heuristically specify the number of iterations, leading to concrete resource counts (no symbolic expressions).

@qp.qjit(capture=True)
@qp.qnode(qp.device('lightning.qubit', wires=10))
def c(n):

    @qp.hint({"num-iters": 10})
    @qp.for_loop(n)
    def hinted_loop(i):
        qp.X(i)

    hinted_loop()

    @qp.for_loop(n)
    def unhinted_loop(i):
        qp.Y(i)

    unhinted_loop()

    return qp.expval(qp.Z(0))
>>> print(qp.analyze(c)(5).resources)
Symbolic Variables: a
Quantum operations:
- Total: a + 10
  - PauliX: 10
  - PauliY: a
Measurement processes:
- expval(PauliZ): 1
Total wires: 10
Circuit Depth: Not computed

The concrete 10 corresponds to the hinted loop, contrasting the symbolic a from the unhinted loop.

The same annotation can be applied directly instead of as a decorator:

@qp.for_loop(n)
def hinted_loop(i):
    qp.X(i)

hinted_loop = qp.hint(hinted_loop, {"num-iters": 10})

“branch-prob” with cond

By hinting cond() branches with "branch-prob", profiling with analyze() can heuristically specify the probabilities for each branch being selected, leading to a weighted average of resources from each branch.

By default (with no hints), analyze() takes the maximum union of all gate types in every cond() branch. The difference in behaviour with and without hint is evident in the example below.

import pennylane as qp

@qp.qjit(capture=True)
@qp.qnode(qp.device("lightning.qubit", wires=2))
def circuit():
    qp.H(0)
    qp.H(1)

    @qp.for_loop(0, 10)
    def loop_hinted(_):
        m = qp.measure(0)

        @qp.hint({"branch-prob": 0.8})
        def true_fn():
            qp.CNOT((0, 1))

        @qp.hint({"branch-prob": 0.2})
        def false_fn():
            qp.CZ((1, 0))

        qp.cond(m, true_fn=true_fn, false_fn=false_fn)()

    @qp.for_loop(0, 10)
    def loop_unhinted(_):
        m = qp.measure(0)

        def true_fn():
            qp.CRZ(0.1, (0, 1))

        def false_fn():
            qp.CRY(0.1, (1, 0))

        qp.cond(m, true_fn=true_fn, false_fn=false_fn)()

    loop_hinted()
    loop_unhinted()

    return qp.expval(qp.X(0))
>>> print(qp.analyze(circuit)().resources.quantum_operations)
{'CNOT': 8, 'CRY': 10, 'CRZ': 10, 'CZ': 2, 'Hadamard': 2, 'MidCircuitMeasure': 20}

With the hinted conditional branches in loop_hinted, analyze() takes the weighted sum of each branch’s resources (\(10\ \text{iterations} \times (0.8 \times \text{CNOT} + 0.2 \times \text{CZ}) = 8 \times \text{CNOT} + 2 \times \text{CZ}\)). In contrast, with the unhinted conditional branches in loop_unhinted, analyze() takes the max union of all gate types across every branch, which accumulates to \(10 \times \text{CRZ} + 10 \times \text{CRY}\).

General notes on using hint

Note that hints can be overwritten. The following will use 20 as the number of iterations:

@qp.qjit(capture=True)
@qp.qnode(qp.device('lightning.qubit', wires=10))
def c(n):

    @qp.hint({"num-iters": 20})
    @qp.hint({"num-iters": 10})
    @qp.while_loop(lambda i: i < 10)
    def loop(i):
        qp.X(i)
        return i + 1

    loop(0)
    return qp.expval(qp.Z(0))

Compiler hints will also be discarded without warning if they do not match the expected type of hint. The next example would run without warning:

@qp.qjit(capture=True)
@qp.qnode(qp.device('null.qubit', wires=10))
def c(n):

    @qp.hint({"unknown_hint": "a"})
    @qp.for_loop(3)
    def loop(i):
        qp.X(i)

    loop()

    return qp.expval(qp.Z(0))

Contents

Using PennyLane

Release news

Development

API

Internals