# 2025-hpk-hw1

**Repository Path**: gpuap/2025-hpk-hw1

## Basic Information

- **Project Name**: 2025-hpk-hw1
- **Description**: https://github.com/Elivis-AI/ucas-gpu-proj1
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-25
- **Last Updated**: 2026-01-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CUDA实现简单脉冲神经网络
> 2025年秋季国科大《GPU架构与编程》大作业一项目：使用CUDA实现脉冲网络在FashionMNIST上的推理程序。

## 任务介绍
使用CUDA实现脉冲神经网络的推理程序，并优化使程序提高推理速度，神经网络训练程序参考`train.py`中的实现，CUDA程序中标记区域不允许修改，标记如下所示：
```
// ===========================================================================
// XXX - DO NOT MODIFY BEGIN
// ===========================================================================

// ===========================================================================
// XXX - DO NOT MODIFY END
// ===========================================================================
```

### 排名规则
只有准确率大于等于 0.8978 的提交才会被计入有效排名，准确率不达标的提交是无效的。在满足此条件下，将按照推理总时间从低到高进行排名。CUDA文件编译运行后将会输出`time:acc`格式的结果，time为推理耗时，单位为s；准确率acc是一个0-1之间的浮点数。

### 编译与环境
评测服务器CUDA版本为11.8，编译命令为：
```
nvcc inference.cu -o inference_prog -Xcompiler "-O3 -std=c++14" -gencode arch=compute_60,code=sm_60 -gencode arch=compute_61,code=sm_61 -gencode arch=compute_70,code=sm_70 -rdc=true
```
评测将在单块Tesla V100S-PCIE-32GB上进行。

### 训练程序
为了提高作业的竞争上限，我们提供训练程序（训练程序可以直接导出权重，并且可以被推理程序模板直接加载使用）以及助教训练好的权重(其准确率正好是0.8978)，你可以直接使用助教训练的权重，也可以自己训练新的权重，还可以微调网络结构，但是需要注意遵守下面的约束：
- 模型的基本结构和层数不能有变化，任何改变模型层数，卷积类型的操作都是不允许的，且必须保证导出10个固定名称的权重文件。
- 结构拓扑恒定:
    禁止改变层数与顺序：必须保持 Conv -> IF -> Pool -> Conv -> IF -> Pool -> Flatten -> FC -> IF -> FC -> IF -> FC 的 11 层网络拓扑结构。不得增加、删除或重排任何层。
- 层类型恒定:
    禁止改变层的根本类型：Conv2d 必须是标准的密集卷积，MaxPool2d 必须是最大池化，Linear 必须是全连接层。严禁替换为 Depthwise Convolution、AvgPool2d 等其他类型。
- SNN 本质恒定:
    禁止将模型退化为静态网络：IFNode 必须被实现为一个随时间演化的脉冲神经元。时间步长 T 必须大于等于 2 (T >= 2)。T=1 会使模型失去时间动态性，等同于一个普通 ANN，因此被禁止。你必须完整实现膜电位（membrane potential）在 T 个时间步内的累积与重置逻辑。
- 允许修改 SNN 时间步长 T:
    你可以将 T 设置为 2 到 8 之间的任意整数 (T ∈ [2, 8])。
- 允许减少或增加层的“宽度”:
    你可以减少或增加卷积层的输出通道数和全连接层的输出神经元数量,确保修改之后相邻层之间是兼容的。
- 允许调整卷积/池化核的基础参数:
    你可以修改卷积核的 kernel_size、stride、padding，以及池化层的 kernel_size、stride。



## 环境配置
需要确保设备中有英伟达显卡，并已经安装驱动和nvcc，使用下面的命令检查
```
nvidia-smi
nvcc -V
```

如果需要使用训练程序，需要配置python环境，以conda为例
```
conda create -n cuda-cnn-tester-2025 python=3.12
pip install -r requirements.txt
```


## 使用
### 下载数据集
可以运行训练脚本自动下载或者手动下载FashionMNIST数据集并整理成如下格式
```
data
└── FashionMNIST
    └── raw
        ├── t10k-images-idx3-ubyte
        ├── t10k-images-idx3-ubyte.gz
        ├── t10k-labels-idx1-ubyte
        ├── t10k-labels-idx1-ubyte.gz
        ├── train-images-idx3-ubyte
        ├── train-images-idx3-ubyte.gz
        ├── train-labels-idx1-ubyte
        └── train-labels-idx1-ubyte.gz
```

### 训练模型（可选）
```
python train.py
```

### 编译运行
首先确认自己设备对应的sm号，并在`test.sh`中添加对应的gencode选项，如`-gencode arch=compute_60,code=sm_60`。
```
bash test.sh
```
运行后会在report文件夹中生成`.nsys-rep`结尾的性能分析报告文件，使用`nsys-ui`打开分析器并将文件拖入即可打开。

可以从Release中下载历史版本导出的文件，包含权重、CUDA文件、训练程序和nsys性能分析文件。


## 项目文件说明
- [train.py](train.py): 包含神经网络结构的定义和训练脚本。
- [inference.cu](inference.cu): 需要优化的 CUDA 推理程序（单文件）。
- [analysis.py](analysis.py): 分析脉冲神经网络激活度的脚本。
- [test.sh](test.sh): 编译+推理+性能分析。
- [commit.sh](commit.sh): 将权重导出成压缩包，并将cuda文件导出成符合模板提交要求的格式。
- [weights/](weights): 训练导出的权重文件目录，其中[weights/official/](weights/official/)文件夹内为默认权重，准确率为0.8978。