Skip to content

Commit 338193d

Browse files
armstrongttwalker-altarmstrongttwalker-alt
authored
Merge pull request #352 from cheng874/6-domain-specific-lib
3rd wave of translation
2 parents 0ca8da9 + 1086644 commit 338193d

32 files changed

Lines changed: 2708 additions & 0 deletions

‎docs/zh/flagfft_zh/getting_started/getting-started.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# FlagFFT 快速入门
2+
3+
```{toctree}
4+
:maxdepth: 2
5+
6+
requirements.md
7+
install.md
8+
```

‎docs/zh/flagfft_zh/getting_started/install.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# 安装 FlagFFT
2+
3+
## 快速开始
4+
5+
克隆、构建并一步验证：
6+
7+
```sh
8+
# 1. 克隆
9+
git clone https://github.com/flagos-ai/FlagFFT.git
10+
cd FlagFFT
11+
12+
# 2. 初始化子模块
13+
git submodule update --init --recursive
14+
15+
# 3. 构建库、CLI 和测试二进制文件
16+
cmake -B build -DCMAKE_BUILD_TYPE=Release \
17+
-DFLAGFFT_BUILD_CLI=ON \
18+
-DFLAGFFT_BUILD_TESTS=ON
19+
cmake --build build -j$(nproc)
20+
21+
# 4. 安装 Python 代码生成包（JIT 内核生成所需）
22+
pip install .
23+
24+
# 5. 运行完整的精度 + 性能测试套件
25+
python tools/run_tests.py --combination full --gpus 0
26+
```
27+
28+
运行器会打印实时进度表，并写入 `summary.json`，其中包含每个算子的精度（通过/失败）和性能（相对于 cuFFT 的几何平均加速比）结果。
29+
30+
## 构建选项
31+
32+
| 选项 | 默认值 | 描述 |
33+
|---|---|---|
34+
| `FLAGFFT_BUILD_CLI` | `OFF` | 构建 `flagfft-cli` 基准测试/验证工具 |
35+
| `FLAGFFT_BUILD_TESTS` | `OFF` | 构建 C++ 测试套件（需要 Google Test + CUDA） |
36+
| `BACKEND` | `CUDA` | GPU 后端选择器（目前仅支持 `CUDA`） |
37+
| `CMAKE_BUILD_TYPE` | — | `Release`、`Debug`、`RelWithDebInfo` |
38+
39+
### 仅构建库
40+
41+
```sh
42+
cmake -B build -DCMAKE_BUILD_TYPE=Release
43+
cmake --build build -j$(nproc)
44+
```
45+
46+
这将生成 `build/libflagfft.so`。
47+
48+
### 构建库 + CLI + 测试
49+
50+
```sh
51+
cmake -B build -DCMAKE_BUILD_TYPE=Release \
52+
-DFLAGFFT_BUILD_CLI=ON \
53+
-DFLAGFFT_BUILD_TESTS=ON
54+
cmake --build build -j$(nproc)
55+
```
56+
57+
## 安装到系统（可选）
58+
59+
构建后，将库和工具安装到系统范围：
60+
61+
```sh
62+
cmake --install build --prefix /usr/local
63+
```
64+
65+
将 `libflagfft.so` 安装到 `lib/`，公共头文件 `flagfft.h` 安装到 `include/`，`flagfft-cli` 安装到 `bin/`（如果使用 `-DFLAGFFT_BUILD_CLI=ON` 构建）。
66+
67+
## 使用 Docker
68+
69+
预构建的包含所有依赖的环境可作为手动设置的替代方案：
70+
71+
```sh
72+
docker build -t flagfft-dev -f docker/Dockerfile .
73+
docker run --gpus all -v $(pwd):/workspace/FlagFFT -it flagfft-dev
74+
# 在容器内，运行快速开始中的构建和测试步骤。
75+
```
76+
77+
## 设置环境变量
78+
79+
| 变量 | 描述 |
80+
|---|---|
81+
| `FLAGFFT_PYTHON` | JIT 代码生成使用的 Python 解释器路径（默认：PATH 中的 `python3`） |
82+
| `FLAGFFT_TUNE_DB` | SQLite 调优数据库路径（默认：`~/.flagfft/tune.db`） |
83+
| `FLAGFFT_TUNE_DISABLE` | 设置为 `1` 以禁用调优计划查找，始终使用自动选择的计划 |

