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.abc import Callable, Sequence
from functools import partial
from typing import TYPE_CHECKING

from pennylane import capture
from pennylane.core.transforms import CompilePipeline
from pennylane.workflow._levels import (
    device_level,
    is_single_level,
    levels_to_numbers,
    pipeline_at_slice,
    split_device_preprocessing,
)
from pennylane.workflow.get_compile_pipeline import unwrap_qjit_qnode

from ._utils import (
    apply_partial_args,
    build_circuit_specs,
    check_no_tape_transforms,
    unwrap_partial,
)
from .mlir_specs import resources_from_analysis_pass
from .resource import CircuitSpecs, SpecsResources

if TYPE_CHECKING:
    from pennylane.workflow import QNode


def _qnode_at_slice(qnode: QNode, level: slice) -> tuple[QNode, int]:
    """Return a copy of ``qnode`` that only applies the compile pipeline selected by ``level``,
    as given by :func:`~.workflow.get_compile_pipeline`, along with the level at which to analyze
    the resources of the copy."""
    # The device applies its preprocessing itself, after the other transforms
    pipeline, has_device_preprocessing = split_device_preprocessing(
        pipeline_at_slice(qnode.compile_pipeline, level)
    )
    if level.indices(device_level(qnode.compile_pipeline))[0] > 0:
        # The markers describe the circuit after all the transforms before them, so they do not
        # apply to a circuit where the transforms before the slice are skipped
        pipeline = CompilePipeline(list(pipeline))
    sliced_qnode = qnode.update_pipelines(
        pipeline, post_device_pipeline=CompilePipeline(qnode.post_device_pipeline)
    )
    return sliced_qnode, device_level(pipeline) if has_device_preprocessing else len(pipeline)


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.
    """
    if isinstance(level, slice):
        # Only apply the portion of the compile pipeline selected by the slice
        original_qnode, level = _qnode_at_slice(original_qnode, level)

    # Note that this only gets transforms manually applied by the user
    compile_pipeline = original_qnode.compile_pipeline
    level_numbers = levels_to_numbers(level, compile_pipeline)
    # Only the transforms up to the highest level are applied
    check_no_tape_transforms(compile_pipeline[: max(level_numbers)])

    has_device_level: bool = device_level(compile_pipeline) in level_numbers
    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.")

    # Levels with markers are named after them
    markers_by_level = compile_pipeline._level_to_markers()  # pylint: disable=protected-access

    level_to_name: dict[int, str] = {}

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

    # The displayed level describes the circuit after the associated transform has been applied
    level_to_name = {
        lvl: name if lvl == 0 or lvl in markers_by_level else f"After {name}"
        for lvl, name in level_to_name.items()
    }

    # Unpack dictionary to single item if only 1 level was given as input
    if is_single_level(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 | slice | Sequence[str | int] = "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 with the portion(s) of its :class:`~.CompilePipeline` selected by ``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 | slice | Sequence[str | int]): The portion of the :class:`~.CompilePipeline` to apply before analyzing resources. See :func:`~.workflow.get_compile_pipeline` for accepted values. If ``level`` is a ``Sequence``, ``"all-user"``, or ``"all"``, resources are analyzed independently for each provided case. Defaults to ``"user"``. 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:`~pennylane.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: After 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: After cancel-inverses - 2: After merge-rotations - 3: After 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} A ``slice`` only applies that portion of the compile pipeline. For example, the resources after applying ``merge_rotations``, but not ``cancel_inverses``, are given by: >>> qp.analyze(circuit, level=slice(1, 2))(1.23).resources.quantum_operations {'CNOT': 1, 'PauliX': 2, 'RX': 1} .. 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)