Annotations API Reference

PulseEnvelopeAnnotation

class qiskit_waveform_sim.annotations.PulseEnvelopeAnnotation(shape: str = 'drag', amp: float = 0.5, beta: float = 0.08, sigma_ratio: float = 0.25, risefall_dt: int = 16)

Bases: Annotation

Custom Qiskit 2.x Annotation attaching parametric pulse specs to a BoxOp.

This annotation can be attached to a qc.box() context to override the default pulse envelope for gates within that box. It implements OpenQASM3Serializer for round-trip serialization via qiskit.qasm3.dumps() and qiskit.qpy.dump().

Examples

>>> from qiskit import QuantumCircuit
>>> from qiskit_waveform_sim import PulseEnvelopeAnnotation
>>>
>>> qc = QuantumCircuit(1)
>>> with qc.box(duration=160, unit="dt",
...             annotations=[PulseEnvelopeAnnotation(shape="drag", amp=0.55, beta=0.25)]):
...     qc.sx(0)

QPY Round-trip Example >>> from qiskit import qpy >>> from qiskit_waveform_sim import PulseAnnotationSerializer >>> import io >>> >>> qc = QuantumCircuit(1) >>> with qc.box(duration=160, unit=”dt”, … annotations=[PulseEnvelopeAnnotation(shape=”drag”, amp=0.55, beta=0.25)]): … qc.sx(0) >>> >>> serializer = PulseAnnotationSerializer() >>> buf = io.BytesIO() >>> qpy.dump(qc, buf, annotation_factories={“pulse_sim.envelope”: serializer.as_qpy()}) >>> buf.seek(0) >>> loaded = qpy.load(buf, annotation_factories={“pulse_sim.envelope”: serializer.as_qpy()})[0]

__init__(shape: str = 'drag', amp: float = 0.5, beta: float = 0.08, sigma_ratio: float = 0.25, risefall_dt: int = 16)

Initialize pulse envelope annotation.

Parameters:

• shape (str) – Pulse shape: “drag” or “gaussian_square”

• amp (float) – Peak amplitude (normalized, 0.0-1.0)

• beta (float) – DRAG leakage suppression parameter (for drag shape)

• sigma_ratio (float) – Gaussian sigma as ratio of pulse duration (for drag shape)

• risefall_dt (int) – Rise/fall duration in dt (for gaussian_square shape)

classmethod from_dict(data: dict[str, Any]) → PulseEnvelopeAnnotation

Deserialize from dictionary (QPY).

namespace = 'pulse_sim.envelope'

to_dict() → dict[str, Any]

Serialize to dictionary for QPY.

PulseAnnotationSerializer

class qiskit_waveform_sim.annotations.PulseAnnotationSerializer

Bases: OpenQASM3Serializer

Serializes PulseEnvelopeAnnotation to/from OpenQASM 3 and QPY.

OpenQASM 3 Export Format:

@pulse_sim.drag(amp=0.5, beta=0.08, sigma_ratio=0.25, risefall_dt=16)
box {
    sx q[0];
}

QPY Serialization:

Uses the standard QPY annotation mechanism with namespace "pulse_sim.envelope"
via the `as_qpy()` method. Example:

>>> from qiskit import qpy
>>> from qiskit_waveform_sim import PulseAnnotationSerializer
>>> import io
>>>
>>> serializer = PulseAnnotationSerializer()
>>> buf = io.BytesIO()
>>> qpy.dump(qc, buf, annotation_factories={"pulse_sim.envelope": serializer.as_qpy()})
>>> buf.seek(0)
>>> loaded = qpy.load(buf, annotation_factories={"pulse_sim.envelope": serializer.as_qpy()})[0]

dump(annotation: Annotation) → str

Serialize annotation to OpenQASM 3 pragma string.

Returns NotImplemented if namespace doesn’t match.

load(namespace: str, payload: str) → Annotation

Deserialize annotation from OpenQASM 3 pragma string.

Returns NotImplemented if namespace doesn’t match.