# Copyright 2026 Xanadu Quantum Technologies Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Code for projecting the resources of a circuit onto a target gate set"""
from __future__ import annotations
import re
from collections.abc import Callable, Iterable
from functools import partial
from pennylane import capture
from pennylane.core.transforms import CompilePipeline
from pennylane.transforms import decompose
from pennylane.workflow._levels import (
is_single_level,
level_to_number,
pipeline_at_slice,
validate_level,
)
from pennylane.workflow.get_compile_pipeline import unwrap_qjit_qnode
from ._utils import apply_partial_args, build_circuit_specs, unwrap_partial
from .mlir_specs import resources_from_analysis_pass
from .resource import CircuitSpecs
def _decomps_from_pipeline(pipeline: CompilePipeline) -> dict:
"""Collect the ``fixed_decomps`` and ``exclude_decomps`` of the ``decompose`` transforms in
``pipeline``. If more than one fixes a rule for the same operator, the last one is used."""
fixed_decomps, exclude_decomps = {}, {}
for bound_transform in pipeline:
if bound_transform._transform is decompose: # pylint: disable=protected-access
fixed_decomps |= bound_transform.kwargs.get("fixed_decomps", {})
for op, rules in bound_transform.kwargs.get("exclude_decomps", {}).items():
exclude_decomps.setdefault(op, []).extend(rules)
return {"fixed_decomps": fixed_decomps or None, "exclude_decomps": exclude_decomps or None}
def _estimate_qjit(func, level, target, *args, **kwargs) -> CircuitSpecs:
"""Decompose a qjit'd QNode at ``level`` into the ``target`` gate set and return its specs."""
original_qnode = unwrap_qjit_qnode(func, fn_name="qp.estimate")
from catalyst.utils.exceptions import CompileError # pylint: disable=import-outside-toplevel
compile_pipeline = original_qnode.compile_pipeline
validate_level(level, compile_pipeline)
# The ``isinstance`` check avoids elementwise comparisons
if isinstance(level, str) and level == "device":
raise NotImplementedError("qp.estimate does not support level='device' yet.")
if isinstance(level, slice):
# A slice that selects no transforms is the same as level 0
is_top = not pipeline_at_slice(compile_pipeline, level)
else:
is_top = is_single_level(level) and level_to_number(level, compile_pipeline) == 0
if not is_top:
raise NotImplementedError(
f"qp.estimate only supports level='top' or level=0, instead got: {level!r}."
)
if isinstance(target, str):
raise NotImplementedError(
f"qp.estimate does not support target={target!r} yet. Provide a gate set instead."
)
uses_capture = func.compile_options.capture
if uses_capture == "global":
uses_capture = capture.enabled()
if not uses_capture:
raise ValueError(
"qp.estimate requires program capture. Compile the QNode with qp.qjit(capture=True)."
)
# At level="top", the user transforms are skipped and only the decomposition is applied
bound_t = decompose(gate_set=target, **_decomps_from_pipeline(compile_pipeline))
estimate_kwargs = bound_t.kwargs
estimate_qnode = original_qnode.update_pipelines(
CompilePipeline(),
post_device_pipeline=CompilePipeline(original_qnode.post_device_pipeline),
)
try:
resources = resources_from_analysis_pass(
func,
estimate_qnode,
0,
{},
{},
*args,
analysis_pass_name="resource-estimate",
analysis_pass_kwargs=estimate_kwargs,
**kwargs,
)
except CompileError as exc:
missing_rule = re.search(r"Decomposition rule not found for operator '([^'{]+)", str(exc))
if missing_rule is None:
raise
op = missing_rule.group(1)
raise ValueError(
f"Decomposition rule not found for operator {op}: it cannot be decomposed into the "
f"target gate set. Add {op} to the target, or use a gate set it can be decomposed into."
) from None
return build_circuit_specs(original_qnode, next(iter(resources.values())), "top")
[docs]
def estimate(
qnode,
level: str | int | slice = "top",
*,
target: str | Iterable[type | str] | dict[type | str, float],
) -> Callable[..., CircuitSpecs]:
r"""Provides a resource estimate of a quantum circuit with respect to the provided compilation target,
via rapid analysis of decomposition pathways.
.. note::
Only QNodes which have been decorated with :func:`@qp.qjit(capture=True) <~pennylane.qjit>` are supported.
The ``estimate`` function never executes the circuit. It only provides resource estimates.
Args:
qnode (:class:`~catalyst.jit.QJIT`): the qjit'd QNode for which to estimate resources.
level (str | int | slice): The portion of the
:class:`~.CompilePipeline` to apply before projecting the resources onto the
``target``. See :func:`~.workflow.get_compile_pipeline` for accepted values.
Currently, only ``"top"``, ``0``, or the label of a marker placed before all
transforms are supported. Defaults to ``"top"``.
target (str | Iterable[type | str] | dict[type | str, float]): The gate set to project
the resources onto, in any form accepted by the ``gate_set`` argument of
:func:`~.decompose`.
Returns:
A function that has the same argument signature as ``qnode``. This function returns a
:class:`~.resource.CircuitSpecs` object containing the projected resources, including
gate and measurement data, wire allocations, device information, shots, and more.
.. seealso:: :func:`~.analyze`, :func:`~.track`
**Example**
Consider the following circuit.
.. code-block:: python
dev = qp.device("null.qubit", wires=2)
@qp.qjit(capture=True)
@qp.transforms.cancel_inverses
@qp.qnode(dev)
def circuit(x):
qp.X(0)
qp.X(0)
qp.CZ([0, 1])
qp.RX(x, wires=1)
return qp.probs()
By calling ``estimate`` on this circuit with ``level="top"``, the :func:`~.cancel_inverses`
pass is ignored. Subsequently, the operations in the original circuit will have their
resources projected into the ``target`` gate set by analyzing decomposition pathways.
>>> print(qp.estimate(circuit, target={"PauliX", "Hadamard", "CNOT", "RX"})(1.23))
Device: null.qubit
Device wires: 2
Shots: Shots(total=None)
Level: top
<BLANKLINE>
Quantum operations:
- Total: 6
- CNOT: 1
- Hadamard: 2
- PauliX: 2
- RX: 1
Measurement processes:
- probs(all wires): 1
Total wires: 2
Circuit Depth: Not computed
Since :func:`~.cancel_inverses` is ignored, both ``PauliX`` gates are counted. The ``CZ`` gate
is decomposed into ``Hadamard`` and ``CNOT`` gates.
.. details::
:title: Custom decomposition rules
To reach the ``target`` gate set, ``estimate`` uses the ``fixed_decomps`` and
``exclude_decomps`` of the :func:`~.decompose` transforms in the compile pipeline.
For example, the following circuit fixes a decomposition rule for ``CZ`` that uses
``PauliZ`` and ``RY`` gates instead of ``Hadamard`` gates:
.. code-block:: python
@qp.register_resources({qp.Z: 2, qp.RY: 2, qp.CNOT: 1}, name="cz_with_ry")
def cz_with_ry(wires, **_):
qp.Z(wires[1])
qp.RY(np.pi / 2, wires[1])
qp.CNOT(wires)
qp.Z(wires[1])
qp.RY(np.pi / 2, wires[1])
qp.add_decomps(qp.CZ, cz_with_ry)
@qp.qjit(capture=True)
@qp.decompose(
gate_set={"CNOT", "PauliZ", "RY"}, fixed_decomps={qp.CZ: "cz_with_ry"}
)
@qp.qnode(qp.device("null.qubit", wires=2))
def circuit():
qp.CZ([0, 1])
return qp.probs()
The ``CZ`` gate is decomposed with this rule:
>>> qp.estimate(circuit, target={"CNOT", "PauliZ", "RY"})().resources.quantum_operations
{'CNOT': 1, 'PauliZ': 2, 'RY': 2}
.. details::
:title: Symbolic resource counts
Since the circuit is not executed, the projected resources are subject to the same
compile-time constraints as :func:`~.analyze`. In particular, operations inside a loop
whose number of iterations depends on runtime values are counted symbolically.
For example, the number of ``CZ`` gates in the following circuit, and therefore the number
of gates they decompose into, depends on the value of ``n``:
.. code-block:: python
@qp.qjit(capture=True)
@qp.qnode(qp.device("null.qubit", wires=2))
def circuit(n):
qp.Hadamard(0)
@qp.for_loop(n)
def loop(i):
qp.CZ([0, 1])
loop()
return qp.expval(qp.Z(0))
>>> resources = qp.estimate(circuit, target={"Hadamard", "CNOT"})(5).resources
>>> print(resources)
Symbolic Variables: a
Quantum operations:
- Total: 3*a + 1
- CNOT: a
- Hadamard: 2*a + 1
Measurement processes:
- expval(PauliZ): 1
Total wires: 2
Circuit Depth: Not computed
Concrete values can be estimated by substituting each symbolic variable with an integer,
using the ``.subs`` method:
>>> resources.subs(a=5).quantum_operations
{'CNOT': 5, 'Hadamard': 11}
.. note::
Loops inside the decomposition rules used to reach the ``target`` gate set are counted
symbolically as well, so the result can be symbolic even if the circuit has no dynamic
control flow.
"""
# TODO: [sc-133408] Add a qp.hint example to the docstring once hints survive decomposition
qnode, partial_args, partial_kwargs = unwrap_partial(qnode)
return apply_partial_args(
partial(_estimate_qjit, qnode, level, target), partial_args, partial_kwargs
)