Source code for pennylane.resource.specs

# Copyright 2018-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 resource estimation"""

from __future__ import annotations

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

from pennylane.workflow import QNode
from pennylane.workflow.get_compile_pipeline import unwrap_qjit_qnode

from ._utils import apply_partial_args, build_circuit_specs, unwrap_partial
from .analyze import _run_resource_analysis
from .resource import CircuitSpecs
from .track import _run_with_resource_tracking


def _specs_qjit(qjit, level, compute_depth, *args, **kwargs) -> CircuitSpecs:
    original_qnode = unwrap_qjit_qnode(qjit, fn_name="qp.specs")

    if level is None:
        level = "device"

    if level == "device":
        # Tracking executes the circuit, but specs only reports the resources.
        if compute_depth is None:
            compute_depth = True
        _, resources = _run_with_resource_tracking(
            qjit, original_qnode, *args, compute_depth=compute_depth, **kwargs
        )

    elif isinstance(level, (int, tuple, list, range, str)):
        if compute_depth:
            warnings.warn(
                "Cannot calculate circuit depth before applying all transforms."
                " To compute the depth, please use level='device'.",
                UserWarning,
            )
        resources, level = _run_resource_analysis(qjit, original_qnode, level, *args, **kwargs)

    else:
        raise NotImplementedError(f"Unsupported level argument '{level}'.")

    return build_circuit_specs(original_qnode, resources, level)


