Scanner

The Scanner class is the main entry point for analyzing quantum circuits in QWARD. It orchestrates metric calculation and automatically converts schema objects to DataFrames for analysis and visualization.

Key Features: - Unified Interface: Works seamlessly with all metric calculators - Automatic Conversion: Converts schema objects to DataFrames via to_flat_dict() - Flexible Input: Accepts circuits, jobs, and metric calculator instances or classes - DataFrame Output: Returns dictionary of pandas DataFrames for analysis

Usage Example:

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator
from qward import Scanner
from qward.metrics import QiskitMetrics, ComplexityMetrics, CircuitPerformanceMetrics

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

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

# Create scanner and add metrics
scanner = Scanner(circuit=circuit, job=job)
scanner.add_strategy(QiskitMetrics(circuit))
scanner.add_strategy(ComplexityMetrics(circuit))
scanner.add_strategy(CircuitPerformanceMetrics(circuit=circuit, job=job))

# Calculate metrics (returns DataFrames)
results = scanner.calculate_metrics()

# Access DataFrames for analysis
print("Available metrics:", list(results.keys()))
print("QiskitMetrics shape:", results["QiskitMetrics"].shape)
print("ComplexityMetrics shape:", results["ComplexityMetrics"].shape)

Integration with Schema API:

The Scanner automatically detects when metric calculators return schema objects and converts them to flat dictionaries for DataFrame creation, while preserving all the benefits of schema validation.

# Schema objects are automatically converted
# QiskitMetrics.get_metrics() → QiskitMetricsSchema → DataFrame
# ComplexityMetrics.get_metrics() → ComplexityMetricsSchema → DataFrame
# CircuitPerformanceMetrics.get_metrics() → CircuitPerformanceSchema → DataFrame

API Reference

Scanner class for QWARD.

class ScanResult(metrics, scanner)

Bases: object

Thin wrapper around scanner metrics with fluent post-processing helpers.

get(key, default=None)

items()

keys()

summary()

Display scanner summary and return self for chaining.

Return type:

ScanResult

to_dict()

Return a shallow copy of the wrapped metrics dictionary.

Return type:

Dict[str, DataFrame]

values()

visualize(*, save=False, show=True, output_dir='qward/examples/img', config=None, selections=None)

Visualize wrapped metrics and return self for chaining.

If selections are provided, generate selected plots. Otherwise, generate dashboards.

Return type:

ScanResult

class Scanner(circuit=None, *, job=None, strategies=None)

Bases: object

Class for analyzing quantum circuits using the Strategy pattern.

This class provides methods for analyzing quantum circuits using various metric strategies.

Initialize a Scanner object.

Parameters:

• circuit (Optional[QuantumCircuit]) – The quantum circuit to analyze

• job (Union[AerJob, Job, None]) – The job that executed the circuit

• strategies (Optional[list]) – Optional list of metric strategy classes or instances. If a class is provided, it will be instantiated with the circuit. If an instance is provided, its circuit must match the Scanner’s circuit.

add(strategy, **kwargs)

Add a metric strategy and return self for fluent chaining.

Parameters:

• strategy – Metric strategy class or instance

• **kwargs – Extra constructor keyword arguments when strategy is a class

Returns:

This scanner instance

Return type:

Scanner

add_strategy(strategy)

Add a metric strategy to the scanner.

Parameters:

strategy – The metric strategy to add

Return type:

None

calculate_metrics()

Calculate metrics using all registered strategies.

Returns:

Dictionary containing DataFrames for each metric type. For CircuitPerformance metrics, returns two DataFrames: - “CircuitPerformance.individual_jobs”: DataFrame containing metrics for each job - “CircuitPerformance.aggregate”: DataFrame containing aggregate metrics across all jobs

Return type:

Dict[str, pd.DataFrame]

property circuit: QuantumCircuit | None

Get the quantum circuit.

Returns:

The quantum circuit

Return type:

Optional[QuantumCircuit]

display_summary(metrics_dict=None)

Display a summary of the calculated metrics.

Parameters:

metrics_dict (Optional[Dict[str, DataFrame]]) – Optional metrics dictionary. If None, will calculate metrics first.

Return type:

None

property job: AerJob | Job | None

Get the job that executed the circuit.

Returns:

The job that executed the circuit

Return type:

Optional[Union[AerJob, QiskitJob]]

scan(include_all_pre_runtime=True)

Calculate metrics and return a ScanResult wrapper.

Parameters:

include_all_pre_runtime (bool) – If True and no strategies are registered, auto-add all pre-runtime strategy classes.

Returns:

Wrapper with fluent helper methods.

Return type:

ScanResult

set_circuit(circuit)

Set the quantum circuit.

Parameters:

circuit (QuantumCircuit) – The quantum circuit

Return type:

None

set_job(job)

Set the job that executed the circuit.

Parameters:

job (Union[AerJob, Job]) – The job that executed the circuit

Return type:

None

property strategies: List[MetricCalculator]

Get the metric strategies.

Returns:

The metric strategies

Return type:

List[MetricCalculator]

class Scanner(circuit=None, *, job=None, strategies=None)

Bases: object

Class for analyzing quantum circuits using the Strategy pattern.

This class provides methods for analyzing quantum circuits using various metric strategies.

Initialize a Scanner object.

Parameters:

• circuit (Optional[QuantumCircuit]) – The quantum circuit to analyze

• job (Union[AerJob, Job, None]) – The job that executed the circuit

• strategies (Optional[list]) – Optional list of metric strategy classes or instances. If a class is provided, it will be instantiated with the circuit. If an instance is provided, its circuit must match the Scanner’s circuit.

add(strategy, **kwargs)

Add a metric strategy and return self for fluent chaining.

Parameters:

• strategy – Metric strategy class or instance

• **kwargs – Extra constructor keyword arguments when strategy is a class

Returns:

This scanner instance

Return type:

Scanner

add_strategy(strategy)

Add a metric strategy to the scanner.

Parameters:

strategy – The metric strategy to add

Return type:

None

calculate_metrics()

Calculate metrics using all registered strategies.

Returns:

Dictionary containing DataFrames for each metric type. For CircuitPerformance metrics, returns two DataFrames: - “CircuitPerformance.individual_jobs”: DataFrame containing metrics for each job - “CircuitPerformance.aggregate”: DataFrame containing aggregate metrics across all jobs

Return type:

Dict[str, pd.DataFrame]

property circuit: QuantumCircuit | None

Get the quantum circuit.

Returns:

The quantum circuit

Return type:

Optional[QuantumCircuit]

display_summary(metrics_dict=None)

Display a summary of the calculated metrics.

Parameters:

metrics_dict (Optional[Dict[str, DataFrame]]) – Optional metrics dictionary. If None, will calculate metrics first.

Return type:

None

property job: AerJob | Job | None

Get the job that executed the circuit.

Returns:

The job that executed the circuit

Return type:

Optional[Union[AerJob, QiskitJob]]

scan(include_all_pre_runtime=True)

Calculate metrics and return a ScanResult wrapper.

Parameters:

include_all_pre_runtime (bool) – If True and no strategies are registered, auto-add all pre-runtime strategy classes.

Returns:

Wrapper with fluent helper methods.

Return type:

ScanResult

set_circuit(circuit)

Set the quantum circuit.

Parameters:

circuit (QuantumCircuit) – The quantum circuit

Return type:

None

set_job(job)

Set the job that executed the circuit.

Parameters:

job (Union[AerJob, Job]) – The job that executed the circuit

Return type:

None

property strategies: List[MetricCalculator]

Get the metric strategies.

Returns:

The metric strategies

Return type:

List[MetricCalculator]