Metadata-Version: 2.4
Name: qiskit-waveform-sim
Version: 0.1.4
Summary: Zero-bloat Classical Control Waveform Simulator and Interactive Pulse Sheet Viewer
Author-email: Pratul Deshpande <pratul.deshpande06@gmail.com>
Maintainer-email: Pratul Deshpande <pratul.deshpande06@gmail.com>
License: 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] [Pratul Deshpande]
        
        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.
Project-URL: Homepage, https://github.com/PratulDeshpande/qiskit-waveform-sim
Project-URL: Repository, https://github.com/PratulDeshpande/qiskit-waveform-sim
Project-URL: Documentation, https://pratuldeshpande.github.io/qiskit-waveform-sim
Project-URL: Changelog, https://github.com/PratulDeshpande/qiskit-waveform-sim/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/PratulDeshpande/qiskit-waveform-sim/issues
Keywords: qiskit,quantum-computing,waveform-simulation,pulse-sheet,quantum-control,openqasm
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qiskit<3.0.0,>=1.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"
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"
Dynamic: license-file

# qiskit-waveform-sim

[![PyPI](https://img.shields.io/pypi/v/qiskit-waveform-sim.svg?cache=clear)](https://pypi.org/project/qiskit-waveform-sim/)
[![Python](https://img.shields.io/pypi/pyversions/qiskit-waveform-sim.svg?cache=clear)](https://pypi.org/project/qiskit-waveform-sim/)
[![License](https://img.shields.io/pypi/l/qiskit-waveform-sim.svg?cache=clear)](https://www.apache.org/licenses/LICENSE-2.0)
[![Tests](https://github.com/PratulDeshpande/qiskit-waveform-sim/actions/workflows/tests.yml/badge.svg)](https://github.com/PratulDeshpande/qiskit-waveform-sim/actions)

**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

`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` and `QuantumCircuit` APIs.

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

| Tool | Offline? | Dynamic Circuits | Fractional Gates | Virtual-Z Tracking | Sample-Precise I/Q |
|------|----------|------------------|------------------|--------------------|---------------------|
| `qiskit.visualization.timeline` | Yes | No | No | No (markers only) | No |
| `qiskit-ibm-runtime` `CircuitSchedule` | No (cloud only) | Yes (server) | No | No | No |
| **qiskit-waveform-sim** | Yes | Yes | Yes | Yes Exact | Yes 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/PratulDeshpande/qiskit-waveform-sim
cd qiskit-waveform-sim
pip install -e ".[dev,test,docs]"
```

Requires Python 3.11+ and Qiskit 1.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.0'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

**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 (OpenQASM 3 + 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://pratuldeshpande.github.io/qiskit-waveform-sim/tutorials/quickstart.html)
- [Custom Pulse Annotations & OpenQASM 3 Export](https://pratuldeshpande.github.io/qiskit-waveform-sim/tutorials/annotations.html)
- [LabOne Q / RFSoC Integration](https://pratuldeshpande.github.io/qiskit-waveform-sim/tutorials/hardware_export.html)
- [API Reference](https://pratuldeshpande.github.io/qiskit-waveform-sim/api/core.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       = {Pratul Deshpande},
  title        = {qiskit-waveform-sim: Classical Control Waveform Simulator},
  year         = {2026},
  url          = {https://github.com/PratulDeshpande/qiskit-waveform-sim},
  version      = {0.1.2}
}
```
