hpc-lab-code/work/QUICKSTART.md

# 快速开始指南

## 项目概述

本项目实现了MPI-OpenMP混合并行的矩阵乘法程序，用于高性能计算课程实验。

## 文件结构

```
gemm/
├── gemm_serial.cpp       # 串行版本
├── gemm_parallel.cpp     # MPI-OpenMP混合并行版本
├── gemm_optimized.cpp    # 优化版本
├── build.sh              # 编译脚本
├── quick_test.sh         # 快速测试脚本
├── run_experiments.sh    # 完整实验脚本
├── analyze_results.py    # 数据分析脚本
├── README.md             # 本文件
└── 实验报告模板.md       # 实验报告模板
```

## 快速开始

### 1. 编译程序

```bash
cd /home/yly/dev/hpc-lab-code/work/gemm
./build.sh
```

### 2. 快速测试

```bash
./quick_test.sh
```

这将运行一系列小规模测试，验证程序功能是否正常。

### 3. 运行完整实验

```bash
./run_experiments.sh
```

这将运行所有实验并收集数据到CSV文件。

### 4. 分析结果

```bash
python3 analyze_results.py
```

这将生成性能分析图表和摘要。

## 手动运行示例

### 串行版本

```bash
./gemm_serial 1024 1024 1024 0
```

### 并行版本

```bash
# 使用4个MPI进程
mpirun -np 4 ./gemm_parallel 1024 1024 1024

# 使用2个MPI进程，每个进程4个OpenMP线程
export OMP_NUM_THREADS=4
mpirun -np 2 ./gemm_parallel 2048 2048 2048
```

### 优化版本

```bash
mpirun -np 4 ./gemm_optimized 2048 2048 2048
```

## 实验数据说明

### 输出文件

1. **serial_results.csv**：串行基准测试结果
   - 格式：M,N,K,Time_ms

2. **experiment_results.csv**：并行实验结果
   - 格式：Experiment,M,N,K,MPI_Processes,OpenMP_Threads,Time_ms,Speedup,Efficiency

3. **生成的图表**：
   - exp1_mpi_scaling.png：实验一性能曲线
   - exp2_hybrid_scaling.png：实验二性能曲线
   - exp3_mpi_openmp_combo.png：实验三配置对比
   - efficiency_heatmap.png：效率热图

### 数据处理

使用Excel、Python或R处理CSV文件：

**Python示例**：
```python
import pandas as pd
import matplotlib.pyplot as plt

# 读取数据
df = pd.read_csv('experiment_results.csv')

# 筛选实验一的数据
exp1 = df[df['Experiment'] == 'Exp1']

# 绘制加速比曲线
for size in exp1['M'].unique():
    data = exp1[exp1['M'] == size]
    plt.plot(data['MPI_Processes'], data['Speedup'], 
             marker='o', label=f'{size}×{size}')

plt.xlabel('MPI进程数')
plt.ylabel('加速比')
plt.legend()
plt.savefig('my_speedup_plot.png')
```

## 实验报告撰写

1. 使用`实验报告模板.md`作为报告框架
2. 填入实验数据和分析结果
3. 插入生成的性能图表
4. 撰写结果分析和心得体会

## 常见问题

### Q1: 编译时提示找不到mpi.h

**A**: 确保已安装MPI开发库：
```bash
# Ubuntu/Debian
sudo apt-get install libopenmpi-dev

# CentOS/RHEL
sudo yum install openmpi-devel
```

### Q2: 运行时提示找不到mpirun

**A**: 确保已安装MPI运行时：
```bash
# Ubuntu/Debian
sudo apt-get install openmpi-bin

# CentOS/RHEL
sudo yum install openmpi
```

### Q3: Python脚本运行失败

**A**: 安装必要的Python包：
```bash
pip3 install pandas matplotlib seaborn
```

### Q4: 性能不如预期

**A**: 检查以下几点：
1. CPU频率是否正常（是否降频）
2. 关闭其他占用资源的程序
3. 检查系统负载
4. 确认编译优化选项已启用（-O3）

### Q5: 结果验证失败

**A**: 可能的原因：
1. 矩阵尺寸不能被进程数整除
2. MPI通信错误
3. 内存分配问题

检查程序输出中的错误信息。

## 性能优化建议

### 1. 选择合适的进程数

- 小矩阵（< 1024）：1-4个进程
- 中等矩阵（1024-2048）：4-9个进程
- 大矩阵（> 2048）：9-16个进程

### 2. 选择合适的OpenMP线程数

- 单节点：使用物理核心数
- 多节点：每个节点的物理核心数
- 通常4-8个线程效果较好

### 3. 矩阵尺寸选择

- 确保矩阵尺寸能被进程数较好地整除
- 避免过小的矩阵（通信开销大）
- 考虑内存容量限制

## 进阶使用

### 自定义实验参数

编辑`run_experiments.sh`，修改以下变量：

```bash
# 矩阵尺寸
MATRIX_SIZES="512 1024 2048 4096"

# MPI进程数
MPI_PROCESSES="1 2 4 9 16"

# OpenMP线程数
OPENMP_THREADS="1 2 4 8"
```

### 添加新的优化版本

1. 复制`gemm_parallel.cpp`作为模板
2. 实现你的优化算法
3. 在`build.sh`中添加编译命令
4. 在测试脚本中添加测试用例

### 性能分析工具

使用MPI性能分析工具：

```bash
# 使用MPI profiling
mpirun -np 4 -mca pml_ob1_verbose 30 ./gemm_parallel 1024 1024 1024

# 使用时间分析
time mpirun -np 4 ./gemm_parallel 1024 1024 1024
```

## 参考资料

- [MPI教程](https://mpitutorial.com/)
- [OpenMP官方文档](https://www.openmp.org/)
- [并行编程模式](https://patterns.eecs.berkeley.edu/)
- 本地MPI文档：`man MPI_*`

## 联系与支持

如有问题，请：
1. 检查本README的常见问题部分
2. 查看实验报告模板中的详细说明
3. 参考课程教材和讲义
4. 联系助教或老师

## 版本历史

- v1.0 (2026-01-21): 初始版本
  - 实现串行、并行、优化版本
  - 提供完整的测试和分析脚本
  - 包含实验报告模板

## 许可证

本项目仅用于教学目的。