‎docs/zh/flagfft_zh/getting_started/requirements.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# 安装要求
2+
3+
## 硬件
4+
5+
- 支持 CUDA 的 NVIDIA GPU。
6+
7+
## 依赖
8+
9+
您可以准备一个包含以下依赖的 Docker 环境。更多信息请参见[快速开始](/getting_started/install.md)。
10+
11+
### 必需依赖
12+
13+
| 依赖 | 最低版本 | 说明 |
14+
|---|---|---|
15+
| CMake | 3.18 | 构建系统 |
16+
| C++ 编译器 | C++20 支持 | GCC 11+、Clang 14+ |
17+
| Python | 3.12 | JIT 代码生成 + 测试运行器 |
18+
| flagtree | 0.5.0 | Triton TLE 支持 |
19+
| SQLite3 | — | 调优数据库 |
20+
| CUDA Toolkit | 12.x | cudart、cuFFT（用于测试适配器/基准测试） |
21+
| libtriton_jit | 子模块 | Triton JIT 编译器（`deps/libtriton_jit`） |
22+
| PyYAML | — | 测试运行器（`pip install pyyaml`） |
23+
24+
### 可选依赖
25+
26+
| 依赖 | 用途 |
27+
|---|---|
28+
| Google Test | C++ 单元测试（当 `FLAGFFT_BUILD_TESTS=ON` 时通过 FetchContent 自动获取） |
29+
| Ninja | 更快的构建后端（`cmake -G Ninja`） |
30+
| pytest | Python 代码生成测试 |
31+
32+
## 子模块
33+
34+
```bash
35+
git submodule update --init --recursive
36+
```
37+
38+
这将拉取 `deps/libtriton_jit`，提供 Triton JIT 编译器和 `nlohmann_json`。更多信息请参见[快速开始](/getting_started/install.md)。

‎docs/zh/flagfft_zh/index.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# FlagFFT 文档
2+
3+
```{button-ref} getting_started/getting-started
4+
:ref-type: myst
5+
:color: primary
6+
:class: sd-btn-lg sd-px-4 sd-py-2 sd-fw-bold
7+
8+
快速入门
9+
```
10+
11+
::::{grid} 1 2 2 3
12+
:gutter: 1 1 1 2
13+
14+
:::{grid-item-card} {octicon}`browser;1.5em;sd-mr-1` 概览
15+
:link: overview/overview
16+
:link-type: doc
17+
18+
快速了解 FlagFFT 的架构和基本概念。
19+
20+
+++
21+
[了解更多 »](overview/overview.md)
22+
:::
23+
24+
:::{grid-item-card} {octicon}`book;1.5em;sd-mr-1` 快速入门
25+
:link: getting_started/getting-started
26+
:link-type: doc
27+
28+
查看 FlagFFT 的安装要求，并分步安装。
29+
30+
+++
31+
[了解更多 »](getting_started/getting-started.md)
32+
:::
33+
34+
:::{grid-item-card} {octicon}`broadcast;1.5em;sd-mr-1` 用户指南
35+
:link: user_guide/user-guide
36+
:link-type: doc
37+
38+
使用 C API、CLI 和测试运行器。
39+
40+
+++
41+
[了解更多 »](user_guide/user-guide.md)
42+
:::
43+
44+
:::{grid-item-card} {octicon}`code;1.5em;sd-mr-1` API 参考
45+
:link: reference/api-reference
46+
:link-type: doc
47+
48+
FlagFFT 函数和类型的 C API 参考。
49+
50+
+++
51+
[了解更多 »](reference/api-reference.md)
52+
:::
53+
54+
:::{grid-item-card} {octicon}`gear;1.5em;sd-mr-1` TLE 参考
55+
:link: reference/tle-reference
56+
:link-type: doc
57+
58+
编写 Triton 内核时使用的 FlagTree/TLE API 参考。
59+
60+
+++
61+
[了解更多 »](reference/tle-reference.md)
62+
:::
63+
64+
::::
65+
66+
---
67+
68+
```{toctree}
69+
:caption: 📑 发布说明
70+
:maxdepth: 5
71+
:hidden:
72+
73+
release_notes/release-notes.md
74+
```
75+
76+
```{toctree}
77+
:caption: 📚 指南
78+
:maxdepth: 5
79+
:hidden:
80+
81+
overview/overview.md
82+
getting_started/getting-started.md
83+
getting_started/requirements.md
84+
getting_started/install.md
85+
user_guide/user-guide.md
86+
```
87+
88+
```{toctree}
89+
:caption: 📖 参考
90+
:maxdepth: 5
91+
:hidden:
92+
93+
reference/api-reference.md
94+
reference/tle-reference.md
95+
```

