Circuit Performance Metrics¶

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

Key Features: - Unified API: Single get_metrics() method returns FidelitySchema - 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 import FidelityMetrics

# 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 = FidelityMetrics(
    circuit=circuit,
    job=job,
    success_criteria=bell_state_success
)
metrics = circuit_performance.get_metrics()  # Returns FidelitySchema

# Access validated fidelity data
print(f"Success rate: {metrics.success_rate:.3f}")
print(f"DSR: {metrics.dsr:.3f}")
print(f"Hellinger fidelity: {metrics.hellinger_fidelity:.3f}")

API Reference¶

Fidelity metrics for quantum circuit output validation.

Computes DSR (Michelson), Hellinger fidelity, TVD, and success rate from Sampler results, or expectation-value-based metrics from Estimator results. Automatically detects the primitive type from the provided inputs.

class FidelityMetrics(circuit, *, job=None, jobs=None, counts=None, expected_outcomes=None, target_histogram=None, target_state=None, success_criteria=None, expectation_values=None, standard_deviations=None, ideal_expectation_values=None, observable_labels=None)[source]¶

Bases: MetricCalculator

Post-runtime fidelity metrics for quantum circuit outputs.

Handles both Qiskit primitive types automatically: - Sampler (counts/histograms): DSR, Hellinger fidelity, TVD, success rate - Estimator (expectation values): success probability, observable fidelity,

SNR, depolarization factor

Example

# Sampler path — from counts fm = FidelityMetrics(circuit, counts={“00”: 900, “11”: 100}, target_state=”00”)

# Sampler path — from job fm = FidelityMetrics(circuit, job=sampler_job, expected_outcomes=[“00”])

# Estimator path — from values fm = FidelityMetrics(circuit, expectation_values=np.array([0.95]))

# Estimator path — from job (auto-detected) fm = FidelityMetrics(circuit, job=estimator_job)

Initialize a MetricCalculator object.

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

add_job(job)[source]¶

Add one or more jobs for multi-job analysis.

Return type:: None

get_metrics()[source]¶

Compute fidelity metrics based on detected primitive type.

Returns FidelitySchema for Sampler results, EstimatorSchema for Estimator results.

Return type:: Any

get_metrics_all()[source]¶

Compute fidelity metrics for each job. Returns one schema per job.

When using counts (no jobs), returns a single-element list.

Return type:: List[Any]

is_ready()[source]¶

Check if the metric is ready to be calculated.

Returns:: True if the metric is ready to be calculated, False otherwise
Return type:: bool

property primitive_type: str¶

‘sampler’, ‘estimator’, or ‘unknown’.

Type:: Detected primitive type