Unified Visualizer

The Visualizer class is the main entry point for creating visualizations in QWARD. It automatically detects available metric types and orchestrates the appropriate visualization strategies to create comprehensive analysis dashboards.

Key Features: - Automatic Detection: Identifies available metric types and selects appropriate visualizers - Unified Interface: Single class handles all visualization needs - Comprehensive Output: Creates both individual plots and combined dashboards - Flexible Configuration: Supports custom plot configurations and output directories

Supported Metric Types: - QiskitMetrics: Basic circuit properties and instruction analysis - ComplexityMetrics: Multi-dimensional circuit complexity analysis - CircuitPerformanceMetrics: Performance analysis with custom success criteria

Usage Patterns:

Basic Usage:

from qiskit import QuantumCircuit
from qward import Scanner
from qward.metrics import QiskitMetrics, ComplexityMetrics
from qward.visualization import Visualizer

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

scanner = Scanner(circuit=circuit)
scanner.add_strategy(QiskitMetrics(circuit))
scanner.add_strategy(ComplexityMetrics(circuit))
results = scanner.calculate_metrics()

# Create unified visualizations
visualizer = Visualizer(results, output_dir="analysis_plots")

# Generate all visualizations
all_plots = visualizer.create_all_visualizations(save=True, show=False)

Advanced Configuration:

from qward.visualization import Visualizer
from qward.visualization.base import PlotConfig

# Custom plot configuration
config = PlotConfig(
    figsize=(14, 10),
    dpi=200,
    style="quantum",
    color_palette=["#1f77b4", "#ff7f0e", "#2ca02c", "#d62728"],
    save_format="svg",
    grid=True,
    alpha=0.85
)

# Create visualizer with custom configuration
visualizer = Visualizer(
    metrics_dict=results,
    output_dir="custom_plots",
    config=config
)

# Generate customized visualizations
dashboards = visualizer.create_dashboards(save=True, show=False)
individual_plots = visualizer.create_individual_plots(save=True, show=False)

Performance Analysis Example:

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

# 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 success criteria
def bell_state_success(result: str) -> bool:
    return result.replace(" ", "") in ["00", "11"]

# Comprehensive analysis
scanner = Scanner(circuit=circuit, job=job)
scanner.add_strategy(QiskitMetrics(circuit))
scanner.add_strategy(ComplexityMetrics(circuit))
scanner.add_strategy(CircuitPerformanceMetrics(
    circuit=circuit,
    job=job,
    success_criteria=bell_state_success
))
results = scanner.calculate_metrics()

# Create comprehensive visualizations
visualizer = Visualizer(results, output_dir="comprehensive_analysis")

# Generate complete analysis suite
complete_analysis = visualizer.create_all_visualizations(save=True, show=False)

print("Generated visualizations:")
for metric_type, plots in complete_analysis.items():
    print(f"  {metric_type}: {len(plots)} plots")

Main Visualizer Class

Main Visualizer class for QWARD metrics using strategy pattern.

This module provides the unified Visualizer class that acts as the main entry point for visualizing metrics from Scanner or custom data sources using pluggable strategies.

class Visualizer(scanner=None, metrics_data=None, config=None, output_dir='qward/examples/img')[source]

Bases: object

Unified visualizer for QWARD metrics using strategy pattern.

This class provides a single entry point for visualizing metrics from Scanner or custom data sources. It automatically detects available metrics and provides appropriate visualizations using pluggable strategies.

Initialize the Visualizer.

Parameters:

  • scanner (Optional[Scanner]) – Scanner instance containing metrics strategies

  • metrics_data (Optional[Dict[str, DataFrame]]) – Custom metrics data as DataFrames

  • config (Optional[PlotConfig]) – Global plot configuration for all visualizations

  • output_dir (str) – Directory to save plots

Raises:

ValueError – If neither scanner nor metrics_data is provided

create_dashboard(*, save=False, show=False, **kwargs)[source]

Create a comprehensive dashboard with all available metrics.

Parameters:

  • save (bool) – Whether to save the dashboard to files

  • show (bool) – Whether to display the dashboard

  • **kwargs – Additional arguments passed to strategies

Returns:

Dictionary mapping metric names to dashboard figures

Return type:

Dict[str, plt.Figure]

Example

dashboards = visualizer.create_dashboard(save=True, show=True)

generate_plot(*, metric_name, plot_name, save=False, show=False, **kwargs)[source]

Generate a single specific plot.

Parameters:

  • metric_name (str) – Name of the metric (e.g., “CircuitPerformance”, “QiskitMetrics”)

  • plot_name (str) – Name of the plot to generate

  • save (bool) – Whether to save the plot to file

  • show (bool) – Whether to display the plot

  • **kwargs – Additional arguments passed to the plot method

Return type:

Figure

Returns:

matplotlib Figure object

Example

fig = visualizer.generate_plot(

metric_name=”CircuitPerformance”, plot_name=”success_error_comparison”, save=True, show=True

)

generate_plots(*, selections, save=False, show=False, **kwargs)[source]

Generate selected plots for each metric.

Parameters:

  • selections (Dict[str, List[str]]) – Dictionary mapping metric names to lists of plot names. Use None as plot list to generate all plots for a metric.

  • save (bool) – Whether to save the plots to files

  • show (bool) – Whether to display the plots

  • **kwargs – Additional arguments passed to plot methods

Return type:

Dict[str, Dict[str, Figure]]

Returns:

Dictionary mapping metric names to PlotResult dictionaries

Example

