readout_program/chapters/04-04-acq-matched-filter.md

## 4.4. 匹配滤波器

匹配滤波器在FPGA/ASIC两种平台下由于资源不同实现的形式也不同，区别如下：

* 由于ASIC多计算少存储，因而ASIC平台使用系数计算模式以节省存储资源。
* 由于FPGA 多存储少计算，因此FPGA平台使用系数直读模式以节省DSP资源。

### 4.4.1. 读出参数存储

DAQ_PAR 模块（基地址 `0x00500000`，总容量 32 KB）存储解模所需的全部参数，
每个量子比特独占 2 KB 子空间（控制区 512 B + 权重区 1536 B）：

$$ \text{Qubit }N\text{ DAQ\_PAR 基地址} = \mathtt{0x00500000} + N \times \mathtt{0x800},\quad N = 0,1,\ldots,15 $$

**控制区**（每比特偏移 0x000 ~ 0x1FF，共 512 字节）

控制区最多支持 16 组参数（PARA_ID = 0~15），每组占用 8 个 32 位寄存器（32 字节），
各组基地址 = Qubit 基地址 + PARA_ID × `0x20`。

每组包含以下 8 个寄存器：

|组内偏移|寄存器|位段|说明|
|:-|:-|:-|:-|
|`0x00`|dds_fpw|[31:12] fcw|解模载波频率控制字：$F_c = fcw / 2^{20} \times F_s$|
|^|^|[11:0] pcw|解模载波相位控制字：$\phi_c = pcw / 2^{12} \times 2\pi$|
|`0x04`|mtf_idx|[31:16] addr|权重数据起始地址（单位：时钟周期）|
|^|^|[15:0] len|权重数据样本长度（单位：时钟周期）|
|`0x08`|line0_ab|[31:16] a0|直线0 斜率系数 a（16位有符号数）|
|^|^|[15:0] b0|直线0 斜率系数 b（16位有符号数）|
|`0x0C`|line0_c|[31:0] c0|直线0 截距系数 c（32位有符号数）|
|`0x10`|line1_ab|[31:16] a1|直线1 斜率系数 a|
|^|^|[15:0] b1|直线1 斜率系数 b|
|`0x14`|line1_c|[31:0] c1|直线1 截距系数 c|
|`0x18`|line2_ab|[31:16] a2|直线2 斜率系数 a|
|^|^|[15:0] b2|直线2 斜率系数 b|
|`0x1C`|line2_c|[31:0] c2|直线2 截距系数 c|

> 三组直线方程用于三态判断，将 IQ 平面划分为三个区间。判定公式：$a \times I < c \times 2^4 - b \times Q$。三条直线的交点应重合于一点，否则产生错误态（3态）。详见 [§4.5.3](#453-采集态数据)。

**权重区**（每比特偏移 0x200 起，共 1536 字节）

权重区存储匹配滤波器权重系数，最大 1536 个 8 位有符号系数，I 路和 Q 路权重分开存储。
详细布局见下方存储格式图。

- 系数的粒度由 `func_ctrl.step_ctrl` 控制，一个权重样本点可对应 1/2/4/8/16 个时钟周期采样点；
- 权重数据由 `mtf_idx` 中的 addr 和 len 字段索引。

**读出参数存储格式**如下图所示。

![读出参数存储格式](../assets/readout_para.png)

> 系数计算模式（ASIC）下，匹配滤波器系数 = DDS 载波 × 权重参数。FPGA 平台使用系数直读模式，仅使用 `Ctrl` 部分（mtf_idx）索引 DAQ_FLT（`0x00580000`）中预存储的匹配滤波器系数，忽略 dds_fpw 控制字。

### 4.4.2. 匹配滤波器系数

ez-Q 2.5 FPGA平台使用系数直读模式，其需要额外的存储空间来配置匹配滤波器系数。

- 其中mtf_idx的含义从索引权重数据变为索引匹配滤波器系数。
- 匹配滤波器系数索引的粒度是时钟周期，
    - 在FPGA平台下每个时钟周期对应16个采样点数据。
- 匹配滤波器系数采样点采用8比特数据位宽，因此1个周期数据位宽为128 bit，

匹配滤波器系数存储结构如下图所示。
- 匹配滤波器的I和Q数据分开存储，每个比特的I、Q数据容量分别为16 KB。
- I路数据偏移地址为 x × 32 KB，Q路数据偏移地址为 x × 32 KB + 16 KB，其中 x 为 Qubit 序号，范围为 0~15。

![匹配滤波器系数存储结构](../assets/readout_mtf.png)

### 4.4.3. 匹配滤波器系数设计原则

匹配滤波器系数直接影响解模信噪比（SNR）。本小节提供系数设计的基本指导原则。

#### 系数计算模式（ASIC 平台）

ASIC 平台下，匹配滤波器系数由 DDS 载波与权重参数实时计算：

$$\text{FilterCoeff}[n] = \text{Weight}[n] \times e^{j(2\pi f_{IF} \cdot n / F_s + \phi)}$$

其中 $f_{IF}$ 为中频频率（由 `dds_fpw.fcw` 决定），$F_s$ 为采样率。

**权重设计要点**：

1. **权重的包络应匹配输入信号的幅度包络**。理想情况下，权重是输入脉冲波形的时域反转复共轭；
2. **权重长度**（`mtf_idx.len`）应覆盖输入信号从开始到完全衰减的时间窗口。过短 → SNR 损失；过长 → 引入额外噪声且增加解模延迟；
3. **STEP_CTRL 优化**：若信号包络变化缓慢，增大 `STEP_CTRL` 可在相同权重存储空间下覆盖更长的解模窗口（见 [§4.3 参数选择指南](04-03-acq-registers.md)）；
4. **权重归一化**：建议权重系数峰值设为 ±127（8 位有符号数最大值），以充分利用动态范围。

**典型设计流程**：
1. 采集原始波形数据（`WAVE_SAVE_EN=1`），观察信号幅度和持续时间
2. 提取信号的幅度包络作为权重初始值
3. 根据 SNR 需求调整权重长度和 `STEP_CTRL`
4. 通过解模 IQ 数据的 SNR 验证权重设计效果

#### 系数直读模式（FPGA 平台）

FPGA 平台下，匹配滤波器系数需预计算并直接存入 DAQ_FLT（`0x00580000`），每 qubit 的 I/Q 各 16 KB。

**系数预计算**：
$$\text{I\_Coeff}[n] = \text{Weight}[n] \times \cos(2\pi f_{IF} \cdot n / F_s + \phi)$$
$$\text{Q\_Coeff}[n] = \text{Weight}[n] \times \sin(2\pi f_{IF} \cdot n / F_s + \phi)$$

其中每个采样点 n 对应一个时钟周期（FPGA: 16 ADC samples/cycle）。

**存储布局注意**：每个时钟周期的 128 位数据（16 samples × 8 bit）需按大端字节序排列，I/Q 分开存储且地址偏移为 16 KB（见 [§4.4.2](#442-匹配滤波器系数) 存储结构图）。

> **跨平台一致性**：对于同一组解模参数，ASIC 和 FPGA 平台应产生相同的解模结果（在量化误差范围内）。建议在平台移植时，用相同的输入波形验证两个平台的 IQ 输出一致性。