Circuit Performance Metrics¶

CircuitPerformanceMetrics analyzes quantum circuit execution performance using the unified schema-based API.

Key Features: - Unified API: Single get_metrics() method returns CircuitPerformanceSchema - Custom Success Criteria: User-defined success conditions for flexible analysis - Multi-Job Support: Handles both single job and multiple job analysis - Type Safety: Full validation with automatic constraint checking

Metric Categories: - Success Metrics: Success rate, error rate, successful shots analysis - Statistical Metrics: Entropy, uniformity, concentration analysis

Usage Example:

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator
from qward.metrics import CircuitPerformanceMetrics

# Create and execute circuit
circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()

simulator = AerSimulator()
job = simulator.run(circuit, shots=1000)

# Define custom success criteria
def bell_state_success(result: str) -> bool:
    clean_result = result.replace(" ", "")
    return clean_result in ["00", "11"]  # |00⟩ or |11⟩ states

# Analyze with type-safe API
circuit_performance = CircuitPerformanceMetrics(
    circuit=circuit,
    job=job,
    success_criteria=bell_state_success
)
metrics = circuit_performance.get_metrics()  # Returns CircuitPerformanceSchema

# Access validated performance data
print(f"Success rate: {metrics.success_metrics.success_rate:.3f}")
print(f"Error rate: {metrics.success_metrics.error_rate:.3f}")
print(f"Entropy: {metrics.statistical_metrics.entropy:.3f}")

API Reference¶

Circuit performance metrics implementation for QWARD.

This module provides the CircuitPerformanceMetrics class for analyzing the performance of quantum circuits based on job execution results. It supports both single job and multiple job analysis with customizable success criteria.

Supports multiple job types: - AerJob: Qiskit Aer simulator jobs - QiskitJob (JobV1): Traditional Qiskit jobs - RuntimeJobV2: IBM Quantum Runtime V2 primitive jobs (SamplerV2, EstimatorV2)

The performance metrics help evaluate the success rate and statistical properties of quantum circuit executions.

class CircuitPerformanceMetrics(circuit, *, job=None, jobs=None, success_criteria=None, expected_outcomes=None)[source]¶

Bases: MetricCalculator

Calculate circuit performance metrics for quantum circuits.

This class provides methods for analyzing the performance of quantum circuits based on job execution results. It supports both single job and multiple job analysis with customizable success criteria.

Supports multiple job types: - AerJob: Qiskit Aer simulator jobs - QiskitJob (JobV1): Traditional Qiskit jobs - RuntimeJobV2: IBM Quantum Runtime V2 primitive jobs (SamplerV2, EstimatorV2)

The performance metrics include: - Success metrics: Success rate, error rate, successful shots analysis - Statistical metrics: Entropy, uniformity, concentration analysis

Example

# Basic usage with default success criteria (ground state) performance = CircuitPerformanceMetrics(circuit, job=job) metrics = performance.get_metrics()

# With RuntimeJobV2 from SamplerV2 from qiskit_ibm_runtime import SamplerV2 as Sampler sampler = Sampler(backend) job = sampler.run([circuit]) # Returns RuntimeJobV2 performance = CircuitPerformanceMetrics(circuit, job=job) success_metrics = performance.get_success_metrics()

# With custom success criteria def custom_success(state): return state == “101”

performance = CircuitPerformanceMetrics(: circuit, job=job, success_criteria=custom_success

) success_metrics = performance.get_success_metrics()

Initialize a CircuitPerformanceMetrics object.

Parameters:

circuit (QuantumCircuit) – The quantum circuit to analyze
job (Union[AerJob, RuntimeJobV2, None]) – A single job that executed the circuit
jobs (Optional[List[Union[AerJob, RuntimeJobV2]]]) – A list of jobs that executed the circuit (for multiple runs)
success_criteria (Optional[Callable[[str], bool]]) – Function that determines if a measurement result is successful
expected_outcomes (Optional[List[str]]) – Expected bitstrings for DSR histogram contrast calculations

add_job(job)[source]¶

Add one or more jobs to the list of jobs for multiple job metrics.

Parameters:: job (Union[AerJob, RuntimeJobV2, List[Union[AerJob, RuntimeJobV2]]]) – A single job or a list of jobs to add
Return type:: None

static create_bell_state_distribution()[source]¶

