Source code for pennylane.resource.analyze

# 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 analyzing the resources of a compiled circuit"""

from __future__ import annotations

from collections import defaultdict
from collections.abc import Callable, Iterable
from functools import partial

from pennylane import capture

from ._utils import (
    apply_partial_args,
    build_circuit_specs,
    get_marker_level_map,
    preprocess_level_input,
    unwrap_partial,
    unwrap_qjit_qnode,
)
from .mlir_specs import resources_from_analysis_pass
from .resource import CircuitSpecs, SpecsResources


def _run_resource_analysis(func, original_qnode, level, *args, **kwargs) -> tuple[
    SpecsResources | list[SpecsResources] | dict[str, SpecsResources | list[SpecsResources]],
    str | dict[int, str],
]:
    """Compile a qjit'd QNode with the ``resource-analysis`` pass inserted at the given levels.

    Returns the resources found at each level along with the name of each level.
    """
    # Note that this only gets transforms manually applied by the user
    compile_pipeline = original_qnode.compile_pipeline

    return_single_level: bool = isinstance(level, (int, str)) and level not in ("all", "all-user")

    has_device_level: bool = level in ("device", "all")
    if has_device_level:
        if not func.compile_options.capture or (
            func.compile_options.capture == "global" and not capture.enabled()
        ):
            raise ValueError("Device level is only supported when capture is enabled.")

    # Easier to assume level is always a sorted list of int levels
    level = preprocess_level_input(level, compile_pipeline)

    # Map to convert back and forth between marker name and int level
    marker_to_level = get_marker_level_map(compile_pipeline)
    level_to_markers = defaultdict(list)  # Multiple markers can correspond to the same level
    for marker, lvl in marker_to_level.items():
        level_to_markers[lvl].append(marker)

    level_to_name: dict[int, str] = {}

    # Handle MLIR passes
    resources = resources_from_analysis_pass(
        func,
        original_qnode,
        level,
        level_to_markers,
        level_to_name,
        *args,
        **kwargs,
    )

    # Unpack dictionary to single item if only 1 level was given as input
    if return_single_level:
        resources = next(iter(resources.values()))
        level_to_name = next(iter(level_to_name.values()))

    return resources, level_to_name


def _analyze_qjit(func, level, *args, **kwargs) -> CircuitSpecs:
    """Compile a qjit'd QNode up to the given level and return the specs found by analyzing it."""
    original_qnode = unwrap_qjit_qnode(func, fn_name="qp.analyze")

    resources, level = _run_resource_analysis(func, original_qnode, level, *args, **kwargs)

    return build_circuit_specs(original_qnode, resources, level)


[docs] def analyze( qnode, level: str | int | Iterable[int | str] = "user", ) -> Callable[..., CircuitSpecs]: r"""Provides a compile-time resource estimate of a quantum circuit, obtained by analyzing its intermediate representation at the specified compilation level. This transform converts a QNode into a callable that compiles the circuit up to ``level`` and inspects the resulting representation, without executing the circuit or unrolling its control flow. The resource information is therefore subject to compile-time constraints. Args: qnode (:class:`~catalyst.jit.QJIT`): the (qjit'd) QNode for which to estimate resources. ``functools.partial`` wrappers around supported callables are also accepted. level (str | int | Iterable[int | str]): The level of compilation at which to estimate resources. Defaults to ``"user"``. ``level`` accepts the following types: * ``int``: The number of transforms to apply before analyzing resources. * ``str``: One of the presets listed below, or the ``label`` of a :func:`~.marker`. * ``iterable``: A ``list``, ``tuple``, or similar containing ``int`` or ``str`` values. These should be sorted in ascending transform order with no duplicates. Resources will be analyzed for each provided level in the ``iterable``. The following ``str`` presets are provided for ease of use: * ``"top"``: Equivalent to ``0``; to analyze resources before any transforms have been applied. * ``"user"``: To analyze resources after the user-specified transforms have been applied. * ``"device"``: To analyze resources after the user-specified transforms and device preprocessing transforms have been applied. * ``"all-user"``: To analyze resources at each stage of compilation with respect to user-specified transforms. * ``"all"``: To analyze resources at each stage of compilation with respect to user-specified and device preprocessing transforms. Returns: A function that has the same argument signature as ``qnode``. This function returns a :class:`~.resource.CircuitSpecs` object containing the ``qnode`` specifications, including gate and measurement data, wire allocations, device information, shots, and more. .. seealso:: :func:`~.estimate`, :func:`~.track` **Example** .. code-block:: python dev = qp.device("null.qubit", wires=2) @qp.qjit(capture=True) @qp.transforms.merge_rotations @qp.transforms.cancel_inverses @qp.qnode(dev) def circuit(x): qp.RX(x, wires=0) qp.RX(x, wires=0) qp.X(0) qp.X(0) qp.CNOT([0, 1]) return qp.probs() >>> print(qp.analyze(circuit, level="user")(1.23)) Device: null.qubit Device wires: 2 Shots: Shots(total=None) Level: merge-rotations <BLANKLINE> Quantum operations: - Total: 2 - CNOT: 1 - RX: 1 Measurement processes: - probs(all wires): 1 Total wires: 2 Circuit Depth: Not computed Using ``level="all"`` shows how the resources change after each transform: >>> all_specs = qp.analyze(circuit, level="all")(1.23) >>> print(all_specs) Device: null.qubit Device wires: 2 Shots: Shots(total=None) Levels: - 0: Before MLIR Passes - 1: cancel-inverses - 2: merge-rotations - 3: Device Preprocessing <BLANKLINE> ↓Metric Level→ | 0 | 1 | 2 | 3 ------------------------------------------ Quantum operations: | - Total | 5 | 3 | 2 | 2 - CNOT | 1 | 1 | 1 | 1 - PauliX | 2 | 0 | 0 | 0 - RX | 2 | 2 | 1 | 1 Measurement processes: | - probs(all wires) | 1 | 1 | 1 | 1 Total wires | 2 | 2 | 2 | 2 The resources at a given level can be accessed with the name of the corresponding transform or marker: >>> all_specs.resources["cancel-inverses"].quantum_operations {'CNOT': 1, 'RX': 2} .. details:: :title: Compile-time constraints of resource analysis Since the circuit is not executed, some resources cannot be counted exactly: * Resources inside a ``for`` loop whose number of iterations depends on runtime values are counted symbolically, using :class:`~.resource.Expression` instances instead of integers. * Resources inside a ``while`` loop are counted as if only one iteration occurred. * For conditional branches from ``if`` or ``switch`` statements, each gate is counted with its maximum count across all branches, providing an upper bound. For example, the number of ``PauliX`` gates in the following circuit depends on the value of ``n``: .. code-block:: python @qp.qjit(autograph=True) @qp.qnode(qp.device("null.qubit", wires=1)) def circuit(n): qp.Hadamard(0) for _ in range(n): qp.PauliX(0) return qp.expval(qp.Z(0)) >>> resources = qp.analyze(circuit, level=0)(5).resources >>> print(resources) Symbolic Variables: a Quantum operations: - Total: a + 1 - Hadamard: 1 - PauliX: a Measurement processes: - expval(PauliZ): 1 Total wires: 1 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 {'Hadamard': 1, 'PauliX': 5} To get concrete counts for given arguments instead, use :func:`~.track`, which executes the circuit and therefore unrolls its control flow. """ qnode, partial_args, partial_kwargs = unwrap_partial(qnode) return apply_partial_args(partial(_analyze_qjit, qnode, level), partial_args, partial_kwargs)