qiskit-waveform-sim

Control-waveform synthesizer and pulse-schedule viewer for Qiskit 2.x

qiskit-waveform-sim bridges the post-Pulse waveform gap in Qiskit. It turns scheduled Qiskit 2.x circuits into sample-level I/Q control waveforms with Virtual-Z frame tracking, and draws them as an interactive pulse sheet. It does not simulate qubit dynamics. It is offline and lazy-evaluated, and 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, using idealized standard pulse shapes (DRAG, GaussianSquare) instead of hardware calibrations.

Features

• Lazy Windowed Evaluation: O(W) memory for snippet extraction, independent of total circuit depth
• 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 compile() when you pass start_times=[...] (see the annotations tutorial)
• Interactive Visualization: Plotly-based Pulse Sheet + synchronized I/Q Oscilloscope
• get_snippet() windowed API (inspired by LabOne Q's OutputSimulator)

Scope and limitations

• It synthesizes the waveforms a controller would play; it does not evolve a qubit Hamiltonian.
• Amplitudes are uncalibrated placeholders, expressed as a fraction of DAC full scale. Override them with PulseDefaults or per-box PulseEnvelopeAnnotation.
• Qiskit's scheduler rejects BoxOp, so pass compile(qc, start_times=[...]) for boxed circuits.
• Roadmap: an optional QuTiP-based dynamics bridge.

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 waveforms
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)

Overriding placeholder amplitudes

from qiskit_waveform_sim import PulseDefaults

defaults = PulseDefaults(sx_amp=0.3, x_amp=0.6)
sim = TargetWaveformSimulator(backend.target, defaults=defaults).compile(scheduled_qc)

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 when you pass 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: Control-waveform synthesizer and pulse-schedule viewer for Qiskit},
  year         = {2026},
  url          = {https://github.com/PratulDeshpande/qiskit-waveform-sim},
  version      = {0.3.0}
}