Merge pull request #387 from cheng874/Update-FlagTensor

Update flag tensor

Author: armstrongttwalker-alt

docs/flagtensor_en/overview/overview.md

@@ -4,15 +4,15 @@ FlagTensor is part of [FlagOS](https://flagos.io/), a fully open-source system s
 
 FlagTensor is a high-performance tensor-primitive library implemented in [Triton](https://github.com/openai/triton) language. It provides optimized implementations of common tensor primitives (unary, binary, and tensor contraction operations) benchmarked against [cuTensor](https://developer.nvidia.com/cutensor) baselines, delivering reference-level correctness with competitive performance across diverse GPU architectures.
 
-Built on [FlagTree](https://github.com/flagos-ai/FlagTree) (a FlagOS-maintained Triton fork supporting multiple hardware backends), FlagTensor offers a vendor-agnostic operator interface with pluggable backend support.
+Built on [FlagTree](https://github.com/flagos-ai/FlagTree) (a FlagOS-maintained Triton fork supporting multiple hardware backends), FlagTensor offers a vendor-agnostic operator interface with pluggable backend support. Currently the primary backend is NVIDIA; other vendor backends are registered but not yet fully functional.
 
 ## Features
 
 - Comprehensive collection of tensor primitives: unary (28 ops), binary (4 ops), contraction (3 ops), sparse (1 op)
 - Hand-optimized Triton kernels with per-architecture autotune (Ampere, Hopper)
 - Correctness validated against CPU-FP64 golden reference
 - Performance benchmarked against cuTensor baselines
-- Vendor-agnostic backend abstraction (15 vendors registered)
+- Vendor-agnostic backend abstraction (15 vendors registered; NVIDIA backend primary)
 - Architecture-specific kernel specialization (e.g., `_nvidia/hopper/`, `_nvidia/ampere/`)
 - Per-operator test infrastructure with pytest marks and JSON result recording
 - Multi-GPU parallel test runner with live progress display
@@ -31,18 +31,36 @@ FlagTensor
 │   ├── testing/               # Testing utilities (assertions, shapes, dtypes)
 │   ├── fused/                 # Fused operators
 │   └── modules/               # Module implementations
-├── tests/                     # Per-operator correctness tests
-│   ├── unary/test_CUTENSOR_OP_*.py  # 28 unary operator tests
-│   ├── binary/test_CUTENSOR_OP_*.py  # 4 binary operator tests
-│   ├── contraction/           # Contraction operator tests
-│   └── sparse/                # Sparse operator tests
-├── benchmark/                 # Performance tests
+├── tests/                     # Correctness tests (category-level + per-operator)
+│   ├── unary/
+│   │   ├── test_unary_correctness.py   # Category-level entry (28 unary ops)
+│   │   └── test_CUTENSOR_OP_*.py       # Per-operator tests (28 files)
+│   ├── binary/
+│   │   ├── test_binary_correctness.py  # Category-level entry (4 binary ops)
+│   │   └── test_CUTENSOR_OP_*.py       # Per-operator tests (4 files)
+│   ├── contraction/
+│   │   ├── test_contraction_correctness.py  # Category-level entry (3 contraction ops)
+│   │   ├── test_Contraction.py
+│   │   ├── test_ContractionTrinary.py
+│   │   └── test_ElementwiseTrinary.py
+│   └── sparse/
+│       ├── test_sparse_correctness.py   # Category-level entry (1 sparse op)
+│       └── test_BlockSparseContraction.py
+├── benchmark/                 # Performance tests (category-level + per-operator)
 │   ├── consts.py              # Dtypes, shapes, metrics definitions
-│   └── test_<category>_perf.py
+│   ├── test_unary_perf.py     # Category-level: 28 unary operators
+│   ├── test_binary_perf.py    # Category-level: 4 binary operators
+│   ├── test_contraction_perf.py  # Category-level: 3 contraction operators
+│   ├── test_sparse_perf.py    # Category-level: 1 sparse operator
+│   └── test_CUTENSOR_OP_*_perf.py  # Per-operator benchmark files
 ├── tools/                     # CLI tooling
 │   ├── run_tests.py           # Multi-GPU test runner
+│   ├── run_flagtensor_ci.py   # CI runner (smoke/acceptance correctness & perf)
+│   ├── run_flagtensor_weekly.py  # Weekly regression runner
 │   ├── get_marks.py           # Extract pytest marks from YAML
-│   └── summary_for_plot.py    # Parse & aggregate benchmark logs
+│   ├── summary_for_plot.py    # Parse & aggregate benchmark logs
+│   ├── generate_flagtensor_html_report.py  # HTML report generator
+│   └── export_env.py          # Environment export for reproducibility
 ├── conf/
 │   └── operators.yaml         # Operator registry (authoritative test entry point)
 ├── docs/                      # Documentation

docs/flagtensor_en/reference/benchmark_policy.md

@@ -71,7 +71,7 @@ Current category entry points (all four complete):
 
 - `benchmark/test_unary_perf.py` — 28 unary operators
 - `benchmark/test_binary_perf.py` — 4 binary operators
-- `benchmark/test_contraction_perf.py` — 5 contraction operators
+- `benchmark/test_contraction_perf.py` — 3 contraction operators
 - `benchmark/test_sparse_perf.py` — 1 sparse operator
 
 Legacy per-operator benchmark files (`benchmark/test_CUTENSOR_OP_*_perf.py`) are retained as

docs/flagtensor_en/reference/reference.md

@@ -9,7 +9,7 @@ This section contains the FlagTensor acceptance documentation, covering policies
 | [Benchmark Policy](benchmark_policy.md) | Defines benchmark goals, execution modes (smoke/acceptance/weekly), shape/dtype policy, timing policy, and reporting policy for performance validation. |
 | [CI Matrix](ci_matrix.md) | Describes all CI/CD workflows (quality-gate, ci, weekly, acceptance) with job details, parameters, artifact storage, and cluster GPU validation. |
 | [Known Issues](known_issues.md) | Tracks experimental operators, CI limitations, dtype/shape coverage gaps, performance notes, migration status, and future work. |
-| [Operator Coverage](operator_coverage.md) | Per-operator implementation, correctness, and benchmark coverage matrix across all 38 operators (28 unary, 4 binary, 5 contraction, 1 sparse). |
+| [Operator Coverage](operator_coverage.md) | Per-operator implementation, correctness, and benchmark coverage matrix across all 36 operators (28 unary, 4 binary, 3 contraction, 1 sparse). |
 | [Standard Commands](standard_commands.md) | Standard commands for running acceptance checks: static quality, correctness testing, performance testing, weekly regression, registry operations, and GPU cluster validation. |
 
 ```{toctree}

docs/flagtensor_en/user_guide/user-guide.md

@@ -8,7 +8,7 @@ FlagTensor integrates directly with PyTorch. Import the package and call operato
 import torch
 import flagtensor
 
-# Element-wise operations
+# Element-wise (unary) operations
 x = torch.randn(1024, device="cuda", dtype=torch.float32)
 y = flagtensor.abs(x)
 z = flagtensor.relu(x)
@@ -18,11 +18,21 @@ w = flagtensor.sigmoid(x)
 a = torch.randn(1024, device="cuda")
 b = torch.randn(1024, device="cuda")
 c = flagtensor.add(a, b)
+d = flagtensor.mul(a, b)
 
 # Tensor contraction
 m = torch.randn(64, 32, device="cuda")
 n = torch.randn(32, 48, device="cuda")
 r = flagtensor.contraction(m, n)
+
+# Trinary contraction
+p = torch.randn(64, 32, device="cuda")
+q = torch.randn(32, 48, device="cuda")
+s = torch.randn(64, 48, device="cuda")
+t = flagtensor.contraction_trinary(p, q, s)
+
+# Element-wise trinary
+u = flagtensor.elementwise_trinary(a, b, c)
 ```
 
 ## Operator List
@@ -33,13 +43,22 @@ The complete operator registry is maintained at [FlagTensor conf/operators.yaml]
 |---|---|---|
 | **Unary** | abs, acos, acosh, asin, asinh, atan, atanh, ceil, conj, cos, cosh, exp, floor, identity, log, mish, neg, rcp, relu, sigmoid, sin, sinh, soft_plus, soft_sign, sqrt, swish, tan, tanh | stable |
 | **Binary** | add, max, min, mul | stable |
-| **Contraction** | contraction, contraction_trinary, elementwise_trinary | stable |
+| **Contraction** | contraction, elementwise_trinary | stable |
+| **Contraction** | contraction_trinary | active |
 | **Sparse** | block_sparse_contraction | experimental |
 
 ## Run Tests
 
+### Correctness Tests
+
 ```bash
-# Single operator correctness test
+# Category-level correctness (primary acceptance interface)
+pytest tests/unary/test_unary_correctness.py -v
+pytest tests/binary/test_binary_correctness.py -v
+pytest tests/contraction/test_contraction_correctness.py -v
+pytest tests/sparse/test_sparse_correctness.py -v
+
+# Single operator correctness test (per-operator file)
 pytest tests/unary/test_CUTENSOR_OP_ABS.py -v
 
 # Record test results as JSON (using CPU-FP64 reference)
@@ -50,11 +69,39 @@ python tools/run_tests.py --stages stable --gpus 0,1
 
 # Extract operator marks
 python tools/get_marks.py --stage stable --output ops.txt
+```
+
+### Performance Tests
+
+```bash
+# Category-level benchmark (primary acceptance interface)
+pytest benchmark/test_unary_perf.py -m CUTENSOR_OP_ABS --mode kernel --level core --record log
+pytest benchmark/test_binary_perf.py -m CUTENSOR_OP_ADD --mode kernel --level core --record log
+pytest benchmark/test_contraction_perf.py -m Contraction --mode kernel --level core --record log
+pytest benchmark/test_sparse_perf.py -m BlockSparseContraction --mode kernel --level core --record log
 
-# Benchmark with recording
-pytest benchmark/test_unary_perf.py -m CUTENSOR_OP_ABS \
-  --mode kernel --level core --record log
+# Per-operator benchmark (legacy/debug)
+pytest benchmark/test_CUTENSOR_OP_ABS_perf.py --mode kernel --level core --record log
 
 # Parse benchmark summary
 python tools/summary_for_plot.py result-*.log
 ```
+
+### CI Runner
+
+```bash
+# Smoke correctness
+python tools/run_flagtensor_ci.py --smoke --run-correctness --results-dir ci_results_correctness --dump-json-summary
+
+# Smoke performance
+python tools/run_flagtensor_ci.py --smoke --run-perf --results-dir ci_results_perf --dump-json-summary
+
+# Acceptance correctness (full coverage)
+python tools/run_flagtensor_ci.py --run-correctness --results-dir acceptance_results_correctness --dump-json-summary
+
+# Acceptance performance (full coverage)
+python tools/run_flagtensor_ci.py --run-perf --results-dir acceptance_results_perf --dump-json-summary
+
+# Weekly regression
+python tools/run_flagtensor_weekly.py --project-root . --results-dir weekly_results --gpus 0 --mode kernel
+```

docs/flagtensor_zh/overview/overview.md

@@ -4,15 +4,15 @@ FlagTensor 是 [FlagOS](https://flagos.io/) 的组成部分。FlagOS 是一个
 
 FlagTensor 是一个使用 [Triton](https://github.com/openai/triton) 语言实现的高性能张量原语库。它提供常见张量原语（一元、二元和张量收缩操作）的优化实现，以 [cuTensor](https://developer.nvidia.com/cutensor) 基线为基准，在不同 GPU 架构上提供参考级正确性和具有竞争力的性能。
 
-FlagTensor 构建在 [FlagTree](https://github.com/flagos-ai/FlagTree)（FlagOS 维护的 Triton 分支，支持多种硬件后端）之上，提供与供应商无关的算子接口和可插拔后端支持。
+FlagTensor 构建在 [FlagTree](https://github.com/flagos-ai/FlagTree)（FlagOS 维护的 Triton 分支，支持多种硬件后端）之上，提供与供应商无关的算子接口和可插拔后端支持。当前主要后端为 NVIDIA；其他供应商后端已注册但功能尚未完全就绪。
 
 ## 特性
 
 - 全面的张量原语集合：一元（28 个算子）、二元（4 个算子）、收缩（3 个算子）、稀疏（1 个算子）
 - 手工优化的 Triton 内核，支持按架构自动调优（Ampere、Hopper）
 - 基于 CPU-FP64 金标准参考验证正确性
 - 以 cuTensor 基线为基准进行性能基准测试
-- 与供应商无关的后端抽象（已注册 15 家供应商）
+- 与供应商无关的后端抽象（已注册 15 家供应商；NVIDIA 后端为主要后端）
 - 架构特定的内核特化（如 `_nvidia/hopper/`、`_nvidia/ampere/`）
 - 每个算子的测试基础设施，支持 pytest 标记和 JSON 结果记录
 - 多 GPU 并行测试运行器，带实时进度显示
@@ -31,18 +31,36 @@ FlagTensor
 │   ├── testing/               # 测试工具（断言、形状、dtype）
 │   ├── fused/                 # 融合算子
 │   └── modules/               # 模块实现
-├── tests/                     # 每个算子的正确性测试
-│   ├── unary/test_CUTENSOR_OP_*.py  # 28 个一元算子测试
-│   ├── binary/test_CUTENSOR_OP_*.py  # 4 个二元算子测试
-│   ├── contraction/           # 收缩算子测试
-│   └── sparse/                # 稀疏算子测试
-├── benchmark/                 # 性能测试
+├── tests/                     # 正确性测试（分类级 + 每个算子）
+│   ├── unary/
+│   │   ├── test_unary_correctness.py   # 分类级入口（28 个一元算子）
+│   │   └── test_CUTENSOR_OP_*.py       # 每个算子测试（28 个文件）
+│   ├── binary/
+│   │   ├── test_binary_correctness.py  # 分类级入口（4 个二元算子）
+│   │   └── test_CUTENSOR_OP_*.py       # 每个算子测试（4 个文件）
+│   ├── contraction/
+│   │   ├── test_contraction_correctness.py  # 分类级入口（3 个收缩算子）
+│   │   ├── test_Contraction.py
+│   │   ├── test_ContractionTrinary.py
+│   │   └── test_ElementwiseTrinary.py
+│   └── sparse/
+│       ├── test_sparse_correctness.py   # 分类级入口（1 个稀疏算子）
+│       └── test_BlockSparseContraction.py
+├── benchmark/                 # 性能测试（分类级 + 每个算子）
 │   ├── consts.py              # Dtype、形状、指标定义
-│   └── test_<category>_perf.py
+│   ├── test_unary_perf.py     # 分类级：28 个一元算子
+│   ├── test_binary_perf.py    # 分类级：4 个二元算子
+│   ├── test_contraction_perf.py  # 分类级：3 个收缩算子
+│   ├── test_sparse_perf.py    # 分类级：1 个稀疏算子
+│   └── test_CUTENSOR_OP_*_perf.py  # 每个算子的基准测试文件
 ├── tools/                     # CLI 工具
 │   ├── run_tests.py           # 多 GPU 测试运行器
+│   ├── run_flagtensor_ci.py   # CI 运行器（冒烟/验收正确性与性能）
+│   ├── run_flagtensor_weekly.py  # 每周回归运行器
 │   ├── get_marks.py           # 从 YAML 提取 pytest 标记
-│   └── summary_for_plot.py    # 解析和聚合基准测试日志
+│   ├── summary_for_plot.py    # 解析和聚合基准测试日志
+│   ├── generate_flagtensor_html_report.py  # HTML 报告生成器
+│   └── export_env.py          # 环境导出用于可复现性
 ├── conf/
 │   └── operators.yaml         # 算子注册表（权威测试入口点）
 ├── docs/                      # 文档

docs/flagtensor_zh/reference/benchmark_policy.md

@@ -71,7 +71,7 @@
 
 - `benchmark/test_unary_perf.py` —— 28 个一元算子
 - `benchmark/test_binary_perf.py` —— 4 个二元算子
-- `benchmark/test_contraction_perf.py` —— 5 个收缩算子
+- `benchmark/test_contraction_perf.py` —— 3 个收缩算子
 - `benchmark/test_sparse_perf.py` —— 1 个稀疏算子
 
 旧版每个算子的基准测试文件（`benchmark/test_CUTENSOR_OP_*_perf.py`）保留为

docs/flagtensor_zh/reference/reference.md

@@ -9,7 +9,7 @@
 | [基准测试策略](benchmark_policy.md) | 定义性能验证的基准测试目标、执行模式（冒烟/验收/每周）、形状/dtype 策略、计时策略和报告策略。 |
 | [CI 矩阵](ci_matrix.md) | 描述所有 CI/CD 工作流（质量门、ci、每周、验收），包括作业详情、参数、工件存储和集群 GPU 验证。 |
 | [已知问题](known_issues.md) | 跟踪实验性算子、CI 限制、dtype/形状覆盖差距、性能说明、迁移状态和未来工作。 |
-| [算子覆盖率](operator_coverage.md) | 全部 38 个算子（28 个一元、4 个二元、5 个收缩、1 个稀疏）的每个算子实现、正确性和基准测试覆盖率矩阵。 |
+| [算子覆盖率](operator_coverage.md) | 全部 36 个算子（28 个一元、4 个二元、3 个收缩、1 个稀疏）的每个算子实现、正确性和基准测试覆盖率矩阵。 |
 | [标准命令](standard_commands.md) | 运行验收检查的标准命令：静态质量、正确性测试、性能测试、每周回归、注册表操作和 GPU 集群验证。 |
 
 ```{toctree}

docs/flagtensor_zh/user_guide/user-guide.md

@@ -8,7 +8,7 @@ FlagTensor 直接与 PyTorch 集成。导入包并对 CUDA 张量调用算子：
 import torch
 import flagtensor
 
-# 逐元素操作
+# 逐元素（一元）操作
 x = torch.randn(1024, device="cuda", dtype=torch.float32)
 y = flagtensor.abs(x)
 z = flagtensor.relu(x)
@@ -18,11 +18,21 @@ w = flagtensor.sigmoid(x)
 a = torch.randn(1024, device="cuda")
 b = torch.randn(1024, device="cuda")
 c = flagtensor.add(a, b)
+d = flagtensor.mul(a, b)
 
 # 张量收缩
 m = torch.randn(64, 32, device="cuda")
 n = torch.randn(32, 48, device="cuda")
 r = flagtensor.contraction(m, n)
+
+# 三元收缩
+p = torch.randn(64, 32, device="cuda")
+q = torch.randn(32, 48, device="cuda")
+s = torch.randn(64, 48, device="cuda")
+t = flagtensor.contraction_trinary(p, q, s)
+
+# 逐元素三元操作
+u = flagtensor.elementwise_trinary(a, b, c)
 ```
 
 ## 算子列表
@@ -33,13 +43,22 @@ r = flagtensor.contraction(m, n)
 |---|---|---|
 | **一元** | abs、acos、acosh、asin、asinh、atan、atanh、ceil、conj、cos、cosh、exp、floor、identity、log、mish、neg、rcp、relu、sigmoid、sin、sinh、soft_plus、soft_sign、sqrt、swish、tan、tanh | stable |
 | **二元** | add、max、min、mul | stable |
-| **收缩** | contraction、contraction_trinary、elementwise_trinary | stable |
+| **收缩** | contraction、elementwise_trinary | stable |
+| **收缩** | contraction_trinary | active |
 | **稀疏** | block_sparse_contraction | experimental |
 
 ## 运行测试
 
+### 正确性测试
+
 ```bash
-# 单个算子正确性测试
+# 分类级正确性（主要验收接口）
+pytest tests/unary/test_unary_correctness.py -v
+pytest tests/binary/test_binary_correctness.py -v
+pytest tests/contraction/test_contraction_correctness.py -v
+pytest tests/sparse/test_sparse_correctness.py -v
+
+# 单个算子正确性测试（每个算子文件）
 pytest tests/unary/test_CUTENSOR_OP_ABS.py -v
 
 # 记录测试结果为 JSON（使用 CPU-FP64 参考）
@@ -50,11 +69,39 @@ python tools/run_tests.py --stages stable --gpus 0,1
 
 # 提取算子标记
 python tools/get_marks.py --stage stable --output ops.txt
+```
+
+### 性能测试
+
+```bash
+# 分类级基准测试（主要验收接口）
+pytest benchmark/test_unary_perf.py -m CUTENSOR_OP_ABS --mode kernel --level core --record log
+pytest benchmark/test_binary_perf.py -m CUTENSOR_OP_ADD --mode kernel --level core --record log
+pytest benchmark/test_contraction_perf.py -m Contraction --mode kernel --level core --record log
+pytest benchmark/test_sparse_perf.py -m BlockSparseContraction --mode kernel --level core --record log
 
-# 带记录的基准测试
-pytest benchmark/test_unary_perf.py -m CUTENSOR_OP_ABS \
-  --mode kernel --level core --record log
+# 每个算子基准测试（旧版/调试）
+pytest benchmark/test_CUTENSOR_OP_ABS_perf.py --mode kernel --level core --record log
 
 # 解析基准测试摘要
 python tools/summary_for_plot.py result-*.log
 ```
+
+### CI 运行器
+
+```bash
+# 冒烟正确性
+python tools/run_flagtensor_ci.py --smoke --run-correctness --results-dir ci_results_correctness --dump-json-summary
+
+# 冒烟性能
+python tools/run_flagtensor_ci.py --smoke --run-perf --results-dir ci_results_perf --dump-json-summary
+
+# 验收正确性（完整覆盖率）
+python tools/run_flagtensor_ci.py --run-correctness --results-dir acceptance_results_correctness --dump-json-summary
+
+# 验收性能（完整覆盖率）
+python tools/run_flagtensor_ci.py --run-perf --results-dir acceptance_results_perf --dump-json-summary
+
+# 每周回归
+python tools/run_flagtensor_weekly.py --project-root . --results-dir weekly_results --gpus 0 --mode kernel
+```