qp.specs¶
- specs(qnode, level=None, compute_depth=None)[source]¶
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.
- Parameters:
qnode (
QJIT) – the (qjit’d) QNode to calculate the specifications for.functools.partialwrappers around supported callables are also accepted.- Keyword Arguments:
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,specswill always attempt to calculate circuit depth (behaves asTrue), except where not available, such as in pass-by-pass analysis forqjit-compiled workflows.
- Returns:
A function that has the same argument signature as
qnode. This function returns aCircuitSpecsobject containing theqnodespecifications, including gate and measurement data, total wires, device information, shots, and more.
See also
analyze(), which provides the same pass-by-pass analysis, andtrack(), 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
specscalculations. If circuit depth is not needed, setcompute_depth=False.Note
The available options for
levelsare:"top"or0: 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
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 Quantum operations: - Total: 2 - CNOT: 1 - RX: 1 Measurement processes: - probs(2 wires): 1 Total wires: 2 Circuit Depth: Not computed
The
SpecsResourcescan be accessed using the.resourcesattribute, which provides more direct access to the data fields. For example:>>> qp.specs(circuit)(1.23).resources.quantum_operations {'CNOT': 1, 'RX': 1}
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.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 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.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
forloop with a non-static range or awhileloop will be counted as if only one iteration occurred. Additionally, resources contained in conditional branches fromiforswitchstatements 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
levelargument:An
int: the desired transform level of a user-applied transform, see the note belowA marker name (str): The name of an applied
qp.markertransformAn iterable: A
list,tuple, or similar containing ints and/or marker names. Should be sorted in ascending transform order with no duplicatesThe string
"all": To provide information at each stage of compilation with respect to user-specified transformsThe string
"user": To provide information after all user-specified transforms have been applied
Note
The
levelargument is based on user-applied transforms. Level0always 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:
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) >>> print(all_specs) Device: lightning.qubit Device wires: 3 Shots: Shots(total=None) Levels: - 0: Before MLIR Passes - 1: After cancel-inverses - 2: After merge-rotations ↓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 returnedCircuitSpecsobject’s.resourcesattribute, using the name of a transform or marker. For example:>>> print(all_specs.resources['merge-rotations']) 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 themerge-rotationstransform:>>> print(qp.specs(circuit, level="user")(1.23).resources) 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-commutingtransform, can result in splitting a single execution into multiple executions. In this case, the resources for that level will be returned as a list ofSpecsResourcesobjects. When printed, these split executions will be shown as individual columns.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")()) Device: lightning.qubit Device wires: 3 Shots: Shots(total=None) Levels: - 0: Before MLIR Passes - 1: After split-non-commuting - 2: After cancel-inverses ↓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-commutingtransform results in two separate executions, which are labeled with the suffixes-aand-bin 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.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,
specsmay 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 aSpecsResourcesincluding symbolic expressions, rather than one with concrete values. For example, consider the following circuit which contains aforloop with a non-static range: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
xandz:>>> print(specs_result) Device: lightning.qubit Device wires: 1 Shots: Shots(total=None) Level: Before MLIR Passes 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
.subsmethod of the returnedSpecsResourcesobject, and providing keyword arguments which describe the mapping from each symbolic variable to an integer value:>>> res = specs_result.resources >>> print(res.subs(a=5, b=3)) 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})) Quantum operations: - Total: 10 - Hadamard: 1 - PauliX: 6 - PauliZ: 3 Measurement processes: - expval(PauliZ): 1 Total wires: 1 Circuit Depth: Not computed