# 算子大赛S2仓库官方示例

**Repository Path**: rymaker/operator-competition-demo

## Basic Information

- **Project Name**: 算子大赛S2仓库官方示例
- **Description**: 算子大赛S2仓库官方示例
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 32
- **Created**: 2026-08-28
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 算子大赛作品示例仓库

本仓库是算子大赛官方作品示例仓库，可作为选手提交作品的目录结构参考。

示例地址：

```text
https://gitee.com/mthreadsacademy/operator-competition-demo
```

## 使用方式

1. Fork 或复制本仓库。
2. 在对应赛题目录下完成作品实现。
3. 将代码提交到 `master` 分支。
4. 在摩尔学院提交页填写你的 Gitee 仓库主页 HTTPS 地址，例如 `https://gitee.com/<owner>/<repo>`，不要填写目录或单个文件地址。
5. 如果仓库是 private，请将大赛官方账号 `MUSA-Operator` 加入仓库并授予只读权限，且至少保留至正式榜公布及获奖复核结束。

选手不需要配置 Gitee webhook。提交仓库地址后，评测系统会定时检测仓库最新提交并自动触发评测。

评测系统会分页同步多个报名绑定，并为每份报名记录独立轮询、拉取和评测其绑定的 Gitee 仓库；一个绑定对应一个仓库，同一仓库不得同时绑定多个参赛账号或多份报名记录。轮询间隔内发生多次 push 时，评测系统只保证处理扫描时 `master` 分支的最新 commit。正式榜候选版本为截止时间前已被评测系统记录、通过完整正确性校验且状态为 `Accepted` 的历史最高吞吐成绩对应 commit；失败的新提交不会覆盖已确认的历史最佳成绩。

## 目录结构

```text
operator-competition-demo/
  README.md
  README.en.md
  docs/
    算子挑战赛S2_GEMM_build.sh使用说明.md
  examples/
    build_sh_patterns/
  GEMM/
    README.md
    submission.mu
    build.sh
  scripts/
    check_structure.py
```

当前 S2 赛季正式赛题为 GEMM 优化，本仓库仅保留 `GEMM/` 的完整最小示例。

其中 `GEMM/` 是选手 clone 后直接修改和提交的工作区；`docs/` 和 `examples/` 是同级说明与参考目录，不属于正式提交入口。

## 必需文件

每个赛题目录至少需要包含：

```text
<ProblemName>/
  build.sh
  README.md
```

GEMM 赛题还必须包含：

```text
GEMM/
  submission.mu
```

`submission.mu` 是 GEMM 赛题的参赛实现文件，必须暴露固定入口：

```cpp
extern "C" void gemm_optimized(
    half const* d_A,
    half const* d_B,
    half* d_C,
    int M,
    int N,
    int K);
```

`build.sh` 是官方包装代码编译前执行的准备脚本。即使无需额外准备，也必须保留该文件并保证脚本正常退出。脚本可以在 `GEMM/` 内生成由 `submission.mu` 直接引用的头文件或辅助源码，但不得替换官方 runner、绕过官方编译流程或生成可执行文件代替 `gemm_optimized` 接口。

参赛实现使用 MUSA C++ 编写，提交文件为 `.mu`，使用赛事指定的 `mcc` 编译器和 MUSA SDK 编译。允许使用 MUSA Runtime API、标准 C/C++、公开的 WMMA/Tensor Core 和其他底层编译器接口，以及自行实现的 Kernel、分块、共享内存、寄存器、流水线和双缓冲优化。

## GEMM 示例

GEMM 赛题要求实现 FP16 GEMM：

```text
C[M, N] = A[M, K] x B[K, N]
```

输入 A/B 为 FP16，计算语义为 FP32 累加后写回 FP16。示例实现位于：

```text
GEMM/submission.mu
```

该实现是便于理解接口的朴素参考结构，不是高性能实现。正式比赛中，选手需要自行优化分块、访存、共享内存、寄存器、流水线和 Tensor Core/WMMA 使用方式，才能获得更好的性能成绩。