[docs] def specs( qnode, level: str | int | Iterable[int | str] | None = None, compute_depth: bool | None = None, ) -> Callable[..., CircuitSpecs]: r"""Provides the specifications of a quantum circuit. This transform converts a QNode into a callable that provides resource information about the circuit after applying the specified transforms. Args: qnode (:class:`~catalyst.jit.QJIT`): the (qjit'd) QNode to calculate the specifications for. ``functools.partial`` wrappers around supported callables are also accepted. Keyword Args: level (str | int | iter[int | str] | None): An indication of which transforms to apply before computing the resource information. See the sections below for more information about acceptable values. compute_depth (bool): Whether to compute the depth of the circuit. If ``False``, circuit depth will not be included in the output. By default, ``specs`` will always attempt to calculate circuit depth (behaves as ``True``), except where not available, such as in pass-by-pass analysis for ``qjit``-compiled workflows. 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, total wires, device information, shots, and more. .. seealso:: :func:`~.analyze`, which provides the same pass-by-pass analysis, and :func:`~.track`, which returns the same device-level information along with the result of executing the circuit. .. warning:: Computing circuit depth is computationally expensive and can lead to slower ``specs`` calculations. If circuit depth is not needed, set ``compute_depth=False``. .. note:: The available options for ``levels`` are: * ``"top"`` or ``0``: The original circuit before any transforms have been applied. * ``"user"``: The circuit after all user-specified transforms have been applied. * ``"device"``: The circuit after all user-specified transforms and device preprocessing transforms have been applied. * An ``int``: The circuit after the specified number of user-specified transforms have been applied. * A marker name (str): The circuit after the specified user-specified transform (and all before it) has been applied. * An iterable: A ``list``, ``tuple``, or similar containing ints and/or marker names. Should be sorted in ascending transform order with no duplicates. The output will provide resource information for each level. * The string ``"all"``: To provide information at each stage of compilation with respect to user-specified transforms. **Example** .. code-block:: python dev = qp.device("null.qubit", wires=2) @qp.qjit @qp.qnode(dev) def circuit(theta): qp.RX(theta, wires=0) qp.CNOT(wires=(0,1)) return qp.probs(wires=(0,1)) >>> print(qp.specs(circuit, level="top")(1.23)) Device: null.qubit Device wires: 2 Shots: Shots(total=None) Level: Before MLIR Passes <BLANKLINE> Quantum operations: - Total: 2 - CNOT: 1 - RX: 1 Measurement processes: - probs(2 wires): 1 Total wires: 2 Circuit Depth: Not computed The :class:`~.resource.SpecsResources` can be accessed using the ``.resources`` attribute, which provides more direct access to the data fields. For example: >>> qp.specs(circuit)(1.23).resources.quantum_operations {'CNOT': 1, 'RX': 1} .. details:: :title: Runtime Specs with Catalyst **Runtime resource tracking** (specified by ``level="device"``) works by mock-executing the desired workflow and tracking the number of times a given gate has been applied. This mock-execution happens after all compilation steps, and should be highly accurate to the final gate counts of running on a real device. .. code-block:: python dev = qp.device("lightning.qubit", wires=3) @qp.qjit @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.specs(circuit, level="device")(1.23)) Device: lightning.qubit Device wires: 3 Shots: Shots(total=None) Level: device <BLANKLINE> Quantum operations: - Total: 2 - CNOT: 1 - RX: 1 Measurement processes: - probs(all wires): 1 Total wires: 3 Circuit Depth: 2 .. note:: The resources shown when using ``level="device"`` may reflect changes to the circuit beyond the transforms manually applied to the QNode. Theses changes are a result of additional "device preprocessing" transforms applied to ensure compatibility with lowering to MLIR and/or execution on the chosen device. .. details:: :title: Pass-by-pass Specs with Catalyst **Pass-by-pass specs** analyze the intermediate representations of compiled circuits. This can be helpful for determining how circuit resources change after a given transform. .. warning:: Some resource information from pass-by-pass specs may be estimated, since it is not always possible to determine exact resource usage from intermediate representations. For example, resources contained in a ``for`` loop with a non-static range or a ``while`` loop will be counted as if only one iteration occurred. Additionally, resources contained in conditional branches from ``if`` or ``switch`` statements will take a union of resources over all branches, providing a tight upper-bound. Due to similar technical limitations, depth computation is not available for pass-by-pass specs. Pass-by-pass specs can be obtained by providing one of the following values for the ``level`` argument: * An ``int``: the desired transform level of a user-applied transform, see the note below * A marker name (str): The name of an applied :func:`qp.marker <pennylane.marker>` transform * An iterable: A ``list``, ``tuple``, or similar containing ints and/or marker names. Should be sorted in ascending transform order with no duplicates * The string ``"all"``: To provide information at each stage of compilation with respect to user-specified transforms * The string ``"user"``: To provide information after all user-specified transforms have been applied .. note:: The ``level`` argument is based on user-applied transforms. Level ``0`` always corresponds to the original circuit before any user-specified transforms have been applied, and incremental levels correspond to the aggregate of user-specified transforms in the order in which they are applied. Consider the following circuit: .. code-block:: python dev = qp.device("lightning.qubit", wires=3) @qp.qjit @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() We can get a pass-by-pass overview of the resources using ``level="all"``: >>> all_specs = qp.specs(circuit, level="all")(1.23) # doctest: +SKIP >>> print(all_specs) # doctest: +SKIP Device: lightning.qubit Device wires: 3 Shots: Shots(total=None) Levels: - 0: Before MLIR Passes - 1: After cancel-inverses - 2: After merge-rotations <BLANKLINE> ↓Metric Level→ | 0 | 1 | 2 ------------------------------------- Quantum operations: | - Total | 5 | 3 | 2 - CNOT | 1 | 1 | 1 - PauliX | 2 | 0 | 0 - RX | 2 | 2 | 1 Measurement processes: | - probs(all wires) | 1 | 1 | 1 Total wires | 3 | 3 | 3 When invoked with an iterable of levels, or ``"all"`` as above, the resources at different levels can be accessed from the the returned :class:`~.resource.CircuitSpecs` object's ``.resources`` attribute, using the name of a transform or marker. For example: >>> print(all_specs.resources['merge-rotations']) # doctest: +SKIP Quantum operations: - Total: 2 - CNOT: 1 - RX: 1 Measurement processes: - probs(all wires): 1 Total wires: 3 Circuit Depth: Not computed A shortcut to access the resources after all user-specified transforms have been applied is to use the ``"user"`` level. For example, the following will also return the resources after the ``merge-rotations`` transform: >>> print(qp.specs(circuit, level="user")(1.23).resources)# doctest: +SKIP Quantum operations: - Total: 2 - CNOT: 1 - RX: 1 Measurement processes: - probs(all wires): 1 Total wires: 3 Circuit Depth: Not computed .. warning:: Certain transforms, like the ``split-non-commuting`` transform, can result in splitting a single execution into multiple executions. In this case, the resources for that level will be returned as a list of :class:`~.resource.SpecsResources` objects. When printed, these split executions will be shown as individual columns. .. code-block:: python dev = qp.device("lightning.qubit", wires=3) @qp.qjit @qp.transforms.cancel_inverses @qp.transform(pass_name="split-non-commuting") @qp.qnode(dev) def circuit(): qp.X(0) qp.X(0) return qp.expval(qp.PauliZ(0)), qp.expval(qp.PauliX(0)) >>> print(qp.specs(circuit, level="all")()) # doctest: +SKIP Device: lightning.qubit Device wires: 3 Shots: Shots(total=None) Levels: - 0: Before MLIR Passes - 1: After split-non-commuting - 2: After cancel-inverses <BLANKLINE> ↓Metric Level→ | 0 | 1-a | 1-b | 2-a | 2-b --------------------------------------------------------- Quantum operations: | - Total | 2 | 2 | 2 | 0 | 0 - PauliX | 2 | 2 | 2 | 0 | 0 Measurement processes: | - expval(PauliX) | 1 | 0 | 1 | 0 | 1 - expval(PauliZ) | 1 | 1 | 0 | 1 | 0 Total wires | 3 | 3 | 3 | 3 | 3 Note that in the above example, the ``split-non-commuting`` transform results in two separate executions, which are labeled with the suffixes ``-a`` and ``-b`` in the output. The resources for these executions are returned and displayed separately, though the level name for both is the same, since they come from the same transform. .. details:: :title: Symbolic Results for Pass-by-pass Specs with Catalyst In cases where the exact resources of a circuit are not easily obtained at compile time, ``specs`` may return resources which include expressions rather than exact values. This can occur when the resources depend on values that are not known at compile time, such as the number of iterations in a loop. In these cases, the resource information will be returned as a :class:`~.resource.SpecsResources` including symbolic expressions, rather than one with concrete values. For example, consider the following circuit which contains a ``for`` loop with a non-static range: .. code-block:: python dev = qp.device("lightning.qubit", wires=1) @qp.qjit(autograph=True) @qp.qnode(dev) def circuit(x, z): qp.Hadamard(0) qp.PauliX(0) for _ in range(x): qp.PauliX(0) for _ in range(z): qp.PauliZ(0) return qp.expval(qp.PauliZ(0)) >>> specs_result = qp.specs(circuit, level=0)(5, 3) If we attempt to get pass-by-pass specs for this circuit, the resource information will be symbolic due to the dependence on the input parameters ``x`` and ``z``: >>> print(specs_result) # doctest: +SKIP Device: lightning.qubit Device wires: 1 Shots: Shots(total=None) Level: Before MLIR Passes <BLANKLINE> Symbolic Variables: a, b Quantum operations: - Total: b + a + 2 - Hadamard: 1 - PauliX: a + 1 - PauliZ: b Measurement processes: - expval(PauliZ): 1 Total wires: 1 Circuit Depth: Not computed You can estimate the concrete resource values using the ``.subs`` method of the returned :class:`~.resource.SpecsResources` object, and providing keyword arguments which describe the mapping from each symbolic variable to an integer value: >>> res = specs_result.resources # doctest: +SKIP >>> print(res.subs(a=5, b=3)) # doctest: +SKIP Quantum operations: - Total: 10 - Hadamard: 1 - PauliX: 6 - PauliZ: 3 Measurement processes: - expval(PauliZ): 1 Total wires: 1 Circuit Depth: Not computed These substitutions may also be provided as a dictionary, which can be helpful in programmatic contexts: >>> print(res.subs({"a": 5, "b": 3})) # doctest: +SKIP Quantum operations: - Total: 10 - Hadamard: 1 - PauliX: 6 - PauliZ: 3 Measurement processes: - expval(PauliZ): 1 Total wires: 1 Circuit Depth: Not computed """ qnode, partial_args, partial_kwargs = unwrap_partial(qnode) if isinstance(qnode, QNode): raise ValueError( "qp.specs no longer supports being applied to a bare QNode; it must be applied to " "a qjit'd QNode. Instead, apply qp.qjit to the QNode first or consider " "using qp.workflow.construct_tape with qp.resource.resources_from_tape." ) return apply_partial_args( partial(_specs_qjit, qnode, level, compute_depth), partial_args, partial_kwargs )