Create the expected distribution for a Bell state (|00⟩ + |11⟩)/√2.

Returns:: Bell state distribution
Return type:: Dict[str, float]

static create_ground_state_distribution(num_qubits)[source]¶

Create a distribution where only the ground state (|000…⟩) has probability 1.

Parameters:: num_qubits (int) – Number of qubits in the circuit
Returns:: Ground state distribution
Return type:: Dict[str, float]

static create_uniform_distribution(num_qubits)[source]¶

Create a uniform distribution over all possible measurement outcomes.

Parameters:: num_qubits (int) – Number of qubits in the circuit
Returns:: Uniform probability distribution
Return type:: Dict[str, float]

get_dsr_metrics()[source]¶

Get Differential Success Rate metrics as a validated schema object.

Returns:

Validated DSR metrics schema

Return type:

DSRVariantsSchema

Raises:

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

get_dsr_metrics_dict()[source]¶

Get Differential Success Rate metrics as a dictionary.

Returns:: Dictionary containing DSR variant and mismatch metrics
Return type:: Dict[str, Any]

get_metrics()[source]¶

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

Returns:

Complete validated performance metrics schema

Return type:

CircuitPerformanceSchema

Raises:

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

get_multiple_jobs_metrics()[source]¶

Calculate circuit performance metrics from multiple job results.

DEPRECATED: Use get_success_metrics() or get_statistical_metrics() instead.

Returns:: Circuit performance metrics for multiple jobs with individual and aggregate data
Return type:: Dict[str, Any]

get_single_job_metrics(job=None)[source]¶

Calculate circuit performance metrics from a single job result.

DEPRECATED: Use get_success_metrics() or get_statistical_metrics() instead.

Parameters:: job (Union[AerJob, RuntimeJobV2, None]) – Optional job to use for metrics calculation. If None, uses self._job.
Returns:: Circuit performance metrics for a single job
Return type:: Dict[str, Any]

get_statistical_metrics()[source]¶

Get statistical analysis metrics as a validated schema object.

Returns:

Validated statistical metrics schema

Return type:

StatisticalMetricsSchema

Raises:

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

get_statistical_metrics_dict()[source]¶

Get statistical analysis metrics as a dictionary.

Returns:: Dictionary containing entropy, uniformity, and concentration metrics
Return type:: Dict[str, Any]

get_structured_multiple_jobs_metrics()[source]¶

Get multiple jobs metrics as a validated schema object.

DEPRECATED: Use get_structured_metrics() instead.

Returns:: Validated aggregate metrics
Return type:: CircuitPerformanceSchema

get_structured_single_job_metrics(job=None)[source]¶

Get single job metrics as a validated schema object.

DEPRECATED: Use get_structured_metrics() instead.

Returns:: Validated single job metrics
Return type:: CircuitPerformanceSchema

get_success_metrics()[source]¶

Get success rate analysis metrics as a validated schema object.

Returns:

Validated success metrics schema

Return type:

SuccessMetricsSchema

Raises:

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

get_success_metrics_dict()[source]¶

Get success rate analysis metrics as a dictionary.

Returns:: Dictionary containing success rate, error rate, and shot analysis
Return type:: Dict[str, Any]

is_ready()[source]¶

Check if the metric is ready to be calculated.

Return type:: bool

class CircuitPerformanceMetrics(circuit, *, job=None, jobs=None, success_criteria=None, expected_outcomes=None)[source]¶

Bases: MetricCalculator

Calculate circuit performance metrics for quantum circuits.

This class provides methods for analyzing the performance of quantum circuits based on job execution results. It supports both single job and multiple job analysis with customizable success criteria.

Supports multiple job types: - AerJob: Qiskit Aer simulator jobs - QiskitJob (JobV1): Traditional Qiskit jobs - RuntimeJobV2: IBM Quantum Runtime V2 primitive jobs (SamplerV2, EstimatorV2)

The performance metrics include: - Success metrics: Success rate, error rate, successful shots analysis - Statistical metrics: Entropy, uniformity, concentration analysis

Example

# Basic usage with default success criteria (ground state) performance = CircuitPerformanceMetrics(circuit, job=job) metrics = performance.get_metrics()

# With custom success criteria def custom_success(state): return state == “101”

