Structural Metrics¶

Structural Metrics implementation for QWARD.

This module provides the StructuralMetrics class for analyzing the structural properties of quantum circuits within the QWARD framework. Structural metrics characterize how a circuit is organized, independent of the specific gates or quantum states involved.

These metrics capture global and topological attributes such as circuit depth, width, size, density, connectivity, and structural complexity indicators adopted from software engineering.

[1]J. Zhao, “Some Size and Structure Metrics for Quantum Software.” 2021. [Online]. Available: https://arxiv.org/abs/2103.08815

class StructuralMetrics(circuit)[source]¶

Bases: MetricCalculator

Extract structural metrics from QuantumCircuit objects.

This class analyzes the structural organization of a quantum circuit and computes metrics that describe its shape, topology, and logical arrangement. Structural metrics include circuit depth, width, size, density, connectivity, and software-engineering-inspired metrics such as LOC and Halstead adapted to quantum circuit representations.

circuit¶

The quantum circuit to analyze (inherited from MetricCalculator).

Type:: QuantumCircuit

_circuit_dag¶

DAG representation of the circuit, used to compute depth, connectivity, structural relationships, and topological features.

Type:: DAGCircuit | None

Initialize the StructuralMetrics 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 structural metrics combining LOC, Halstead, and circuit structure.

Returns:: Validated schema with all metrics
Return type:: StructuralMetricsSchema
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 Structural Metrics module provides a unified analysis of the structural properties of a quantum circuit. It integrates three complementary metric families:

Quantum Lines-of-Code (ϕ1–ϕ6) as proposed in quantum software engineering (e.g., total LOC, quantum-only LOC, measurement LOC, number of qubits, and gate-type diversity).
Halstead Metrics adapted to quantum circuits, where quantum gates act as operators and qubits/classical bits/parameters act as operands. These metrics estimate program vocabulary, program length, volume, difficulty, and effort—offering an early indication of cognitive complexity before execution.
Circuit Shape Metrics, computed from the circuit DAG, which quantify: - Width (number of qubits), - Depth (longest sequential chain of operations), - Size (total operations), - Maximum and average density (number of operations per DAG layer).

Together, these metrics capture the structural, topological, and cognitive complexity of a quantum program, enabling static analysis, comparison of circuit architectures, and complexity-aware optimizations.

Autosummary¶

StructuralMetrics(circuit)

Extract structural metrics from QuantumCircuit objects.

Selected Formulas¶

The following equations summarize key computed metrics:

Halstead Vocabulary n = n₁ + n₂ where n₁ = number of unique operators, and n₂ = number of unique operands.

Halstead Program Length N = N₁ + N₂ where N₁ = total operators, and N₂ = total operands.

Halstead Estimated Length N̂ = n₁ * log₂(n₁) + n₂ * log₂(n₂)

Halstead Volume V = N * log₂(n)

Halstead Difficulty D = (n₁ / 2) * (N₂ / n₂)

Halstead Effort E = D * V

Circuit Density - max_dens = maximum number of operations in any DAG layer - avg_dens = average number of operations across all layers

Usage Example¶

from qiskit import QuantumCircuit
from qward.metrics import StructuralMetrics

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

metrics = StructuralMetrics(qc).get_metrics()

print("Depth:", metrics.depth)
print("Halstead Volume:", metrics.volume)
print("Estimated Effort:", metrics.effort)
print("Average Density:", metrics.avg_dens)

Notes¶

Structural metrics are pre-runtime; they do not require circuit execution.
Measurements and classical operations are included as operands but are treated differently from quantum gates in LOC and Halstead categories.
Density metrics depend on the DAG structure; circuits with higher parallelism exhibit lower depth but potentially higher per-layer operation counts.

References¶

[1]J. Zhao, “Some Size and Structure Metrics for Quantum Software.” 2021.

[Online]. Available: https://arxiv.org/abs/2103.08815