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— Bothfor_loop()andwhile_loop()support"num-iters"to indicate a heuristic number of loop iterations for the purposes of resource estimation withspecs(). See Usage Details for more information."branch-prob"— The branches tocond()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 ofhintin 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.Usage Details
“num-iters” with for and while loops
By hinting control flow like
for_loop()andwhile_loop(), profiling withanalyze()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
10corresponds to the hinted loop, contrasting the symbolicafrom 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 withanalyze()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 everycond()branch. The difference in behaviour with and withouthintis 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 inloop_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
20as 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))