qiskit-waveform-sim 0.1.1__tar.gz

qiskit_waveform_sim-0.1.1/LICENSE

@@ -0,0 +1,159 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting this License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) the power, direct or indirect, to cause
+the direction or management of such entity, whether by contract or
+otherwise, or (iv) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) the power, direct or indirect, to cause
+the direction or management of such entity, whether by contract or
+otherwise, or (iv) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) the power, direct or indirect, to cause
+the direction or management of such entity, whether by contract or
+otherwise, or (iv) ownership of fifty percent (50%) or more of the
+outstanding shares.
+
+"Work" shall mean the work of authorship, whether in digital or
+analog form, that is the subject of the copyright license granted
+herein.
+
+"Derivative Works" shall mean any work, whether in digital or analog
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+substantially the same as the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent
+an original work of authorship.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by any individual or entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, system bulletin boards,
+regular mail, or telephone communication that the Licensor or its
+representatives have explicitly agreed to receive.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Licensor hereby grants to you a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Licensor hereby grants to you a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(patent) license to make, have made, use, offer to sell, sell,
+import, and otherwise transfer the Work, where such license applies
+only to those patent claims licensable by such Licensor that are
+necessarily infringed by the Contribution alone or by combination
+of the Contribution with the Work; provided, however, that this
+patent license shall not apply to any patent claims that are
+infringed by Derivative Works other than the Work, or that are
+infringed by Contributions other than the Contribution.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works of the Work in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Derivative Works, all copyright,
+patent, trademark, and attribution notices from the Source form of
+the Work, excluding those notices that do not remain on the
+Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that you distribute must
+include a readable copy of the NOTICE file as part of its
+distribution, unless the Licensor has explicitly waived this requirement
+in writing.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution submitted to the Licensor for inclusion in the
+Work by You shall be treated as a Contribution under the terms of this
+License, without any additional terms or conditions. Notwithstanding
+the above, nothing herein shall supersede or modify the terms of any
+separate license agreement you may have with the Licensor regarding
+such Contribution.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as necessary for reasonable and customary use in describing the
+origin of the Work and distributing the Derivative Works.
+
+7. Disclaimer of Warranty. Unless required by applicable law, the
+Work is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
+OF ANY KIND, either express or implied, including, without limitation,
+warranties of merchantability, fitness for a particular purpose,
+and non-infringement. In no event shall the Licensor be liable for any
+claim, damages, or other losses arising out of or in connection with
+the use of the Work, including without limitation, special, incidental,
+or consequential damages, except as required by applicable law.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law, the Licensor shall not be liable
+for any direct, indirect, incidental, special, exemplary, or
+consequential damages (including lost profits, lost data, or loss of
+business opportunity) arising out of or related to the use of the
+Work, even if the Licensor has been advised of the possibility of
+such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works of the Work, You may choose to offer,
+and charge a fee for, acceptance of Warranty or Additional Liability
+associated with the use of the Work, but only if such acceptance
+does not violate the terms of this License.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be printed in the next-to-last
+line of the first page of the document (using the regular font)
+and if the document is used on a regular page, the text should be
+centered.
+
+Copyright [2026] [Qiskit Community]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