performance = CircuitPerformanceMetrics(: circuit, job=job, success_criteria=custom_success

) success_metrics = performance.get_success_metrics()

Initialize a CircuitPerformanceMetrics object.

Parameters:

circuit (QuantumCircuit) – The quantum circuit to analyze
job (Union[AerJob, RuntimeJobV2, None]) – A single job that executed the circuit
jobs (Optional[List[Union[AerJob, RuntimeJobV2]]]) – A list of jobs that executed the circuit (for multiple runs)
success_criteria (Optional[Callable[[str], bool]]) – Function that determines if a measurement result is successful
expected_outcomes (Optional[List[str]]) – Expected bitstrings for DSR histogram contrast calculations

add_job(job)[source]¶

Add one or more jobs to the list of jobs for multiple job metrics.

Parameters:: job (Union[AerJob, RuntimeJobV2, List[Union[AerJob, RuntimeJobV2]]]) – A single job or a list of jobs to add
Return type:: None

property circuit: QuantumCircuit¶

Get the quantum circuit.

Returns:: The quantum circuit
Return type:: QuantumCircuit

static create_bell_state_distribution()[source]¶

Create the expected distribution for a Bell state (|00⟩ + |11⟩)/√2.

Returns:: Bell state distribution
Return type:: Dict[str, float]

static create_ground_state_distribution(num_qubits)[source]¶

Create a distribution where only the ground state (|000…⟩) has probability 1.

Parameters:: num_qubits (int) – Number of qubits in the circuit
Returns:: Ground state distribution
Return type:: Dict[str, float]

static create_uniform_distribution(num_qubits)[source]¶

Create a uniform distribution over all possible measurement outcomes.

Parameters:: num_qubits (int) – Number of qubits in the circuit
Returns:: Uniform probability distribution
Return type:: Dict[str, float]

get_dsr_metrics()[source]¶

Get Differential Success Rate metrics as a validated schema object.

Returns:

Validated DSR metrics schema

Return type:

DSRVariantsSchema

Raises:

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

get_dsr_metrics_dict()[source]¶

Get Differential Success Rate metrics as a dictionary.

Returns:: Dictionary containing DSR variant and mismatch metrics
Return type:: Dict[str, Any]

get_metrics()[source]¶

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

Returns:

Complete validated performance metrics schema

Return type:

CircuitPerformanceSchema

Raises:

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

get_multiple_jobs_metrics()[source]¶

Calculate circuit performance metrics from multiple job results.

DEPRECATED: Use get_success_metrics() or get_statistical_metrics() instead.

Returns:: Circuit performance metrics for multiple jobs with individual and aggregate data
Return type:: Dict[str, Any]

get_single_job_metrics(job=None)[source]¶

Calculate circuit performance metrics from a single job result.

DEPRECATED: Use get_success_metrics() or get_statistical_metrics() instead.

Parameters:: job (Union[AerJob, RuntimeJobV2, None]) – Optional job to use for metrics calculation. If None, uses self._job.
Returns:: Circuit performance metrics for a single job
Return type:: Dict[str, Any]

get_statistical_metrics()[source]¶

Get statistical analysis metrics as a validated schema object.

Returns:

Validated statistical metrics schema

Return type:

StatisticalMetricsSchema

Raises:

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

get_statistical_metrics_dict()[source]¶

Get statistical analysis metrics as a dictionary.

Returns:: Dictionary containing entropy, uniformity, and concentration metrics
Return type:: Dict[str, Any]

get_structured_multiple_jobs_metrics()[source]¶

Get multiple jobs metrics as a validated schema object.

DEPRECATED: Use get_structured_metrics() instead.

Returns:: Validated aggregate metrics
Return type:: CircuitPerformanceSchema

get_structured_single_job_metrics(job=None)[source]¶

Get single job metrics as a validated schema object.

DEPRECATED: Use get_structured_metrics() instead.

Returns:: Validated single job metrics
Return type:: CircuitPerformanceSchema

get_success_metrics()[source]¶

Get success rate analysis metrics as a validated schema object.

Returns:

Validated success metrics schema

Return type:

SuccessMetricsSchema

Raises:

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

get_success_metrics_dict()[source]¶

Get success rate analysis metrics as a dictionary.

Returns:: Dictionary containing success rate, error rate, and shot analysis
Return type:: Dict[str, Any]

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.

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