TTNN 与 Metalium：不同抽象保留同一份数学合同

先问要控制什么，再选接口

假设A为1、2、3、4，B为10、20、30、40，目标是逐项加法。高层接口让你表达“对两个tensor做add”，库负责选择并安排实现；低层接口让你更直接控制kernel、数据搬运、buffer与工作分布。两者的数学合同可以相同，开发和调试所需处理的细节却不同。

TTNN提供较高层的tensor操作；Metalium暴露更低层的Tensix编程方式。初学不需要为了显得底层而绕过现成算子。标准算子、模型验证和快速建立baseline适合从高层入手；需要新操作、特殊布局或具体瓶颈控制时，再向下深入。选择低层意味着多承担实现正确性，并不自动意味着更快。

Tensor 不只是一段数

Tensor同时涉及shape、dtype、layout及存储位置。Shape描述逻辑维度；dtype决定元素表示与数值精度；layout描述数据排列；memory配置关系到放在哪里、怎样分布。一个转换可能只改元数据，也可能真的复制、打包或改变数值精度，不能仅凭函数名假定零成本。

例一的高层路径用单循环，低层教学路径用两项一组的分块循环。逐元素结果都应为11、22、33、44。这个比较只说明两种原创C++表达实现同一算式，没有运行TTNN或Metalium。例二检查矩阵加法shape合同，主动拒绝两个元素数量相同但行列含义不同的输入。

把真实语法放回生命周期

四次调用，三个 API（补充，另估25分钟）

先读 Python 的外壳：a_tt = 调用(...) 把返回的对象绑定到名字 a_tt；它不是 C++ 的类型声明，也不保证复制对象。ttnn.from_torch 中的 ttnn 是模块名，点号选择其中的函数。device=device 左边是形参名字，右边是先前已有的变量；layout=ttnn.TILE_LAYOUT 同样通过名字传参，其中 TILE_LAYOUT 是模块提供的布局选项。

本片段假定 a_host、b_host 是已准备好的、形状和 dtype 兼容的 torch 张量，device 是可用的目标设备对象。这里只跟踪逻辑上逐项相加的四个值，不据此推断所有设备都支持某个特定 shape 或 dtype。

行	输入与动作	返回值归属
1、2	分别把 host 张量转成指定 device、tile layout 的 TT 张量	a_tt、b_tt 是 Python 名字，引用的 TT 张量数据位于指定设备
3	对这两个 TT 张量做 add	c_tt 接收结果 TT 张量
4	把结果转回 torch 张量	c_host 接收可在 host 检查的结果

**纸上走一次：**给定逻辑输入 A=[1,2,3,4]、B=[10,20,30,40]，先写出两次转换后各张量应代表哪些数，再预测加法和回读应代表 [11,22,33,44]。前两行没有相加，第三行也没有把结果自动赋给 a_host；少了第四行，就没有得到这里命名为 c_host 的回读结果。

转换可能涉及复制、打包、补齐或精度变化，不保证零拷贝。本章 CPU 例二自行采用“shape 必须相等”的窄合同；真实 ttnn.add 还支持规定的广播形式，不能用这个模型替代 API 规则。当前 latest 的 from_torch 将 device 类型列为 MeshDevice，add 默认 BF16 路径可能有最多 1 ULP 的误差（一个可表示数值间距）；因此手算值是比较目标，真实结果须按选定 dtype 与版本检查。

本次只核对公开读法，未运行 SDK。来源为 from_torch、add、to_torch，均为滚动 latest，核对日期 2026-09-08；实验时另记安装的版本。

# TTNN公开API语法示意，未在设备执行。
# 已有兼容device与torch张量；具体dtype/layout支持以安装版本为准。
a_tt = ttnn.from_torch(a_host, device=device, layout=ttnn.TILE_LAYOUT)
b_tt = ttnn.from_torch(b_host, device=device, layout=ttnn.TILE_LAYOUT)
c_tt = ttnn.add(a_tt, b_tt)
c_host = ttnn.to_torch(c_tt)

这个片段隐藏了设备创建与关闭、异常清理、输入dtype选择和误差检查，所以它不是复制即运行的完整程序。真正实验应从官方对应版本完整示例开始，记录环境，然后用自己的小输入建立reference。若存在低精度转换，比较必须针对实际执行的数值合同，而不是要求和无限精度实数运算完全一致。

高层结果可以当什么证据

高层库输出可以作为交叉检查，但最好另有简单而独立的CPU oracle。若两个路径共享同一错误的reshape或同一输入打包函数，它们可能一起算错。使用非对称矩阵、负数、零、边缘shape和易手算值，能比随机大矩阵更快地暴露合同混淆。

一个有效降层过程是先固定高层输入输出，再一次替换一个环节：数据布局、单核实现或分布方式。每一步都重新比较正确性，最后才比较性能。不要同时改dtype、tile布局、kernel和batch大小，否则很难解释差异来自哪里。

什么问题才值得写低层kernel

例如trace显示某标准操作的前后反复转换布局，可能考虑减少转换或融合；某特殊操作没有合适实现，则需要自定义kernel。但如果瓶颈是host准备数据或反复读取结果，重写计算kernel未必有收益。面试讨论时应先说测量观察、假设和选择，再描述API细节。

TTNN、Metalium及其设备接口持续演进，部分历史示例使用旧设备管理方式。阅读时以相同版本的文档、headers和示例为一组，不能混搭旧CreateDevice代码与新mesh对象接口。教材讲的是职责与合同，不将某一版本的函数表当永久架构。

// Original CPU teaching model; not a device simulator or benchmark.
#include <iostream>
#include <vector>
#include <stdexcept>

void require(bool ok) { if (!ok) throw std::runtime_error("model check failed"); }

int main() {
 const std::vector<int> a{1,2,3,4},b{10,20,30,40};
 std::vector<int> oracle(4),candidate(4);
 for(std::size_t i=0;i<4;++i) oracle[i]=a[i]+b[i];
 for(std::size_t tile=0;tile<2;++tile) for(std::size_t j=0;j<2;++j) {
  const auto i=tile*2+j; candidate[i]=a[i]+b[i];
 }
 require(candidate==oracle);
 std::cout<<"result=";
 for(std::size_t i=0;i<4;++i) std::cout<<(i?" ":"")<<candidate[i];
 std::cout<<" match=1\n";
}

clang++ -std=c++20 -Wall -Wextra -Wpedantic -Werror -pthread 38-a.cpp -o example && ./example

result=11 22 33 44 match=1

// Original CPU teaching model; not a device simulator or benchmark.
#include <iostream>
#include <array>
#include <stdexcept>

void require(bool ok) { if (!ok) throw std::runtime_error("model check failed"); }

int main() {
 const std::array<int,2> a{2,3},b{3,2};
 const bool count=a[0]*a[1]==b[0]*b[1];
 const bool compatible=a==b;
 require(count && !compatible);
 std::cout<<"same_count="<<count<<" compatible="<<compatible<<'\n';
}

clang++ -std=c++20 -Wall -Wextra -Wpedantic -Werror -pthread 38-b.cpp -o example && ./example

same_count=1 compatible=0