qiskit-waveform-sim

Classical Control Waveform Simulator & Interactive Pulse Sheet Viewer

qiskit-waveform-sim bridges the post-Pulse waveform gap in Qiskit by providing a native, offline, lazy-evaluated waveform simulator that works directly with Qiskit's modern Target, op_start_times, BoxOp, fractional gates (RX, RZZ), and the new qiskit.circuit.annotation.Annotation API.

Overview

With the deprecation and removal of qiskit.pulse in Qiskit 2.0, users need a way to inspect scheduled waveforms. This package provides an analytical envelope generator that synthesizes waveforms directly from instruction durations and gate names, overriding hardware calibrations with idealized standard physics (DRAG, GaussianSquare).

Features

• Lazy Windowed Evaluation: O(W) memory for snippet extraction, independent of total circuit depth
• Exact Virtual-Z Frame Tracking: Per-qubit phase accumulation propagated to drive and cross-resonance channels
• Analytical Envelope Synthesis: DRAG (with leakage suppression), GaussianSquare (flat-top with pedestal correction)
• Fractional Gate Support: Amplitude scaling for RX(θ), RZZ(θ) (angles wrapped to [-π, π]; over-range amplitudes are clipped with a warning)
• BoxOp & Annotation Native: Custom PulseEnvelopeAnnotation with OpenQASM 3 & QPY serialization, applied by the simulator whenever the circuit carries start times
• Interactive Visualization: Plotly-based Pulse Sheet + synchronized I/Q Oscilloscope
• LabOne Q-style Architecture: OutputSimulator.get_snippet()-style API

Installation

pip install qiskit-waveform-sim

For development:

git clone https://github.com/PratulDeshpande/qiskit-waveform-sim
cd qiskit-waveform-sim
pip install -e ".[dev,test,docs]"

Requires Python 3.11+ and Qiskit 2.5+.

Quickstart

from qiskit import QuantumCircuit
from qiskit.providers.fake_provider import GenericBackendV2
from qiskit.transpiler import generate_preset_pass_manager
from qiskit_waveform_sim import TargetWaveformSimulator

# 1. Create backend and circuit
backend = GenericBackendV2(num_qubits=2, seed=42)

qc = QuantumCircuit(2, 2)
qc.h(0)                    # Decomposes to rz(π/2) → sx → rz(π/2)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

# 2. Transpile & schedule (ALAP)
pm = generate_preset_pass_manager(optimization_level=1, backend=backend, scheduling_method="alap")
scheduled_qc = pm.run(qc)

# 3. Compile waveform simulator
sim = TargetWaveformSimulator(backend.target).compile(scheduled_qc)

# 4. Extract sample-precise I/Q snippets (lazy, windowed)
d0_snip = sim.get_snippet("d0", start_dt=0, length_dt=2500)
cr_snip = sim.get_snippet("u(0,1)", start_dt=0, length_dt=2500)

# 5. Plot interactive Pulse Sheet + I/Q Oscilloscope
from qiskit_waveform_sim.visualization import show_pulse_sheet, show_iq_oscilloscope
show_pulse_sheet(sim, interactive=True)
show_iq_oscilloscope(sim, "d0", start_dt=0, length_dt=1000, interactive=True)

Custom Pulse Annotations (Unscheduled Preview)

For custom pulse shapes, use BoxOp with PulseEnvelopeAnnotation. Note: Qiskit's preset scheduling passes do not yet accept circuits that contain BoxOp, so boxed circuits cannot be scheduled with scheduling_method="alap". The annotations serialize to OpenQASM 3 and QPY today, and TargetWaveformSimulator.compile() applies them to any circuit that carries start times (see the annotations tutorial).

from qiskit_waveform_sim import PulseEnvelopeAnnotation, PulseAnnotationSerializer
from qiskit import qasm3

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)

# Custom high-beta DRAG for SX gate
with qc.box(
    duration=160,
    unit="dt",
    annotations=[PulseEnvelopeAnnotation(shape="drag", amp=0.55, beta=0.25, sigma_ratio=0.2)]
):
    qc.sx(0)

qc.measure([0, 1], [0, 1])

# Export to OpenQASM 3 with pulse annotations (works without scheduling)
qasm3_str = qasm3.dumps(
    qc, annotation_handlers={"pulse_sim.envelope": PulseAnnotationSerializer()}
)
print(qasm3_str)

Architecture

Input: Scheduled QuantumCircuit + Target

Pillar 1: Target Parametric Binding

• sx/x → DRAG envelope (σ = D/4, β leakage suppression)
• rx(θ) → DRAG with A(θ) = A_π · (θ/π)
• ecr/cx/rzz → GaussianSquare cross-resonance pulses on ControlChannel u(c,t)
• cz → uncalibrated flat-top stand-in on u(c,t)
• measure → GaussianSquare on MeasureChannel m{q}
• other gates that take time but have no model → a UserWarning

Pillar 2: PulseAnnotation Override (OpenQASM 3 + QPY)

• @pulse_sim.envelope {'shape': 'drag', 'amp': 0.5, 'beta': 0.1, 'sigma_ratio': 0.25, 'risefall_dt': 16}
• box[160dt] { sx q[0]; }

Engine: FrameTracker + AnalyticalEnvelopes + Interval Indexing

• Virtual-Z: φ_q(t⁺) = φ_q(t⁻) - λ
• CR phase-locked to target qubit frame φ_t
• I(t) + iQ(t) = Ω_env(t) · e^{i(2πf_IF t + φ_q)}
• Binary search over ChannelEvent start_dt (O(log N))

Output: WaveformSnippet(channel, time_ns, wave=I+iQ, phase) Visualization: Pulse Sheet (Plotly/HTML) + I/Q Oscilloscope

Documentation

• Quickstart Tutorial
• Custom Pulse Annotations & OpenQASM 3 Export
• LabOne Q / RFSoC Integration
• API Reference

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch
3. Run tests: pytest -v
4. Run linters: ruff check qiskit_waveform_sim tests examples && black --check qiskit_waveform_sim tests examples && mypy qiskit_waveform_sim
5. Submit a PR

License

Apache License 2.0 — see LICENSE for details.

Citation

If you use qiskit-waveform-sim in your research, please cite:

@software{qiskit_waveform_sim,
  author       = {Pratul Deshpande},
  title        = {qiskit-waveform-sim: Classical Control Waveform Simulator},
  year         = {2026},
  url          = {https://github.com/PratulDeshpande/qiskit-waveform-sim},
  version      = {0.2.0}
}