# 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 tracking the resources of an executed circuit"""
from __future__ import annotations
import copy
import json
import os
import tempfile
import time
from collections.abc import Callable
from functools import partial
from pathlib import Path
from typing import Any
from pennylane.workflow._levels import (
device_level,
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 .resource import CircuitSpecs, SpecsResources
# Used for device-level qjit resource tracking
_RESOURCE_TRACKING_PREFIX = "pennylane_track_resources"
def _run_with_resource_tracking(
func, original_qnode, *args, compute_depth: bool, **kwargs
) -> tuple[Any, SpecsResources]:
"""Execute a qjit'd QNode on ``null.qubit`` with resource tracking enabled.
Returns the result of the execution along with the resources counted while running it.
"""
# Have to import locally to prevent circular imports as well as accounting for Catalyst not being installed
# pylint: disable=import-outside-toplevel
from catalyst import QJIT
from ..devices import NullQubit
with tempfile.TemporaryDirectory(
prefix=f"{_RESOURCE_TRACKING_PREFIX}_{os.getpid()}_"
) as tmpdirname:
filepath = Path(f"{tmpdirname}/{_RESOURCE_TRACKING_PREFIX}_{time.time_ns()}.json")
# When running at the device level, execute on null.qubit directly with resource tracking,
# which will give resource usage information for after all transforms have completed
# TODO: Find a way to inherit all devices args from input
original_device = original_qnode.device
spoofed_dev = NullQubit(
target_device=original_device,
wires=original_device.wires,
track_resources=True,
resources_filename=str(filepath),
compute_depth=compute_depth,
)
new_qnode = original_qnode.update(device=spoofed_dev)
new_qjit = QJIT(new_qnode, copy.deepcopy(func.compile_options))
# Execute on null.qubit with resource tracking
results = new_qjit(*args, **kwargs)
with filepath.open("r", encoding="utf-8") as f:
resource_data = json.load(f)
return results, SpecsResources(
counts=resource_data["gate_types"],
measurement_processes=resource_data["measurements"],
num_wires=resource_data["num_wires"],
circuit_depth=resource_data["depth"],
)
def _track_qjit(func, level, *args, **kwargs) -> tuple[Any, CircuitSpecs]:
"""Execute a qjit'd QNode on ``null.qubit`` and return its result along with its specs."""
original_qnode = unwrap_qjit_qnode(func, fn_name="qp.track")
compile_pipeline = original_qnode.compile_pipeline
validate_level(level, compile_pipeline)
if isinstance(level, slice):
# A slice that selects all the transforms, including the device preprocessing
is_device = pipeline_at_slice(compile_pipeline, level) == pipeline_at_slice(
compile_pipeline, slice(0, None)
)
else:
is_device = is_single_level(level) and level_to_number(
level, compile_pipeline
) == device_level(compile_pipeline)
if not is_device:
raise NotImplementedError(f"qp.track only supports level='device', instead got: {level!r}.")
results, resources = _run_with_resource_tracking(
func, original_qnode, *args, compute_depth=True, **kwargs
)
# TODO: report the actual level once levels other than the device level are supported
return results, build_circuit_specs(original_qnode, resources, "device")
[docs]
def track(
qnode,
level: str | int | slice = "device",
) -> Callable[..., tuple[Any, CircuitSpecs]]:
r"""Executes a quantum circuit and tracks the resources it uses.
This transform converts a QNode into a callable that executes the circuit on
``null.qubit`` and returns both the result of that execution and the resource
information gathered while running it.
Args:
qnode (:class:`~catalyst.jit.QJIT`): the (qjit'd) QNode to execute and track.
``functools.partial`` wrappers around supported callables are also accepted.
Keyword Args:
level (str | int | slice): The portion of the
:class:`~.CompilePipeline` to apply before executing the circuit and tracking its
resources. See :func:`~.workflow.get_compile_pipeline` for accepted values.
Currently, only ``"device"`` is supported. Defaults to ``"device"``.
Returns:
A function that has the same argument signature as ``qnode``. This function returns a
tuple containing the result of executing the circuit and a
:class:`~.resource.CircuitSpecs` object containing the ``qnode`` specifications,
including gate and measurement data, total wires, device information, shots, and more.
.. seealso:: :func:`~pennylane.estimate`, :func:`~.analyze`
.. note::
Resources are tracked by mock-executing the workflow on ``null.qubit``. For a QNode bound
to any other device, the returned execution result therefore carries the shape and dtype
of that device's result, but not its values.
.. warning::
``null.qubit`` does not perform a true state-vector simulation, so mid-circuit measurement
outcomes are not grounded in real measurement statistics. If the circuit contains a
conditional whose branch depends on such an outcome, the reported circuit depth and any
branch-dependent gate counts correspond to the branch taken during the mock execution, and
should be treated as an estimate rather than exact counts.
**Example**
.. code-block:: python
n_wires = 2
dev = qp.device("lightning.qubit", wires=n_wires)
@qp.qjit
@qp.qnode(dev)
def circuit(theta):
qp.RX(theta, wires=0)
qp.CNOT(wires=(0,1))
return qp.probs(wires=(0,1))
>>> result, circuit_specs = qp.track(circuit)(1.23)
>>> circuit_specs.resources.quantum_operations
{'CNOT': 1, 'RX': 1}
Since the circuit is executed on ``null.qubit``, the result has the shape and dtype of the
``lightning.qubit`` result, but not its values:
>>> result
Array([1., 0., 0., 0.], dtype=float64)
>>> circuit(1.23)
Array([0.66711886, 0. , 0. , 0.33288114], dtype=float64)
The specifications are the same as the ones returned by :func:`~.specs` at the device level:
>>> circuit_specs == qp.specs(circuit, level="device")(1.23)
True
Because the circuit is executed, control flow is unrolled with the given arguments and
the resources are concrete numbers:
.. code-block:: python
@qp.qjit(autograph=True)
@qp.qnode(dev)
def circuit(n):
for i in range(n):
qp.Hadamard(wires=i % n_wires)
qp.CNOT(wires=(0, 1))
return qp.probs(wires=(0, 1))
>>> _, circuit_specs = qp.track(circuit)(3)
>>> circuit_specs.resources.quantum_operations
{'CNOT': 1, 'Hadamard': 3}
In contrast, :func:`~.analyze` does not execute the circuit, so it reports the number of
loop iterations symbolically:
>>> qp.analyze(circuit, level=0)(3).resources.quantum_operations
{'CNOT': 1, 'Hadamard': Expression({('a',): 1})}
"""
qnode, partial_args, partial_kwargs = unwrap_partial(qnode)
return apply_partial_args(partial(_track_qjit, qnode, level), partial_args, partial_kwargs)