results = visualizer.generate_plots(
selections={

“CircuitPerformance”: [“success_error_comparison”, “shot_distribution”], “QiskitMetrics”: [“basic_metrics_bar”]

}, save=True, show=False

)

get_available_metrics()[source]

Get list of available metrics that can be visualized.

Returns:

List of metric names available for visualization

Return type:

List[str]

get_available_plots(metric_name=None)[source]

Get available plots for each metric or specific metric.

Parameters:

metric_name (str) – Optional specific metric name to get plots for

Return type:

Dict[str, List[str]]

Returns:

Dictionary mapping metric names to lists of available plot names

get_metric_summary()[source]

Get a summary of available metrics and their key statistics.

Returns:

Summary information for each metric

Return type:

Dict[str, Dict[str, Any]]

get_plot_metadata(metric_name, plot_name)[source]

Get metadata for a specific plot.

Parameters:

  • metric_name (str) – Name of the metric

  • plot_name (str) – Name of the plot

Return type:

PlotMetadata

Returns:

PlotMetadata object with plot information

list_registered_strategies()[source]

List all registered visualization strategies.

Returns:

Dictionary mapping metric names to strategy class names

Return type:

Dict[str, str]

print_available_metrics()[source]

Print information about available metrics and visualizations.

Return type:

None

register_strategy(metric_name, strategy_class)[source]

Register a visualization strategy for a specific metric.

Parameters:

  • metric_name (str) – Name of the metric (e.g., “QiskitMetrics”, “ComplexityMetrics”)

  • strategy_class (Type[VisualizationStrategy]) – Strategy class that inherits from VisualizationStrategy

Return type:

None

class Visualizer(scanner=None, metrics_data=None, config=None, output_dir='qward/examples/img')[source]

Bases: object

Unified visualizer for QWARD metrics using strategy pattern.

This class provides a single entry point for visualizing metrics from Scanner or custom data sources. It automatically detects available metrics and provides appropriate visualizations using pluggable strategies.

Initialize the Visualizer.

Parameters:

  • scanner (Optional[Scanner]) – Scanner instance containing metrics strategies

  • metrics_data (Optional[Dict[str, DataFrame]]) – Custom metrics data as DataFrames

  • config (Optional[PlotConfig]) – Global plot configuration for all visualizations

  • output_dir (str) – Directory to save plots

Raises:

ValueError – If neither scanner nor metrics_data is provided

create_dashboard(*, save=False, show=False, **kwargs)[source]

Create a comprehensive dashboard with all available metrics.

Parameters:

  • save (bool) – Whether to save the dashboard to files

  • show (bool) – Whether to display the dashboard

  • **kwargs – Additional arguments passed to strategies

Returns:

Dictionary mapping metric names to dashboard figures

Return type:

Dict[str, plt.Figure]

Example

dashboards = visualizer.create_dashboard(save=True, show=True)

generate_plot(*, metric_name, plot_name, save=False, show=False, **kwargs)[source]

Generate a single specific plot.

Parameters:

  • metric_name (str) – Name of the metric (e.g., “CircuitPerformance”, “QiskitMetrics”)

  • plot_name (str) – Name of the plot to generate

  • save (bool) – Whether to save the plot to file

  • show (bool) – Whether to display the plot

  • **kwargs – Additional arguments passed to the plot method

Return type:

Figure

Returns:

matplotlib Figure object

Example

fig = visualizer.generate_plot(

metric_name=”CircuitPerformance”, plot_name=”success_error_comparison”, save=True, show=True

)

generate_plots(*, selections, save=False, show=False, **kwargs)[source]

Generate selected plots for each metric.

Parameters:

  • selections (Dict[str, List[str]]) – Dictionary mapping metric names to lists of plot names. Use None as plot list to generate all plots for a metric.

  • save (bool) – Whether to save the plots to files

  • show (bool) – Whether to display the plots

  • **kwargs – Additional arguments passed to plot methods

Return type:

Dict[str, Dict[str, Figure]]

Returns:

Dictionary mapping metric names to PlotResult dictionaries

Example

results = visualizer.generate_plots(
selections={

“CircuitPerformance”: [“success_error_comparison”, “shot_distribution”], “QiskitMetrics”: [“basic_metrics_bar”]

}, save=True, show=False

)

get_available_metrics()[source]

Get list of available metrics that can be visualized.

Returns:

List of metric names available for visualization

Return type:

List[str]

get_available_plots(metric_name=None)[source]

Get available plots for each metric or specific metric.

Parameters:

metric_name (str) – Optional specific metric name to get plots for

Return type:

Dict[str, List[str]]

Returns:

Dictionary mapping metric names to lists of available plot names

get_metric_summary()[source]

Get a summary of available metrics and their key statistics.

Returns:

Summary information for each metric

Return type:

Dict[str, Dict[str, Any]]

get_plot_metadata(metric_name, plot_name)[source]

Get metadata for a specific plot.

Parameters:

  • metric_name (str) – Name of the metric

  • plot_name (str) – Name of the plot

Return type:

PlotMetadata

Returns:

PlotMetadata object with plot information

list_registered_strategies()[source]

List all registered visualization strategies.

Returns:

Dictionary mapping metric names to strategy class names

Return type:

Dict[str, str]

print_available_metrics()[source]

Print information about available metrics and visualizations.

Return type:

None

register_strategy(metric_name, strategy_class)[source]

Register a visualization strategy for a specific metric.

Parameters:

  • metric_name (str) – Name of the metric (e.g., “QiskitMetrics”, “ComplexityMetrics”)

  • strategy_class (Type[VisualizationStrategy]) – Strategy class that inherits from VisualizationStrategy

Return type:

None