Core API Reference

TargetWaveformSimulator

class qiskit_waveform_sim.core.TargetWaveformSimulator(target: Target, if_freq_hz: float = 0.0)[source]

Bases: object

LabOne Q OutputSimulator equivalent for Qiskit 2.0+ scheduled circuits.

Tracks Virtual-Z phase accumulation per qubit and synthesizes I/Q waveforms lazily on-demand via windowed snippet extraction.

Memory complexity: O(N_events) for compilation, O(W) for snippet extraction, where W is the requested window length in dt.

Example

>>> backend = GenericBackendV2(num_qubits=2)
>>> qc = QuantumCircuit(2)
>>> qc.h(0); qc.cx(0, 1); qc.measure_all()
>>> pm = generate_preset_pass_manager(backend=backend, scheduling_method="alap")
>>> scheduled_qc = pm.run(qc)
>>> sim = TargetWaveformSimulator(backend.target).compile(scheduled_qc)
>>> snippet = sim.get_snippet("d0", start_dt=0, length_dt=1000)
>>> print(snippet.wave.shape)  # (1000,) complex array

__init__(target: Target, if_freq_hz: float = 0.0)[source]

Initialize simulator with backend target.

Parameters:

target (Target) – Qiskit 2.x Target containing instruction durations and properties
if_freq_hz (float, optional) – Intermediate frequency for digital upconversion (Hz). 0.0 = baseband, non-zero = NCO modulation prior to DAC.

compile(scheduled_qc: QuantumCircuit) → TargetWaveformSimulator[source]

Compile a scheduled circuit into channel events with frame tracking.

Parameters:: scheduled_qc (QuantumCircuit) – Circuit with op_start_times populated (via scheduling pass)
Returns:: Self, for method chaining
Return type:: TargetWaveformSimulator

export_openqasm3(scheduled_qc: QuantumCircuit, annotation_handlers: dict | None = None) → str[source]

Export scheduled circuit to OpenQASM 3 with serialized pulse annotations.

Parameters:

scheduled_qc (QuantumCircuit) – Scheduled circuit to export
annotation_handlers (dict, optional) – Custom annotation serializers. Defaults to including PulseAnnotationSerializer for the “pulse_sim.envelope” namespace. e.g., {“pulse_sim.envelope”: PulseAnnotationSerializer()}

Returns:

OpenQASM 3 string with pulse annotation pragmas

Return type:

str

get_channels() → list[str][source]: Return list of all channels with events.

get_phase_history(qubit: int) → list[tuple[int, float]][source]: Return phase history for a qubit as list of (dt, phase_rad).

get_snippet(channel: str, start_dt: int = 0, length_dt: int | None = None) → WaveformSnippet[source]

Synthesize the complex I(t) + 1j*Q(t) waveform strictly within [start_dt, start_dt + length_dt].

Memory complexity is O(length_dt), independent of total circuit depth. Uses binary search to find only overlapping events.

Parameters:

channel (str) – Channel identifier (e.g., “d0”, “u(0,1)”, “m0”)
start_dt (int) – Start time in dt units
length_dt (int, optional) – Window length in dt. Defaults to remaining circuit duration.

Returns:

Container with time array, complex waveform, phase trace, and overlapping events

Return type:

WaveformSnippet

WaveformSnippet

class qiskit_waveform_sim.core.WaveformSnippet(channel: str, start_dt: int, dt_sec: float, time_ns: ndarray, wave: ndarray, phase_rad: ndarray, events: list[ChannelEvent] = <factory>)[source]

Bases: object

LabOne Q OutputSimulator-style snippet container.

Contains the synthesized complex waveform for a specific time window on a specific channel, along with metadata for visualization.

channel: str

dt_sec: float

events: list[ChannelEvent]

phase_rad: ndarray

start_dt: int

time_ns: ndarray

wave: ndarray

ChannelEvent

class qiskit_waveform_sim.core.ChannelEvent(channel: str, start_dt: int, duration_dt: int, op_name: str, qubits: tuple[int, ...], frame_phase_rad: float, shape: str, amp: complex, beta: float = 0.0, sigma_dt: float = 16.0, risefall_dt: int = 16)[source]

Bases: object

Lightweight event record representing a scheduled hardware pulse or phase shift.

Memory footprint ~64 bytes per gate, enabling compilation of large circuits without sample array allocation.

amp: complex

beta: float = 0.0

channel: str

duration_dt: int

frame_phase_rad: float

op_name: str

qubits: tuple[int, ...]

risefall_dt: int = 16

shape: str

sigma_dt: float = 16.0

start_dt: int

AnalyticalEnvelopes

class qiskit_waveform_sim.core.AnalyticalEnvelopes[source]

Bases: object

Vectorized NumPy evaluators for physical microwave pulse envelopes.

All methods are static and operate on time arrays in dt units, returning complex baseband envelopes.

static drag(t_dt: ndarray, duration_dt: int, amp: complex, sigma_dt: float, beta: float) → ndarray[source]

DRAG (Derivative Removal by Adiabatic Gate) envelope with pedestal correction.

The Q quadrature is windowed by the normalized Gaussian to ensure zero boundary conditions on both I and Q components.

Parameters:

t_dt (np.ndarray) – Time points in dt units, relative to pulse start
duration_dt (int) – Total pulse duration in dt
amp (complex) – Complex amplitude (magnitude = peak Rabi rate, phase = drive phase)
sigma_dt (float) – Gaussian standard deviation in dt units
beta (float) – DRAG leakage suppression parameter (typically 0.05-0.15)

Returns:

Complex baseband envelope Ω(t) = A[g_norm(t) - iβ d(g_norm)/dt] with zero boundary conditions on both real and imaginary parts. The Q quadrature is -β times the derivative of the I quadrature envelope.

Return type:

np.ndarray

static gaussian_square(t_dt: ndarray, duration_dt: int, amp: complex, risefall_dt: int) → ndarray[source]

GaussianSquare (flat-top with Gaussian rise/fall) envelope with pedestal correction.

Parameters:

t_dt (np.ndarray) – Time points in dt units, relative to pulse start
duration_dt (int) – Total pulse duration in dt
amp (complex) – Complex amplitude
risefall_dt (int) – Rise/fall duration in dt (each edge)

Returns:

Real-valued envelope (0 to 1) scaled by amplitude

Return type:

np.ndarray