qiskit_waveform_sim-0.1.1/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: qiskit-waveform-sim
+Version: 0.1.1
+Summary: Zero-bloat Classical Control Waveform Simulator & Interactive Pulse Sheet Viewer for Qiskit 2.5+
+Author-email: Qiskit Community <qiskit@us.ibm.com>
+Maintainer-email: Qiskit Waveform Sim Team <qiskit-waveform-sim@example.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Qiskit/qiskit-waveform-sim
+Project-URL: Repository, https://github.com/Qiskit/qiskit-waveform-sim
+Project-URL: Documentation, https://qiskit-waveform-sim.readthedocs.io
+Project-URL: Changelog, https://github.com/Qiskit/qiskit-waveform-sim/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Qiskit/qiskit-waveform-sim/issues
+Keywords: qiskit,quantum-computing,waveform-simulation,pulse-sheet,quantum-control,ibm-quantum
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: qiskit>=2.0.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: plotly>=5.18
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-cov>=4.1; extra == "test"
+Requires-Dist: pytest-xdist>=3.3; extra == "test"
+Requires-Dist: hypothesis>=6.8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Requires-Dist: nbsphinx>=0.9; extra == "docs"
+Requires-Dist: jupyter>=1.0; extra == "docs"
+Requires-Dist: ipykernel>=6.0; extra == "docs"
+Provides-Extra: export
+Requires-Dist: kaleido>=0.2; extra == "export"
+Requires-Dist: h5py>=3.0; extra == "export"
+Dynamic: license-file
+
+# qiskit-waveform-sim
+
+[![PyPI](https://img.shields.io/pypi/v/qiskit-waveform-sim.svg)](https://pypi.org/project/qiskit-waveform-sim/)
+[![Python](https://img.shields.io/pypi/pyversions/qiskit-waveform-sim.svg)](https://pypi.org/project/qiskit-waveform-sim/)
+[![License](https://img.shields.io/pypi/l/qiskit-waveform-sim.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Tests](https://github.com/Qiskit/qiskit-waveform-sim/workflows/Tests/badge.svg)](https://github.com/Qiskit/qiskit-waveform-sim/actions)
+
+**Zero-bloat Classical Control Waveform Simulator & Interactive Pulse Sheet Viewer for Qiskit 2.5+**
+
+`qiskit-waveform-sim` bridges the post-Pulse waveform gap in Qiskit 2.5+ 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.
+
+---
+
+## The Problem
+
+With Qiskit 2.0–2.5, IBM completed a major architectural overhaul:
+- Core circuit structures moved to Rust (`QkCircuit`, `QkTarget`)
+- `qiskit.pulse` module was deprecated and removed
+- `qiskit-dynamics` was archived (Oct 31, 2025)
+
+This created a **structural visibility gap**:
+| Tool | Offline? | Dynamic Circuits | Fractional Gates | Virtual-Z Tracking | Sample-Precise I/Q |
+|------|----------|------------------|------------------|--------------------|---------------------|
+| `qiskit.visualization.timeline` | ✅ | ❌ | ❌ | ❌ (markers only) | ❌ |
+| `qiskit-ibm-runtime` `CircuitSchedule` | ❌ (cloud only) | ✅ (server) | ❌ | ❌ | ❌ |
+| **qiskit-waveform-sim** | ✅ | ✅ | ✅ | ✅ Exact | ✅ Lazy/Windowed |
+
+---
+
+## 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**: Continuous parametric amplitude/duration scaling for `RX(θ)`, `RZZ(θ)`
+- **BoxOp & Annotation Native**: Custom `PulseEnvelopeAnnotation` with OpenQASM 3 & QPY serialization
+- **Interactive Visualization**: Plotly-based Pulse Sheet + synchronized I/Q Oscilloscope
+- **LabOne Q Compatible Architecture**: `OutputSimulator.get_snippet()`-style API
+
+---
+
+## Installation
+
+```bash
+pip install qiskit-waveform-sim
+```
+
+For development:
+```bash
+git clone https://github.com/Qiskit/qiskit-waveform-sim
+cd qiskit-waveform-sim
+pip install -e ".[dev,test,docs]"
+```
+
+Requires Python 3.11+ and Qiskit 2.0+.
+
+---
+
+## Quickstart
+
+```python
+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: scheduling with `BoxOp` is not yet supported in Qiskit 2.5's transpiler. Use the unscheduled circuit for OpenQASM 3 export and manual waveform compilation.
+
+```python
+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
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    qiskit-waveform-sim                          │
+├─────────────────────────────────────────────────────────────────┤
+│  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 on ControlChannel          │  │
+│  │ • measure → GaussianSquare on MeasureChannel + Acquire   │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│  Pillar 2: PulseAnnotation Override (OpenQASM3 + QPY)          │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │ @pulse_sim.drag(amp=0.5, beta=0.1, σ_ratio=0.25)         │  │
+│  │ box { 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](https://qiskit-waveform-sim.readthedocs.io/en/latest/tutorials/quickstart.html)
+- [Custom Pulse Annotations & OpenQASM 3 Export](https://qiskit-waveform-sim.readthedocs.io/en/latest/tutorials/annotations.html)
+- [LabOne Q / RFSoC Integration](https://qiskit-waveform-sim.readthedocs.io/en/latest/tutorials/hardware_export.html)
+- [API Reference](https://qiskit-waveform-sim.readthedocs.io/en/latest/api.html)
+
+---
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+1. Fork the repository
+2. Create a feature branch
+3. Run tests: `pytest -v`
+4. Run linters: `ruff check . && black --check . && mypy .`
+5. Submit a PR
+
+---
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) for details.
+
+---
+
+## Citation
+
+If you use `qiskit-waveform-sim` in your research, please cite:
+
+```bibtex
+@software{qiskit_waveform_sim,
+  author       = {Qiskit Community},
+  title        = {qiskit-waveform-sim: Classical Control Waveform Simulator for Qiskit 2.5+},
+  year         = {2026},
+  url          = {https://github.com/Qiskit/qiskit-waveform-sim},
+  version      = {0.1.0},
+  doi          = {10.5281/zenodo.XXXXXXX}
+}
+```
+
+---
+
+## Acknowledgments
+
+- IBM Quantum team for Qiskit 2.x architecture and `Annotation` API
+- Zurich Instruments for LabOne Q `OutputSimulator` architectural inspiration
+- Qiskit Advocates and Unitary Foundation for ecosystem support

qiskit_waveform_sim-0.1.1/README.md

@@ -0,0 +1,207 @@
+# qiskit-waveform-sim
+
+[![PyPI](https://img.shields.io/pypi/v/qiskit-waveform-sim.svg)](https://pypi.org/project/qiskit-waveform-sim/)
+[![Python](https://img.shields.io/pypi/pyversions/qiskit-waveform-sim.svg)](https://pypi.org/project/qiskit-waveform-sim/)
+[![License](https://img.shields.io/pypi/l/qiskit-waveform-sim.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Tests](https://github.com/Qiskit/qiskit-waveform-sim/workflows/Tests/badge.svg)](https://github.com/Qiskit/qiskit-waveform-sim/actions)
+
+**Zero-bloat Classical Control Waveform Simulator & Interactive Pulse Sheet Viewer for Qiskit 2.5+**
+
+`qiskit-waveform-sim` bridges the post-Pulse waveform gap in Qiskit 2.5+ 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.
+
+---
+
+## The Problem
+
+With Qiskit 2.0–2.5, IBM completed a major architectural overhaul:
+- Core circuit structures moved to Rust (`QkCircuit`, `QkTarget`)
+- `qiskit.pulse` module was deprecated and removed
+- `qiskit-dynamics` was archived (Oct 31, 2025)
+
+This created a **structural visibility gap**:
+| Tool | Offline? | Dynamic Circuits | Fractional Gates | Virtual-Z Tracking | Sample-Precise I/Q |
+|------|----------|------------------|------------------|--------------------|---------------------|
+| `qiskit.visualization.timeline` | ✅ | ❌ | ❌ | ❌ (markers only) | ❌ |
+| `qiskit-ibm-runtime` `CircuitSchedule` | ❌ (cloud only) | ✅ (server) | ❌ | ❌ | ❌ |
+| **qiskit-waveform-sim** | ✅ | ✅ | ✅ | ✅ Exact | ✅ Lazy/Windowed |
+
+---
+
+## 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**: Continuous parametric amplitude/duration scaling for `RX(θ)`, `RZZ(θ)`
+- **BoxOp & Annotation Native**: Custom `PulseEnvelopeAnnotation` with OpenQASM 3 & QPY serialization
+- **Interactive Visualization**: Plotly-based Pulse Sheet + synchronized I/Q Oscilloscope
+- **LabOne Q Compatible Architecture**: `OutputSimulator.get_snippet()`-style API
+
+---
+
+## Installation
+
+```bash
+pip install qiskit-waveform-sim
+```
+
+For development:
+```bash
+git clone https://github.com/Qiskit/qiskit-waveform-sim
+cd qiskit-waveform-sim
+pip install -e ".[dev,test,docs]"
+```
+
+Requires Python 3.11+ and Qiskit 2.0+.
+
+---
+
+## Quickstart
+
+```python
+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: scheduling with `BoxOp` is not yet supported in Qiskit 2.5's transpiler. Use the unscheduled circuit for OpenQASM 3 export and manual waveform compilation.
+
+```python
+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
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    qiskit-waveform-sim                          │
+├─────────────────────────────────────────────────────────────────┤
+│  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 on ControlChannel          │  │
+│  │ • measure → GaussianSquare on MeasureChannel + Acquire   │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│  Pillar 2: PulseAnnotation Override (OpenQASM3 + QPY)          │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │ @pulse_sim.drag(amp=0.5, beta=0.1, σ_ratio=0.25)         │  │
+│  │ box { 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](https://qiskit-waveform-sim.readthedocs.io/en/latest/tutorials/quickstart.html)
+- [Custom Pulse Annotations & OpenQASM 3 Export](https://qiskit-waveform-sim.readthedocs.io/en/latest/tutorials/annotations.html)
+- [LabOne Q / RFSoC Integration](https://qiskit-waveform-sim.readthedocs.io/en/latest/tutorials/hardware_export.html)
+- [API Reference](https://qiskit-waveform-sim.readthedocs.io/en/latest/api.html)
+
+---
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+1. Fork the repository
+2. Create a feature branch
+3. Run tests: `pytest -v`
+4. Run linters: `ruff check . && black --check . && mypy .`
+5. Submit a PR
+
+---
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) for details.
+
+---
+
+## Citation
+
+If you use `qiskit-waveform-sim` in your research, please cite:
+
+```bibtex
+@software{qiskit_waveform_sim,
+  author       = {Qiskit Community},
+  title        = {qiskit-waveform-sim: Classical Control Waveform Simulator for Qiskit 2.5+},
+  year         = {2026},
+  url          = {https://github.com/Qiskit/qiskit-waveform-sim},
+  version      = {0.1.0},
+  doi          = {10.5281/zenodo.XXXXXXX}
+}
+```
+
+---
+
+## Acknowledgments
+
+- IBM Quantum team for Qiskit 2.x architecture and `Annotation` API
+- Zurich Instruments for LabOne Q `OutputSimulator` architectural inspiration
+- Qiskit Advocates and Unitary Foundation for ecosystem support