BP-AC CUDA Decoder Annotated Copy

这是一个带中文注释的 BP-AC 解码器代码副本，面向想阅读 CUDA 后端、Python 调用封装和 benchmark 脚本的新手。代码主体来自 release 版本，注释重点解释 BP、AC、cluster、pivot、Stage1/2/3、DEM 转矩阵、Sinter benchmark 等算法流程。

目录结构

copy/
  cuda/
    ac_decoder.h
    ac_decoder.cu
    ac_backend.cuh
    ac_backend.cu
  python/
    bptac_pgfast_release.py
    dem_utils.py
    sinter_bptac_timed_full_pgfast_release.py
    sinter_bposd_timed.py
    run_bbcode_benchmark_pgfast_release.py
    run_server_bbcode_benchmark_pgfast_release.py
    gong_src/
      __init__.py
      build_circuit.py
      codes_q.py
      utils.py

代码功能概览

cuda/ 中是 CUDA/C++ 后端：

• ac_decoder.cu / ac_decoder.h：实现 BP 消息传递、BP 收敛样本的 logical 投影、BP 失败样本的 AC 解码流程，以及 AC Stage1/Stage2/Stage3 的核心 kernel。
• ac_backend.cu / ac_backend.cuh：负责主机侧调度，包括上传 H/L/epsilon、创建 GPU 工作区、批量运行 BP、筛出失败 shot、调用 AC、汇总统计，并暴露 C API 给 Python。

python/ 中是 Python 调用和 benchmark：

• bptac_pgfast_release.py：用 ctypes 调用 CUDA 后端动态库，提供 BPTACDecoder。
• dem_utils.py：把 Stim detector error model 转成 BP-AC 需要的 H、L 和错误先验概率。
• sinter_bptac_timed_full_pgfast_release.py：把 GPU BP-AC 封装成 Sinter decoder，并记录阶段耗时。
• sinter_bposd_timed.py：CPU BP-OSD 对照解码器封装。
• run_bbcode_benchmark_pgfast_release.py：BBCode benchmark 主脚本。
• run_server_bbcode_benchmark_pgfast_release.py：服务器环境下的 benchmark 启动脚本。
• gong_src/：构造 BBCode/CSS 码和 Stim 电路所需的辅助代码。

依赖

Python 依赖：

python -m pip install numpy scipy matplotlib stim sinter ldpc

CUDA 后端需要：

• NVIDIA CUDA Toolkit
• 支持 CUDA 的 NVIDIA GPU
• Windows 下需要 MSVC Build Tools；Linux 下需要可用的 C++ 编译环境

编译 CUDA 后端

在仓库根目录或 copy 的上级目录执行，Windows 示例：

nvcc -O3 -std=c++17 --shared -Xcompiler "/EHsc /MD" -o copy\python\ac.dll copy\cuda\ac_decoder.cu copy\cuda\ac_backend.cu
$env:BPTAC_DLL_PATH=(Resolve-Path copy\python\ac.dll)

Linux 示例：

nvcc -O3 -std=c++17 --shared -Xcompiler "-fPIC" -o copy/python/libbptac.so copy/cuda/ac_decoder.cu copy/cuda/ac_backend.cu
export BPTAC_DLL_PATH="$(pwd)/copy/python/libbptac.so"

bptac_pgfast_release.py 会优先读取 BPTAC_DLL_PATH，如果没有设置，会在脚本目录下搜索 ac.dll、libbptac.so 等动态库文件。

运行示例

小规模 smoke benchmark：

python copy/python/run_bbcode_benchmark_pgfast_release.py --codes 72 --decoder-mode ac_only --max-shots 100 --max-errors 1 --num-workers 1 --tag smoke

同时跑 GPU BP-AC 和 CPU BP-OSD 对照：

python copy/python/run_bbcode_benchmark_pgfast_release.py --codes 72,90 --decoder-mode both --max-shots 2000 --num-workers 1 --tag compare