00 - Getting Started with QICK and tProc v2
Objective: Verify your QICK installation, connect to the RFSoC board, and understand the basic hardware configuration.
1. Setup and Imports
[1]:
# Jupyter notebook setup
%matplotlib inline
import matplotlib.pyplot as plt
import numpy as np
import logging
# Core QICK imports
import qick
from qick import *
# tProc v2 specific classes
from qick.asm_v2 import AveragerProgramV2, QickSweep1D, QickSpan
# Optional: increase logging level for debugging
# logging.basicConfig(level=logging.DEBUG)
logging.basicConfig(level=logging.INFO, format='%(levelname)-8s [%(filename)s:%(lineno)d] %(message)s')
# Reduce noise from the tProc core
logging.getLogger("qick_processor").setLevel(logging.WARNING)
# Display the loaded QICK library version
print(f"QICK Version: {qick.get_version()}")
QICK Version: 0.2.381
Explanation: This cell imports all necessary libraries. The qick.asm_v2 module contains the classes for building tProc v2 programs. The logging configuration helps with debugging if something goes wrong.
2. Connect to the RFSoC Board
You need to provide the correct path to your firmware .bit file. This file is specific to your board model and the firmware version.
[2]:
# --- IMPORTANT: Change this path to point to your firmware file ---
# Common paths for different boards (examples):
# ZCU111: '/home/xilinx/jupyter_notebooks/qick_firmware/out/qick_zcu111.bit'
# RFSoC4x2: '/home/xilinx/jupyter_notebooks/qick_firmware/out/qick_4x2.bit'
# ZCU216: '/home/xilinx/jupyter_notebooks/qick_firmware/out/qick_216.bit'
BITSTREAM_PATH = 'qick_216.bit'#'/path/to/your/firmware.bit' # <--- YOU MUST CHANGE THIS
# Connect to the board
soc = QickSoc(BITSTREAM_PATH)
soccfg = soc # 'soccfg' is a common alias used throughout QICK examples
print("\n=== Board Connection Successful ===")
=== Board Connection Successful ===
3. Inspect the Hardware Configuration
The QickSoc object contains all the information about your firmware: clock frequencies, generator channels, readout channels, digital I/O, and tProc capabilities.
[3]:
print(soccfg)
QICK running on ZCU216, software version 0.2.381
Firmware configuration (built Sun Aug 10 18:48:22 2025):
Global clocks (MHz): tProc dispatcher timing 430.080, RF reference 245.760
Groups of related clocks: [tProc timing clock, DAC tile 1, DAC tile 2, DAC tile 3], [DAC tile 0], [ADC tile 2]
16 signal generator channels:
0: axis_signal_gen_v6 - fs=9584.640 Msps, fabric=599.040 MHz
envelope memory: 65536 complex samples (6.838 us)
32-bit DDS, range=9584.640 MHz
DAC tile 0, blk 0 is 0_228 on JHC1, or QICK box DAC port 0
1: axis_signal_gen_v6 - fs=9584.640 Msps, fabric=599.040 MHz
envelope memory: 16384 complex samples (1.709 us)
32-bit DDS, range=9584.640 MHz
DAC tile 0, blk 1 is 1_228 on JHC2, or QICK box DAC port 1
2: axis_signal_gen_v6 - fs=9584.640 Msps, fabric=599.040 MHz
envelope memory: 32768 complex samples (3.419 us)
32-bit DDS, range=9584.640 MHz
DAC tile 0, blk 2 is 2_228 on JHC1, or QICK box DAC port 2
3: axis_signal_gen_v6 - fs=9584.640 Msps, fabric=599.040 MHz
envelope memory: 16384 complex samples (1.709 us)
32-bit DDS, range=9584.640 MHz
DAC tile 0, blk 3 is 3_228 on JHC2, or QICK box DAC port 3
4: axis_sg_mixmux8_v1 - fs=6881.280 Msps, fabric=430.080 MHz
32-bit DDS, range=1720.320 MHz
DAC tile 1, blk 0 is 0_229 on JHC1, or QICK box DAC port 4
5: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 16384 complex samples (38.095 us)
32-bit DDS, range=1720.320 MHz
DAC tile 1, blk 1 is 1_229 on JHC2, or QICK box DAC port 5
6: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 8192 complex samples (19.048 us)
32-bit DDS, range=1720.320 MHz
DAC tile 1, blk 2 is 2_229 on JHC1, or QICK box DAC port 6
7: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 16384 complex samples (38.095 us)
32-bit DDS, range=1720.320 MHz
DAC tile 1, blk 3 is 3_229 on JHC2, or QICK box DAC port 7
8: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 8192 complex samples (19.048 us)
32-bit DDS, range=1720.320 MHz
DAC tile 2, blk 0 is 0_230 on JHC3, or QICK box DAC port 8
9: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 8192 complex samples (19.048 us)
32-bit DDS, range=1720.320 MHz
DAC tile 2, blk 1 is 1_230 on JHC4, or QICK box DAC port 9
10: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 8192 complex samples (19.048 us)
32-bit DDS, range=1720.320 MHz
DAC tile 2, blk 2 is 2_230 on JHC3, or QICK box DAC port 10
11: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 8192 complex samples (19.048 us)
32-bit DDS, range=1720.320 MHz
DAC tile 2, blk 3 is 3_230 on JHC4, or QICK box DAC port 11
12: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 8192 complex samples (19.048 us)
32-bit DDS, range=1720.320 MHz
DAC tile 3, blk 0 is 0_231 on JHC3, or QICK box DAC port 12
13: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 8192 complex samples (19.048 us)
32-bit DDS, range=1720.320 MHz
DAC tile 3, blk 1 is 1_231 on JHC4, or QICK box DAC port 13
14: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 8192 complex samples (19.048 us)
32-bit DDS, range=1720.320 MHz
DAC tile 3, blk 2 is 2_231 on JHC3, or QICK box DAC port 14
15: axis_sg_int4_v2 - fs=6881.280 Msps, fabric=430.080 MHz
envelope memory: 8192 complex samples (19.048 us)
32-bit DDS, range=1720.320 MHz
DAC tile 3, blk 3 is 3_231 on JHC4, or QICK box DAC port 15
10 readout channels:
0: axis_dyn_readout_v1 - configured by tProc output 4
fs=2457.600 Msps, decimated=307.200 MHz, 32-bit DDS, range=2457.600 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 4096 decimated (13.333 us)
triggered by tport 10, pin 0, feedback to tProc input 0
ADC tile 2, blk 0 is 0_226 on JHC7, or QICK box ADC port 4
1: axis_dyn_readout_v1 - configured by tProc output 4
fs=2457.600 Msps, decimated=307.200 MHz, 32-bit DDS, range=2457.600 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 4096 decimated (13.333 us)
triggered by tport 11, pin 0, feedback to tProc input 1
ADC tile 2, blk 2 is 2_226 on JHC7, or QICK box ADC port 6
2: axis_pfb_readout_v4 - configured by PYNQ
fs=2457.600 Msps, decimated=38.400 MHz, 32-bit DDS, range=38.400 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 1024 decimated (26.667 us)
triggered by tport 12, pin 0, feedback to tProc input 2
ADC tile 2, blk 1 is 1_226 on JHC8, or QICK box ADC port 5
3: axis_pfb_readout_v4 - configured by PYNQ
fs=2457.600 Msps, decimated=38.400 MHz, 32-bit DDS, range=38.400 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 1024 decimated (26.667 us)
triggered by tport 13, pin 0, feedback to tProc input 3
ADC tile 2, blk 1 is 1_226 on JHC8, or QICK box ADC port 5
4: axis_pfb_readout_v4 - configured by PYNQ
fs=2457.600 Msps, decimated=38.400 MHz, 32-bit DDS, range=38.400 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 1024 decimated (26.667 us)
triggered by tport 14, pin 0, feedback to tProc input 4
ADC tile 2, blk 1 is 1_226 on JHC8, or QICK box ADC port 5
5: axis_pfb_readout_v4 - configured by PYNQ
fs=2457.600 Msps, decimated=38.400 MHz, 32-bit DDS, range=38.400 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 1024 decimated (26.667 us)
triggered by tport 15, pin 0, feedback to tProc input 5
ADC tile 2, blk 1 is 1_226 on JHC8, or QICK box ADC port 5
6: axis_pfb_readout_v4 - configured by PYNQ
fs=2457.600 Msps, decimated=38.400 MHz, 32-bit DDS, range=38.400 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 1024 decimated (26.667 us)
triggered by tport 16, pin 0, feedback to tProc input 6
ADC tile 2, blk 1 is 1_226 on JHC8, or QICK box ADC port 5
7: axis_pfb_readout_v4 - configured by PYNQ
fs=2457.600 Msps, decimated=38.400 MHz, 32-bit DDS, range=38.400 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 1024 decimated (26.667 us)
triggered by tport 17, pin 0, feedback to tProc input 7
ADC tile 2, blk 1 is 1_226 on JHC8, or QICK box ADC port 5
8: axis_pfb_readout_v4 - configured by PYNQ
fs=2457.600 Msps, decimated=38.400 MHz, 32-bit DDS, range=38.400 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 1024 decimated (26.667 us)
triggered by tport 18, pin 0, feedback to tProc input 8
ADC tile 2, blk 1 is 1_226 on JHC8, or QICK box ADC port 5
9: axis_pfb_readout_v4 - configured by PYNQ
fs=2457.600 Msps, decimated=38.400 MHz, 32-bit DDS, range=38.400 MHz
axis_avg_buffer v1.2 (has edge counter, no weights)
memory 8192 accumulated, 1024 decimated (26.667 us)
triggered by tport 19, pin 0, feedback to tProc input 9
ADC tile 2, blk 1 is 1_226 on JHC8, or QICK box ADC port 5
8 digital output pins:
0: PMOD0_0_LS
1: PMOD0_1_LS
2: PMOD0_2_LS
3: PMOD0_3_LS
4: PMOD0_4_LS
5: PMOD0_5_LS
6: PMOD0_6_LS
7: PMOD0_7_LS
tProc: qick_processor ("v2") rev 26, core execution clock 215.040 MHz
memories (words): program 4096, data 16384, waveform 1024
external start pin: PMOD1_0_LS
external stop pin: None
DDR4 memory buffer: 1073741824 samples (3.495 sec), 128 samples/transfer
wired to readouts [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
MR buffer: 8192 samples (3.333 us), wired to readouts [0, 1]
Explanation: The printed output shows:
Global clocks: tProc timing clock, RF reference frequency
Signal generators: Number of channels, sample rates, envelope memory size
Readout channels: Sample rates, buffer sizes, trigger mappings
Digital output pins: Available PMOD pins
tProc configuration: Program memory size, data memory size, waveform memory size, core clock
This information is essential when configuring your experiments.
4. Quick Hardware Test
To verify that the board is responding correctly, read the tProc’s program counter and test data memory access.
[4]:
# Read the tProc's program counter (should be 0 after reset)
pc = soc.get_tproc_counter(addr=1)
print(f"tProc Program Counter: {pc}")
# Read a data memory address to verify communication
# Data memory address 0 should contain some value, but reading it confirms the interface works
try:
data = soc.read_mem(length=1, mem_sel='dmem', addr=0)
print(f"Data memory read test: {data}")
except Exception as e:
print(f"Data memory read failed: {e}")
print("\n✓ Basic board communication verified via program counter read.")
tProc Program Counter: 0
Data memory read test: [0]
✓ Basic board communication verified via program counter read.
Explanation: These simple reads confirm that the communication with the board is working correctly. The tProc program counter should be 0 before we load a program.
5. Summary
You are now ready to start writing QICK experiments. The next notebook (`01_Basic_Sequencing.ipynb <./01_Basic_Sequencing.ipynb>`__) will show you how to define and play pulses, and acquire data.
Key takeaways:
Use
QickSoc(path)to connect to your boardThe
soccfgobject holds all hardware configuration informationAlways check that your firmware path is correct for your specific board
Use
get_tproc_counter()andread_mem()to verify board communication