Element Metrics (Gate-Level)

Quantum Software Quality Metrics implementation for QWARD.

This module provides the ElementMetrics class for analyzing quantum circuits and extracting fundamental element-level metrics used across the QWARD framework. These metrics focus on quantifying the basic building blocks of a circuit, including qubits and quantum gates, as well as their distributions and relationships.

This module provides the ElementMetrics class for analyzing quantum circuits and extracting comprehensive quality metrics as defined in the paper:

[ ] 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.

These metrics provide detailed analysis of quantum circuit structure, gate distribution, and oracle usage patterns for quality assessment and comparison.

class ElementMetrics(circuit)[source]

Bases: MetricCalculator

Quantum Element Metrics calculator for QWARD.

This class implements element-based metrics for quantum circuits focusing on gate distribution, oracle usage patterns, and measurement analysis.

Initialize the ElementMetrics calculator.

Parameters:

circuit (QuantumCircuit) – The quantum circuit to analyze

property circuit: QuantumCircuit

Get the quantum circuit.

Returns:

The quantum circuit

Return type:

QuantumCircuit

get_metrics()[source]

Calculate and return quantum element metrics.

Returns:

Validated schema with all metrics

Return type:

ElementMetricsSchema

Raises:

ImportError – If schemas are not available

property id

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

The ElementMetrics component provides low-level, gate– and qubit–oriented metrics that describe the fundamental building blocks of a quantum circuit. These metrics quantify:

  • Distribution of Pauli, single-qubit, controlled, and multi-qubit gates

  • Oracle usage patterns (simple and controlled)

  • Qubit activation and interaction patterns

  • CNOT- and Toffoli-related qubit involvement

  • Measurement and ancilla utilization

They represent a core metric family in QWARD, directly aligned with the definition of elementary circuit properties proposed by Cruz-Lemus et al. (QUATIC 2021).

Autosummary

ElementMetrics(circuit)

Quantum Element Metrics calculator for QWARD.

Selected Formulas

  • Total Pauli gates: t_no_p = no_p_x + no_p_y + no_p_z

  • Single-qubit gates: t_no_sqg = no_h + t_no_p + no_other_sg + t_no_csqg

  • Percentage of single-qubit gates: percent_single_gates = t_no_sqg / no_gates (if no_gates > 0)

  • Superposition ratio (qubits whose first gate is H): percent_sppos_q = (# qubits with initial H) / total_qubits

  • Oracle qubit ratio: percent_q_in_or = (# qubits affected by oracles) / total_qubits

  • CNOT/Toffoli target statistics: - avg_cnot = average number of times a qubit is target of a CNOT - max_cnot = maximum among qubits - (analogous definitions for Toffoli)

Usage Example

from qiskit import QuantumCircuit
from qward.metrics import ElementMetrics

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

em = ElementMetrics(qc).get_metrics()
print(em.no_p_x, em.no_cnot, em.no_toff, em.percent_q_in_or)

References

      1. 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.