Interactive circuit visualization with Plotly

[yitchen-tim]

Description

Add a new interactive circuit diagram renderer powered by Plotly, as a sibling to the existing Matplotlib renderer. Both are subclasses of GraphicalCircuitDiagram. This builds on the work in #1239 by offering an interactive alternative -- hovering over gates displays metadata like fidelities and parameters, and subcircuits can be expanded or collapsed.

Motivation

The existing MatplotlibCircuitDiagram produces static images, which is great for papers and docs. But for users working in Jupyter notebooks or web-based environments, an interactive visualization would be significantly more useful:

• Hover tooltips showing gate fidelities, error rates, or gate parameters
• Expandable/collapsible subcircuits to manage visual complexity of large circuits
• Zoom and pan for large circuits
• Dynamic filtering (e.g., highlight a specific qubit's path through the circuit)

The Matplotlib renderer remains unchanged and fully supported. This is a parallel option, not a replacement.

Success Criteria

The following must all be met for this bounty to be considered complete:

1. New PlotlyCircuitDiagram subclass -- Implement a PlotlyCircuitDiagram class under src/braket/circuits/graphical_diagram_builders/ that subclasses GraphicalCircuitDiagram and renders a Circuit as an interactive Plotly figure.

2. Feature parity with Matplotlib renderer -- The Plotly renderer must support the same gate set and circuit structures as MatplotlibCircuitDiagram (single-qubit gates, multi-qubit gates, verbatim blocks, result types, etc.).

3. Hover interactivity -- Each gate element in the rendered figure must display a tooltip on hover containing at minimum:

   • Gate name
   • Target qubit(s)
   • Gate parameters (if any, e.g., rotation angles)
   • A placeholder or hook for device-specific metadata (e.g., fidelity) that can be populated when device properties are available

4. Expandable/collapsible verbatim boxes -- Today, the BDK does not expose general circuit sub-structures (like box or scope) except for verbatim boxes. The Plotly renderer must:

   • Render a verbatim box as a single collapsed block by default, labeled as verbatim
   • Allow the user to click the block to expand it inline, revealing the individual gates within
   • Allow collapsing it back to the summary block

   The implementation should be written with extensibility in mind so the same expand/collapse mechanism can be reused when the BDK later supports broader sub-structure features (box, scope, nested subroutines, etc.). A short note in the code or docs describing the extension path is sufficient; no stub implementation for unsupported structures is required.

5. Integration with Circuit API -- Users can invoke the Plotly diagram via a method on Circuit, e.g.:

   circuit.show("interactive")  # returns a plotly.graph_objects.Figure

   The existing circuit.show() (Matplotlib) must remain unchanged.

6. Jupyter rendering -- The figure renders inline in Jupyter notebooks without extra configuration.

7. Tests -- Unit tests covering:

   • Correct rendering of single-qubit, multi-qubit, and parameterized gates
   • Tooltip content accuracy
   • Subcircuit expand/collapse behavior (collapsed state shows label, expanded state shows inner gates)
   • Edge cases (empty circuit, large circuits, circuits with verbatim blocks, deeply nested subcircuits)

8. Documentation -- A short usage example in the docstring or a notebook showing how to use the interactive visualization, including the subcircuit expand/collapse feature.

Architecture

GraphicalCircuitDiagram (base class)
├── MatplotlibCircuitDiagram   (existing, unchanged)
└── PlotlyCircuitDiagram       (new, this issue)

Technical Pointers

• Existing graphical diagram code lives in src/braket/circuits/graphical_diagram_builders/
• GraphicalCircuitDiagram is the base class; MatplotlibCircuitDiagram is the current implementation
• The Circuit class is in src/braket/circuits/circuit.py
• Subcircuits are added via circuit.add_circuit()
• Plotly should be an optional dependency (guarded import, listed in an extras group like pip install amazon-braket-sdk[interactive])
• For expand/collapse, consider using Plotly's updatemenus or custom click callbacks, or a Dash-based approach if pure Plotly is too limiting

References

• PR feature: graphical visualizations for circuits #1239 -- Matplotlib circuit diagram implementation
• Plotly Python documentation

uH 2026

Please note that we're still waiting for Unitary Foundation to review and approve our issues, so these are subject to change.