Sensitivity)¶

Quantum Specific Metrics implementation for QWARD.

This module provides the QuantumSpecificMetrics class for extracting metrics that quantify intrinsically quantum properties of a circuit within the QWARD framework. These metrics capture phenomena that have no classical analogue and directly reflect the quantum computational resources present in a circuit.

Quantum-specific metrics include measures of entanglement, coherence, sensitivity, and non-Clifford “magic,” along with other indicators of quantum behavior that define the circuit’s potential for quantum advantage and its complexity under classical simulation. By focusing on fundamental quantum effects rather than gate counts or structural arrangement, these metrics offer insight into the circuit’s true quantum nature and resource requirements.

[1] K. Bu, R. J. Garcia, A. Jaffe, D. E. Koh y L. Li, “Complexity of quantum circuits via sensitivity, magic, and coherence,” Communications in Mathematical Physics, vol. 405, no. 7, 2024, doi:10.1007/s00220-024-05030-6.

[2] T. Tomesh, P. Gokhale, V. Omole, G. S. Ravi, K. N. Smith, J. Viszlai, X.-C. Wu, N. Hardavellas, M. R. Martonosi y F. T. Chong, “SupermarQ: A scalable quantum benchmark suite,” in Proc. 2022 IEEE International Symposium on High-Performance Computer Architecture (HPCA), 2022, doi: 10.1109/HPCA53966.2022.00050.

[3] J. A. Cruz-Lemus, L. A. Marcelo, and M. Piattini, “Towards a set of metrics for quantum circuits understandability,” in *Quality of Information and Communications Technology. QUATIC 2021 (Communications in Computer and Information Science, vol. 1439) *, A. C. R. Paiva, A. R. Cavalli, P. Ventura Martins, and R. Pérez-Castillo, Eds. Cham:

Springer, 2021, pp. 238–253. doi: 10.1007/978-3-030-85347-1_18.

class QuantumSpecificMetrics(circuit)[source]¶

Bases: MetricCalculator

Extract intrinsically quantum metrics from QuantumCircuit objects.

Quantum-specific metrics provide insight into the true quantum behavior of a circuit, its resource requirements, and its expected difficulty for classical simulation. They complement structural and element-level metrics by focusing exclusively on quantum effects arising from the circuit’s transformations and state evolution.

circuit¶

The quantum circuit to analyze (inherited from MetricCalculator).

Type:: QuantumCircuit

_circuit_dag¶

DAG representation of the circuit, used for structural traversal when computing quantum-specific metrics.

Type:: DAGCircuit | None

_torch_available¶

Indicates whether PyTorch is available for metrics that rely on differentiable simulation or gradient-based optimization.

Type:: bool

_max_steps¶

Maximum number of optimization steps used in iterative or differentiable metrics (e.g., magic or sensitivity estimation).

Type:: int

_lr¶

Learning rate used for gradient-based optimization of certain metrics.

Type:: float

_device¶

Device specification (“cpu” or “cuda”) for metrics that may leverage PyTorch computation.

Type:: str

_use_trace_norm¶

Whether to use the trace norm when computing specific quantum sensitivity or distance-based metrics.

Type:: bool

Inicializa el calculador de métricas cuánticas específicas.

property circuit: QuantumCircuit¶

Get the quantum circuit.

Returns:: The quantum circuit
Return type:: QuantumCircuit

get_metrics()[source]¶

Calculate and return quantum specific metrics.

Returns:: Validated schema with all metrics
Return type:: QuantumSpecificMetricsSchema
Raises:: ImportError – If schemas are not available

property id: MetricsId¶

Get the ID of the metric.

Returns:: The ID of this metric
Return type:: MetricsId

is_ready()[source]¶

Check if the metric is ready to be calculated.

Returns:: True if the circuit is available, False otherwise
Return type:: bool

property metric_type: MetricsType¶

Get the type of this metric.

Returns:: The type of this metric
Return type:: MetricsType

property name: str¶

Get the name of the metric.

Returns:: The name of the metric class.
Return type:: str

Overview¶

Quantum-specific metrics differ fundamentally from structural or gate-level metrics. Instead of counting operations or analyzing connectivity, they evaluate properties rooted in the circuit’s action on quantum states or operators. These properties correlate strongly with classical simulability, potential quantum advantage, and the physical difficulty of implementing or maintaining a computation.

Practical Approximation Strategy¶

The original definitions of many of these metrics (especially magic, sensitivity, and coherence) require solving optimization problems over exponentially large operator spaces. In their exact form, these computations are intractable for all but the smallest circuits due to:

the exponential dimension of the operator Hilbert space,
the need to optimize over arbitrary density matrices or observables,
the requirement to evaluate full Pauli expansions with ( O(4^n) ) terms.

Because of this, QWARD implements practical, efficient approximations:

Gradient-ascent optimization Instead of optimizing over all possible states or operators, parameters are restricted (e.g., diagonal density matrices, low-weight Pauli operators), and PyTorch is used to perform differentiable optimization.
Restricted Pauli basis Instead of expanding operators over all Pauli strings up to weight ( n ), only low-weight Paulis (weight 1–2) are considered, following the empirical observation that these capture most relevant interactions in typical circuits.
Proxy quantities For example, the magic metric uses off-diagonal imaginary components as a proxy for non-stabilizerness; coherence uses the ( L^1 )-norm of off-diagonal elements; and sensitivity considers the influence difference before and after conjugation under the circuit unitary.
Measurement removal Since measurement breaks unitarity and invalidates many theoretical quantities, all metrics are computed on the unitary portion of the circuit, obtained by stripping out measurement, barrier, and reset nodes.

These approximations preserve interpretability, scalability, and relative comparability across circuits, while avoiding exponential computational cost.

Available Metrics¶

The class computes the following quantum-specific metrics:

spposq_ratio — Percentage of qubits whose first nontrivial operation is a Hadamard gate, measuring early creation of superposition.
magic — Proxy for circuit non-stabilizerness, approximated via gradient ascent over diagonal density matrices.
coherence — Approximated ( L^1 )-coherence of output states under the circuit, optimized over diagonal input states.
sensitivity — Approximate circuit sensitivity (CiS), computed as the change in influence of a restricted Pauli operator under conjugation.
entanglement_ratio — Ratio of two-qubit interactions to total non-measurement gates.

Usage Example¶

from qiskit import QuantumCircuit
from qward.metrics import QuantumSpecificMetrics

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

qsm = QuantumSpecificMetrics(qc)
metrics = qsm.get_metrics()

print(metrics.magic, metrics.coherence, metrics.entanglement_ratio)

References¶

[1] K. Bu, R. J. Garcia, A. Jaffe, D. E. Koh, and L. Li,: “Complexity of quantum circuits via sensitivity, magic, and coherence,” Communications in Mathematical Physics, vol. 405, no. 7, 2024. doi:10.1007/s00220-024-05030-6.
[2] T. Tomesh et al., “SupermarQ: A scalable quantum benchmark suite,”: IEEE HPCA 2022. doi:10.1109/HPCA53966.2022.00050.
[3] J. A. Cruz-Lemus et al.,: “Towards a set of metrics for quantum circuits understandability,” QUATIC 2021, CCIS vol. 1439, Springer, 2021. doi:10.1007/978-3-030-85347-1_18.