QICK Tutorials (Jupyter)

This section contains practical tutorials for learning QICK and the tProcessor control core. The tutorials are available as Jupyter notebooks and can be run directly on the RFSoC board.

Prerequisites

RFSoC board (ZCU111, ZCU216, or RFSoC4x2) with firmware loaded
QICK installed (see Quick-start guide)
Firmware bitstream file (.bit and its matching .hwh) for your board
Access to Jupyter notebook on the board

List of Tutorials: tProc v2

These notebooks must be run with a tProc v2 firmware. Some notebooks may have additional firmware or hardware requirements:

Notebooks 00–09 are self-contained and work on any QICK setup
Notebooks 10–15 require additional hardware resources (multi-board, streaming, DSP48, QICKBox)
Notebook 14 (XCOM) requires additional hardware: FMC transceiver board and external hub
Notebook 15 requires a QICKBox with RF (and optionally Balun) daughtercards installed

Basic Tutorials

#	Notebook	Description
00	00 - Getting Started with QICK and tProc v2	Connect to the board, inspect hardware configuration
01	01 - Basic Sequencing with tProc v2	Define pulses, create sequences, acquire data
02	02 - Parameter Sweeps with tProc v2	1D and 2D parameter sweeps
03	03 - Advanced Timing with tProc v2	`delay` vs `wait`, auto-timing, avoiding collisions
04	04 - Real-Time Feedback with tProc v2	Conditional pulses, active reset, thresholding
05	05 - Dynamic Parameters and Subroutines with tProc v2	Virtual-Z gates, subroutines, dynamic updates

Intermediate Tutorials

#	Notebook	Description
06	06 - Generators and Readouts	Basic waveform generators, readout resonators, I/Q mixing
07	07 - Advanced Generators and Readouts in tProc v2	Muxed generators, PFB readout, dynamic readouts, fast dynamic readout, electrical delay calibration, IQ offsets, performance benchmarks
08	08 - Hardware Buffers: DDR4 and MR	DDR4 and MR buffers, data capture
09	09 - Appendix: Tips, Limits, and Troubleshooting	Common errors, limits, debugging tips

Advanced Tutorials

#	Notebook	Description
10	10 - Multi-Board Synchronization	Synchronize multiple boards using external clock and external start signals
14	14 - XCOM Network Synchronization	Full mesh network for multi-board synchronization and low-latency communication (requires FMC transceiver board)
15	15 - QICKBox RF Daughtercards	QICKBox RF/Balun daughtercards: attenuators, ADMV8818 tunable filters, saturation checks (requires QICKBox with RF daughtercards)

List of Tutorials: tProc v1

These notebooks will run on the “standard” tProc v1-based firmware bitstream that is distributed with the QICK library.

#	Notebook
00	00 - Sending and receiving a pulse
01	01 - Phase coherent readout
02	02 - Sweeping variables
03	03 - Conditional logic
04	04 - Reading, math, and writing
05	05 - Calibrating the QICK for phase coherent readout (obsolete)
06	06 - Qubit demos: working with a real qubit
07	07 - Sweeping over multiple variables
08	08 - Special buffers
09	09 - Edge counting

Running the Tutorials

Connect to your RFSoC board via SSH or JupyterHub
Navigate to the docs/source/tutorials/ directory
Open the desired notebook
IMPORTANT: Change the BITSTREAM_PATH variable in the first cell to point to your firmware file
Run the cells in order

Note

Don’t have an RFSoC board handy? Tutorials 00-07 for tProc v2 are also available ported to the QICK emulator (QickEmu, a Verilator-based software simulation of the firmware) at emulator/notebooks/tutorial/*_emu.ipynb in the qick repository, and can be run directly in Google Colab with no local install – each notebook’s first “Colab Setup” cell clones the repo and installs Verilator for you. See the emulator’s README for details. Each emulator notebook’s intro cell notes what had to be adapted or skipped versus the hardware original.

Remote Execution

For remote execution (e.g., from a PC), you’ll need to start the QICK proxy server on the board first:

python -m qick.pyro

Then in your notebook, use:

from qick.pyro import make_proxy
soc = make_proxy("board_ip_address")

Common Setup Cell (copy this to any notebook)

# Configuration
BITSTREAM_PATH = "/path/to/your/firmware.bit"  # ← CHANGE THIS

# Optional: remote execution
USE_PROXY = False
PROXY_IP = "192.168.1.100"

# Connection
from qick import QickSoc
import numpy as np
import matplotlib.pyplot as plt

if USE_PROXY:
    from qick.pyro import make_proxy
    soc = make_proxy(PROXY_IP)
    print(f"Connected to proxy at {PROXY_IP}")
else:
    soc = QickSoc(bitfile=BITSTREAM_PATH)
    print("Connected directly to RFSoC")

print(f"Firmware: {soc.get_cfg()['fw_version']}")
print(f"tProc cores: {soc.num_tprocs}")

Troubleshooting

If you see “Bitstream not found”, check BITSTREAM_PATH
If tProc commands fail, try soc.reset_gens() and soc.reset_adcs()
For proxy connection issues, verify the board IP and that the proxy is running
If no signal in readout, check DAC→ADC loopback cables, verify gen_ch is correct
Phase rotates with frequency, run electrical delay calibration (see [notebook 07](./07_Advanced_Generators_And_Readouts.ipynb))