‎docs/zh/flagfft_zh/overview/overview.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# FlagFFT 概览
2+
3+
FlagFFT 是一个实验性的 C++ FFT 库，提供与 cuFFT 风格兼容的 API 以及基于 Triton/TLE 生成的 CUDA 内核。公开的运行时接口为 C 语言；Python 仅用于 Triton/TLE JIT 源码生成（内部代码生成）。
4+
5+
FlagFFT 是 [FlagOS](https://flagos.io/) 生态系统的组成部分，为科学计算、信号处理和机器学习工作负载提供高性能 FFT 计算。
6+
7+
## 特性
8+
9+
- **cuFFT 风格 API** —— 为从 cuFFT 迁移的开发者提供熟悉的计划创建和执行接口。
10+
- **JIT 内核编译** —— 内核在计划创建时通过 Triton/TLE 生成，消除执行时的 Python 编译延迟。
11+
- **任意长度的一维和二维变换** —— 通过融合四步路径支持任意复合长度，包括超大尺寸（如 n = 2^23），无需回退到 Bluestein。二维 FFT 支持全部六种变换类型。
12+
- **多种变换类型** —— C2C、Z2Z（复数），R2C、D2Z、C2R、Z2D（实数到复数及其逆变换）。
13+
- **计划描述** —— `flagfftGetPlanDescription` 返回计划节点树、内核名称和编译详情的详细信息，用于性能调试。
14+
- **原生 CLI** —— `flagfft-cli` 提供基准测试测量和计划检查功能，无需 Python 开销。
15+
16+
## 架构
17+
18+
### C++ 运行时
19+
20+
| 模块 | 描述 |
21+
|---|---|
22+
| `include/flagfft.h` | cuFFT 风格的不透明句柄 API，后端中立的 `flagfftStream_t` |
23+
| `src/exec/` | `flagfftHandle` 生命周期、计划创建、流状态、计划缓存、原始指针执行调度 |
24+
| `src/plan/` | 将 `FFTRequest` 映射为 `PlanNode` 树 —— 节点、因子分解、成本、自动候选、调优候选 |
25+
| `src/codegen/` | 在计划创建期间调用 Python Triton/TLE 源码生成，通过 libtriton_jit 编译 |
26+
| `python/flagfft_codegen/` | 可通过 pip 安装的源码生成器和绑定的 codelet |
27+
| `src/adaptor/` | 设备分配、流/事件操作、目标标识、能力查询（CUDA Driver 后端） |
28+
| `src/utils/` | 共享的请求/键工具、JSON/SQLite 调优支持 |
29+
30+
### 原始执行节点
31+
32+
- `CompiledRawLeafNode` —— 使用计划拥有的旋转因子和 DFT 表分配启动连续叶子内核。
33+
- `CompiledRawFourStepFusedNode` —— 带有行和列叶子子节点的四步路径，拥有旋转因子和中间缓冲区。
34+
- `CompiledRawBluesteinNode` —— 通过 JIT 准备、逐点、最终化和卷积 FFT 子内核处理质数和复杂复合长度。
35+
- `CompiledRaw2DNode` —— 连续复数二维计划，采用 RTRT 路径（行 FFT → 分块转置 → 行 FFT → 分块转置回）。
36+
37+
### CLI 工具
38+
39+
`src/cli_tools/common/` 拥有 `CaseSpec`、确定性缓冲区生成、FlagFFT/cuFFT 调度和比较。cuFFT 仅在 CLI 中用作 CUDA 验证/性能基准。
40+
41+
- `bench` —— 在预热和计时前将 FlagFFT 和 cuFFT 参考计划绑定到一个适配器流。
42+
- `tune` —— 占位符；退出并返回 `FLAGFFT_NOT_SUPPORTED`。
43+
44+
### 构建选项
45+
46+
| 选项 | 默认值 | 描述 |
47+
|---|---|---|
48+
| `FLAGFFT_BUILD_CLI` | `OFF` | 构建 `flagfft-cli` 及其 cuFFT 依赖 |
49+
| `FLAGFFT_BUILD_TESTS` | `OFF` | 构建 `ctest/` 下的 Google Test 目标 |
50+
| `BACKEND` | `CUDA` | GPU 后端选择器（目前仅支持 `CUDA`） |
51+
52+
### Python 边界
53+
54+
原生运行时调用 `python -m flagfft_codegen.jit_source`；所选的 Python 环境必须提供兼容的 Triton/TLE 依赖。生成的 JIT 源码/元数据存放在可执行文件旁边的 `.flagfft` 中。
55+
56+
### 测试
57+
58+
- `ctest/` —— 所有算子的 Google Test 精度测试。
59+
- `tools/run_tests.py` —— 统一测试运行器，协调多 GPU 的精度和性能测试。
60+
- `tests/python/` —— 代码生成测试。
61+
62+
## 工作流程
63+
64+
1. 使用 `flagfftPlan1d`（或 `flagfftPlanMany` 用于批量变换）创建 FFT 计划。
65+
2. 可选地使用 `flagfftSetStream` 附加 CUDA 流。
66+
3. 使用 `flagfftExec*` 函数执行变换。
67+
4. 使用 `flagfftDestroy` 销毁计划。

‎docs/zh/flagfft_zh/reference/api-reference.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# FlagFFT C API 参考
2+
3+
## 计划创建
4+
5+
| 函数 | 描述 |
6+
|----------|-------------|
7+
| `flagfftPlan1d` | 创建一维 FFT 计划 |
8+
| `flagfftPlan2d` | 创建二维 FFT 计划（目前返回 `FLAGFFT_NOT_SUPPORTED`） |
9+
| `flagfftPlan3d` | 创建三维 FFT 计划（目前返回 `FLAGFFT_NOT_SUPPORTED`） |
10+
| `flagfftPlanMany` | 创建具有自定义布局的批量 FFT 计划 |
11+
12+
## 执行
13+
14+
| 函数 | 描述 |
15+
|----------|-------------|
16+
| `flagfftExecC2C` | 复数到复数变换（complex64） |
17+
| `flagfftExecZ2Z` | 复数到复数变换（complex128） |
18+
| `flagfftExecR2C` | 实数到复数变换（float） |
19+
| `flagfftExecD2Z` | 实数到复数变换（double） |
20+
| `flagfftExecC2R` | 复数到实数变换（float） |
21+
| `flagfftExecZ2D` | 复数到实数变换（double） |
22+
23+
## 流和生命周期
24+
25+
| 函数 | 描述 |
26+
|----------|-------------|
27+
| `flagfftSetStream` | 将 CUDA 流附加到计划 |
28+
| `flagfftDestroy` | 销毁计划并释放资源 |
29+
| `flagfftGetPlanDescription` | 获取人类可读的计划描述 |
30+
31+
## 类型
32+
33+
| 类型 | 描述 |
34+
|------|-------------|
35+
| `flagfftHandle` | 不透明计划句柄 |
36+
| `flagfftResult` | 返回状态码 |
37+
| `flagfftStream_t` | 后端中立的不透明流类型 |
38+
| `flagfftComplex` | 单精度复数 |
39+
| `flagfftDoubleComplex` | 双精度复数 |
40+
41+
## 变换类型
42+
43+
| 常量 | 描述 |
44+
|----------|-------------|
45+
| `FLAGFFT_C2C` | 复数到复数（complex64） |
46+
| `FLAGFFT_Z2Z` | 复数到复数（complex128） |
47+
| `FLAGFFT_R2C` | 实数到复数（float） |
48+
| `FLAGFFT_D2Z` | 实数到复数（double） |
49+
| `FLAGFFT_C2R` | 复数到实数（float） |
50+
| `FLAGFFT_Z2D` | 复数到实数（double） |
51+
52+
## 状态码
53+
54+
| 常量 | 描述 |
55+
|----------|-------------|
56+
| `FLAGFFT_SUCCESS` | 操作成功完成 |
57+
| `FLAGFFT_NOT_SUPPORTED` | 请求的操作不受支持 |

0 commit comments

Comments
 (0)