Visualization API Reference

Interactive (Plotly)

qiskit_waveform_sim.visualization.create_pulse_sheet(sim: TargetWaveformSimulator, config: PulseSheetConfig | None = None) → Figure[source]

Create an interactive Plotly Pulse Sheet (multi-channel schedule view).

This is the primary visualization showing the logical timing structure across all channels, similar to LabOne Q’s pulse sheet.

Parameters:

sim (TargetWaveformSimulator) – Compiled waveform simulator
config (PulseSheetConfig, optional) – Visualization configuration

Returns:

Interactive Plotly figure with pulse sheet

Return type:

go.Figure

qiskit_waveform_sim.visualization.create_iq_oscilloscope(sim: TargetWaveformSimulator, channel: str, start_dt: int = 0, length_dt: int | None = None, show_phase: bool = True) → Figure[source]

Create an interactive I/Q Oscilloscope for a specific channel and time window.

This provides sample-precise waveform visualization with phase tracking, similar to LabOne Q’s Signal tab when clicking a pulse.

Parameters:

sim (TargetWaveformSimulator) – Compiled waveform simulator
channel (str) – Channel to display (e.g., “d0”, “u(0,1)”, “m0”)
start_dt (int) – Start time in dt units
length_dt (int, optional) – Window length in dt units
show_phase (bool) – Whether to show phase trace

Returns:

Interactive Plotly figure with I/Q waveforms

Return type:

go.Figure

qiskit_waveform_sim.visualization.show_pulse_sheet(sim: TargetWaveformSimulator, interactive: bool = True, config: PulseSheetConfig | None = None) → Figure | None[source]

Display the interactive pulse sheet in browser/notebook.

Parameters:

sim (TargetWaveformSimulator) – Compiled waveform simulator
interactive (bool) – If True, opens in browser; if False, returns figure for notebook display
config (PulseSheetConfig, optional) – Visualization configuration

Returns:

Returns the figure when interactive=False, otherwise None

Return type:

go.Figure or None

qiskit_waveform_sim.visualization.show_iq_oscilloscope(sim: TargetWaveformSimulator, channel: str, start_dt: int = 0, length_dt: int | None = None, interactive: bool = True) → Figure | None[source]

Display the I/Q oscilloscope for a channel.

Parameters:

sim (TargetWaveformSimulator) – Compiled waveform simulator
channel (str) – Channel to display
start_dt (int) – Start time in dt
length_dt (int, optional) – Window length in dt
interactive (bool) – If True, opens in browser; if False, returns figure

Returns:

Returns the figure when interactive=False, otherwise None

Return type:

go.Figure or None

qiskit_waveform_sim.visualization.create_combined_view(sim: TargetWaveformSimulator, channel: str, start_dt: int = 0, length_dt: int | None = None, config: PulseSheetConfig | None = None) → Figure[source]

Create a combined view with Pulse Sheet (top) and I/Q Oscilloscope (bottom).

Synchronized x-axis for coordinated exploration.

Parameters:

sim (TargetWaveformSimulator) – Compiled waveform simulator
channel (str) – Channel for I/Q detail view
start_dt (int) – Start time in dt
length_dt (int, optional) – Window length in dt
config (PulseSheetConfig, optional) – Configuration for pulse sheet

Returns:

Combined interactive figure

Return type:

go.Figure

class qiskit_waveform_sim.visualization.PulseSheetConfig(height_per_channel: int = 60, min_channel_height: int = 40, max_channels: int = 20, time_window_ns: tuple[float, float] | None = None, show_phase_markers: bool = True, show_annotations: bool = True, theme: str = 'plotly_white')[source]

Bases: object

Configuration for pulse sheet visualization.

height_per_channel: int = 60

max_channels: int = 20

min_channel_height: int = 40

show_annotations: bool = True

show_phase_markers: bool = True

theme: str = 'plotly_white'

time_window_ns: tuple[float, float] | None = None

Static (Matplotlib)

qiskit_waveform_sim.visualization.plot_pulse_sheet(sim: TargetWaveformSimulator, ax: Axes | None = None, channels: list[str] | None = None, time_range_ns: tuple[float, float] | None = None, figsize: tuple[float, float] = (12, 6), show_phase_markers: bool = True) → Figure[source]

Create a static Matplotlib pulse sheet (multi-channel schedule view).

Parameters:

sim (TargetWaveformSimulator) – Compiled waveform simulator
ax (plt.Axes, optional) – Existing axes to plot on
channels (List[str], optional) – Channels to display (default: all)
time_range_ns (Tuple[float, float], optional) – Time window in ns (default: full circuit)
figsize (Tuple[float, float]) – Figure size if creating new figure
show_phase_markers (bool) – Show virtual Z phase markers

Returns:

Matplotlib figure

Return type:

Figure

qiskit_waveform_sim.visualization.plot_iq_waveforms(snippet: WaveformSnippet, ax: Axes | None = None, figsize: tuple[float, float] = (12, 5), show_envelope: bool = True, show_phase: bool = True, show_events: bool = True) → Figure[source]

Plot I/Q waveforms from a WaveformSnippet.

Parameters:

snippet (WaveformSnippet) – Waveform snippet from TargetWaveformSimulator.get_snippet()
ax (plt.Axes or array of Axes, optional) – Existing axes (2 or 3 axes for I/Q/Phase)
figsize (Tuple[float, float]) – Figure size if creating new figure
show_envelope (bool) – Show magnitude envelope
show_phase (bool) – Show phase trace
show_events (bool) – Show event boundaries

Returns:

Matplotlib figure

Return type:

Figure

qiskit_waveform_sim.visualization.plot_multi_channel_iq(sim: TargetWaveformSimulator, channels: list[str], start_dt: int = 0, length_dt: int | None = None, figsize: tuple[float, float] = (14, 8)) → Figure[source]

Plot I/Q waveforms for multiple channels in a grid.

Parameters:

sim (TargetWaveformSimulator) – Compiled waveform simulator
channels (List[str]) – Channels to plot
start_dt (int) – Start time in dt
length_dt (int, optional) – Window length in dt
figsize (Tuple[float, float]) – Figure size

Returns:

Matplotlib figure with subplots

Return type:

Figure

qiskit_waveform_sim.visualization.plot_phase_tracking(sim: TargetWaveformSimulator, qubits: list[int] | None = None, ax: Axes | None = None, figsize: tuple[float, float] = (12, 4)) → Figure[source]

Plot Virtual-Z frame phase accumulation over time for qubits.

Parameters:

sim (TargetWaveformSimulator) – Compiled waveform simulator
qubits (List[int], optional) – Qubits to plot (default: all)
ax (plt.Axes, optional) – Existing axes
figsize (Tuple[float, float]) – Figure size if creating new figure

Returns:

Matplotlib figure

Return type:

Figure

Export Utilities

qiskit_waveform_sim.visualization.export_html(fig: Figure, filename: str) → None[source]: Export figure to standalone HTML file.

qiskit_waveform_sim.visualization.export_static(fig: Figure, filename: str, format: str = 'png') → None[source]: Export figure to static image (requires kaleido).