本赛题定位为公开固定大 shape 的 peak GEMM 性能挑战，不考察任意 shape 泛化能力，但参赛实现必须正确处理官方公开的正确性 case 和性能 case。性能 case 为：

```text
M=8192、N=8192、K=16384
```

允许基于公开性能 shape 选择特化 tile、kernel、调度和访存策略；禁止利用 shape 判断跳过计算、复用旧输出、只计算部分元素或生成非真实 GEMM 结果。

抽样校验结果仅供评测系统内部快速反馈，不进入摩尔学院实时榜单。`Accepted` 必须表示性能 case 已完整正确性校验通过。正式榜、获奖复核和 Accepted 成绩确认必须对性能 case 做完整正确性校验。

摩尔学院回调中的 `score` 使用该报名历史最优 Accepted 成绩的 GFLOPS，按两位小数传输，取值范围为 `0.01`～`999999.99`。评测系统内部同时保存原始 `score_gflops`、`score_tflops` 和 `time_ms`。没有历史 Accepted 成绩的失败提交不回调 `score`，因此不会在榜单产生 `0.00` 记录；已有历史最优成绩时，失败或低分提交回调历史最优成绩，并更新提交次数和最后一次提交时间。

## 本地结构检查

选手在提交前可以先运行结构检查脚本，自检仓库目录和入口文件是否齐全。脚本通过后，说明当前仓库结构已经满足本赛题的最小提交要求：

```bash
python3 scripts/check_structure.py
```

该脚本只检查目录和入口函数，不代表正式评测成绩。

## `build.sh` 使用说明与公开案例

完整说明见：

```text
docs/算子挑战赛S2_GEMM_build.sh使用说明.md
```

不含算子实现的目录组织和构建准备案例位于：

```text
examples/build_sh_patterns/
```

案例编号与说明文档章节直接对应：`case5` 对应第 5 节，`case7` 对应第 7 节，`case8` 对应第 8 节。可以执行以下命令验证三组公开案例的文件检查、重复执行和确定性生成行为：

```bash
sh examples/build_sh_patterns/verify_examples.sh
```

案例仅用于说明 `build.sh` 和文件组织，不提供或模拟 GEMM 实现，也不能替代正式 `GEMM/submission.mu`。

## 评测流程说明

评测系统会执行以下步骤：

1. 从摩尔学院同步报名记录和作品仓库地址。
2. 定时读取仓库 `master` 分支最新 commit。
3. 发现新 commit 后拉取代码。
4. 进入赛题目录，例如 `GEMM/`。
5. 执行 `build.sh`。
6. 编译 `submission.mu` 与官方包装代码。
7. 调用 `gemm_optimized` 进行正确性校验、性能 case 校验和性能评测。
8. 将成绩回调到摩尔学院并展示到榜单。

## 注意事项

1. 请勿在仓库中提交账号密码、访问令牌、SSH 私钥等敏感信息。
2. 不要依赖个人本地路径。
3. 正式评测阶段不要依赖联网下载资源。
4. private 仓库必须授权 `MUSA-Operator` 只读访问，并将权限至少保留至正式榜公布及获奖复核结束，否则评测系统可能无法拉取或复测代码。
5. `gemm_optimized` 中禁止调用或链接 muBLAS、muBLASLt、muDNN 或其他能够直接完成本题 GEMM 的高层库、预置算子或等价接口。
6. 本赛季标准提交路径不纳入 MUTLASS、Triton、TileLang 及其他第三方 Kernel 生成框架；除非赛事方另行发布固定版本、编译环境和评测适配说明，否则相关依赖视为未声明的外部依赖。
7. 不建议在 `gemm_optimized` 内进行 `musaMalloc/musaFree` 等动态内存分配；如发生，其耗时计入评测时间。

官方评测器可以在独立参考路径中使用 muBLAS 生成参考结果或进行 sanity check，但这不代表选手代码可以依赖、链接或调用 muBLAS。标准提交路径不接收 Python、Triton、TileLang 或其他 DSL 入口；如未来开放其他框架，赛事方将另行发布版本、镜像、构建命令和 runner 适配要求。