Add QCVT: pulse schedule visualization for AveragerProgramV2

.github/workflows/qcvt.yml

@@ -0,0 +1,43 @@
+name: QCVT
+
+on:
+  push:
+    paths:
+      - "qick_lib/qcvt/**"
+      - "qick_demos/qcvt/**"
+      - "setup.py"
+      - ".github/workflows/qcvt.yml"
+  pull_request:
+    paths:
+      - "qick_lib/qcvt/**"
+      - "qick_demos/qcvt/**"
+      - "setup.py"
+      - ".github/workflows/qcvt.yml"
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install qick with QCVT extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[qcvt]" pytest
+
+      - name: Show versions
+        run: |
+          python -c "import qick, qcvt; print('qick', qick.__version__); print('qcvt', qcvt.__version__)"
+
+      - name: Run QCVT tests
+        run: pytest qick_lib/qcvt/tests/ -v

.gitignore

@@ -71,3 +71,6 @@ Temporary Items
 
 !/.gitignore
 !/README.md
+
+# local conda env accidentally under repo
+.conda/

README.md

@@ -14,6 +14,7 @@ We generally recommend using the newer generation of RFSoCs (ZCU216 and RFSoC4x2
 It consists of:
 * Firmware for the supported RFSoC boards, both compiled bitstreams and source for the designs and modules
 * The `qick` Python package, which includes the interface to the firmware and an API for writing QICK programs
+* The `qcvt` package (install with `pip install "qick[qcvt]"`), which visualizes `AveragerProgramV2` pulse schedules offline — see [qick_demos/qcvt](qick_demos/qcvt)
 * [Jupyter notebooks](qick_demos) demonstrating usage
 
 See our [Read the Docs site](https://docs.qick.dev/) for:

qick_demos/README.md

@@ -25,6 +25,11 @@ Below is a brief summary of the QICK software capabilities.
 * The ability to write data to and read data from tProc memory addresses (which tProc registers can access) 
 * Addition, subtraction, multiplication, bit shifting
 
+## Pulse-schedule visualization (QCVT)
+
+* Offline visualization of compiled `AveragerProgramV2` schedules: [qick_demos/qcvt](qcvt)
+* Install extras: `pip install "qick[qcvt]"`, then `python qick_demos/qcvt/run_offline_example.py`
+
 ## Measurements on quantum devices
 
 * Measuring a single qubit [Demo 06_qubit_demos](https://github.com/openquantumhardware/qick/blob/main/qick_demos/06_qubit_demos.ipynb)

qick_demos/qcvt/README.md

@@ -0,0 +1,51 @@
+# QCVT — QICK Control Visualization Tool
+
+Visualize and export the pulse schedule of a QICK `asm_v2` program **before it is
+sent to an RFSoC**. Works online (connected) and fully offline (from a saved
+config or a compiled-program pickle).
+
+Originally developed at https://github.com/DRNag2/QCVT and proposed for inclusion
+in QICK in https://github.com/openquantumhardware/qick/issues/229.
+
+![Example schedule](example_schedule.png)
+
+## Install
+
+```bash
+# from the QICK repo root
+pip install -e ".[qcvt]"
+# optional: load compiled-program pickles
+pip install -e ".[qcvt-pickle]"
+```
+
+## Quick start (offline demo)
+
+```bash
+python qick_demos/qcvt/run_offline_example.py
+python qick_demos/qcvt/walkthrough_demo.py
+```
+
+No RFSoC needed — these use the bundled `qick_config.json`.
+
+## In your experiment code
+
+```python
+from qcvt import show_schedule, review_schedule, extract_schedule
+
+prog = YourProgram(soccfg, reps=1, final_delay=0, cfg=config)
+show_schedule(prog, title="My experiment")
+
+# Pre-submit gate
+ok = review_schedule(prog, save_dir="qcvt_reviews/my_exp", show=True, confirm=True)
+if not ok:
+    raise RuntimeError("aborted")
+
+sched = extract_schedule(prog, strict=True)
+```
+
+## Tests
+
+```bash
+pip install -e ".[qcvt]" pytest
+pytest qick_lib/qcvt/tests/ -v
+```