Complexity Metrics¶

ComplexityMetrics calculates comprehensive circuit complexity analysis based on research literature using the unified schema-based API.

Key Features: - Unified API: Single get_metrics() method returns ComplexityMetricsSchema - Research-Based: Implements metrics from “Character Complexity: A Novel Measure for Quantum Circuit Analysis” by D. Shami - Comprehensive Analysis: Gate-based, entanglement, standardized, advanced, and derived metrics - Type Safety: Full validation with IDE support

Metric Categories: - Gate-Based Metrics: Gate counts, T-count, CNOT count, multi-qubit ratios - Entanglement Metrics: Entangling gate density, entangling width - Standardized Metrics: Circuit volume, gate density, Clifford ratio - Advanced Metrics: Parallelism factor, circuit efficiency - Derived Metrics: Weighted complexity scores

Usage Example:

from qiskit import QuantumCircuit
from qward.metrics import ComplexityMetrics

# Create circuit
circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(0, 2)

# Analyze with type-safe API
complexity_metrics = ComplexityMetrics(circuit)
metrics = complexity_metrics.get_metrics()  # Returns ComplexityMetricsSchema

# Access validated complexity data
print(f"Gate count: {metrics.gate_based_metrics.gate_count}")
print(f"T-gate count: {metrics.gate_based_metrics.t_count}")
print(f"Circuit volume: {metrics.standardized_metrics.circuit_volume}")
print(f"Parallelism factor: {metrics.advanced_metrics.parallelism_factor:.3f}")

API Reference¶

Complexity metrics implementation for QWARD.

This module provides the ComplexityMetrics class for analyzing quantum circuits and extracting various complexity metrics as described in research literature. The metrics include gate-based metrics, entanglement metrics, standardized metrics, advanced metrics, and derived metrics.

Reference:

[1] D. Shami, “Character Complexity: A Novel Measure for Quantum Circuit Analysis,”: Sep. 18, 2024, arXiv: arXiv:2408.09641. doi: 10.48550/arXiv.2408.09641.

class ComplexityMetrics(circuit)[source]¶

Bases: MetricCalculator

Calculate complexity metrics from QuantumCircuit objects.

This class provides methods for analyzing quantum circuits and extracting various complexity metrics including gate-based metrics, entanglement metrics, standardized metrics, advanced metrics, and derived metrics.

The complexity metrics help characterize the computational difficulty and resource requirements of quantum circuits.

Initialize a MetricCalculator object.

Parameters:: circuit (QuantumCircuit) – The quantum circuit to analyze

get_advanced_metrics()[source]¶

Get advanced complexity metrics as a validated schema object.

Returns:: Validated advanced metrics
Return type:: AdvancedMetricsSchema

get_advanced_metrics_dict()[source]¶

Get advanced complexity metrics as a dictionary.

Returns:: Dictionary containing advanced circuit analysis metrics
Return type:: Dict[str, Any]

get_derived_metrics()[source]¶

Get derived complexity metrics as a validated schema object.

Returns:: Validated derived metrics
Return type:: DerivedMetricsSchema

get_derived_metrics_dict()[source]¶

Get derived complexity metrics as a dictionary.

Returns:: Dictionary containing derived circuit metrics
Return type:: Dict[str, Any]

get_entanglement_metrics()[source]¶

Get entanglement-based complexity metrics as a validated schema object.

Returns:: Validated entanglement metrics
Return type:: EntanglementMetricsSchema

get_entanglement_metrics_dict()[source]¶

Get entanglement-based complexity metrics as a dictionary.

Returns:: Dictionary containing entanglement-related metrics
Return type:: Dict[str, Any]

get_gate_based_metrics()[source]¶

Get gate-based complexity metrics as a validated schema object.

Returns:: Validated gate-based metrics
Return type:: GateBasedMetricsSchema

get_gate_based_metrics_dict()[source]¶

Get gate-based complexity metrics as a dictionary.

Returns:: Dictionary containing gate counts and ratios
Return type:: Dict[str, Any]

get_metrics()[source]¶

Get all complexity metrics as a structured, validated schema object.

Returns:

Complete validated complexity metrics schema

Return type:

ComplexityMetricsSchema

Raises:

ImportError – If Pydantic schemas are not available
ValidationError – If metrics data doesn’t match schema constraints

get_standardized_metrics()[source]¶

Get standardized complexity metrics as a validated schema object.

Returns:: Validated standardized metrics
Return type:: StandardizedMetricsSchema

get_standardized_metrics_dict()[source]¶

Get standardized complexity metrics as a dictionary.

Returns:: Dictionary containing standardized circuit metrics
Return type:: Dict[str, Any]

is_ready()[source]¶

Check if the metric is ready to be calculated.

Return type:: bool