怎么读这一卷

主线位置：三条主线和 einsum 线的总览。本页把每条线拆成几步，标出每一步落在哪个函数上、哪一页讲它；再逐条核实 README 里「写代码之前必须知道」的五条约定；最后讲 Cargo feature 怎么决定编进来哪个 CPU provider 和哪个 GPU 后端，以及为什么有几个 feature 必须在所有 crate 上一致。「一次 matmul」和「一次 grad」用实验把直接计算主线和 traced 主线各走一遍。

flowchart TB
  start[从这里开始] --> q{读这一卷为了什么}
  q -->|会用| use1["五条约定 再到 01"]
  q -->|读懂实现| all[00 到 11 按顺序]
  q -->|只关心求导| ad["一次 grad 再到 04 05"]
  q -->|只关心 einsum| es["06 einsum 再到 11"]

锁定版本

源码链接一律指向 tag 和上面的 commit：https://github.com/tensor4all/tenferro-rs/blob/v0.8.0/...。crates.io 上的 tenferro-*-0.8.0 包和 tag 是同一份代码（包里的 .cargo_vcs_info.json 写的就是 a9f494cc）。仓库的合并多是 squash，提交标题末尾的 (#NNNN) 就是 PR 号，本卷的「冷知识」都从这里查。仓库的 docs/ 下有大量上游设计文档（architecture/、design/、spec/、guides/），本卷把它们当资料读，引用之前在源码或实验里核实；0.8.0 的不少文档还留着 WebGPU、CubeCL 和 HostTensor 的说法，对不上的地方会写出来。

实测平台是 M2 Max、macOS 27、rustc 1.99.0，只有 CPU。CUDA 后端和 tenferro-xla 只读源码。

三条主线和 einsum 线

每页开头都会标出本页在哪条线上。

直接计算主线：一次 a.matmul(&b, &mut engine)

flowchart TB
  mk["from_vec_col_major"] --> eng["CpuEngine serial 或 new"]
  eng --> mm["matmul 变 dot_general"]
  mm --> ce["cpueinsum 二元计划"]
  ce --> tc["tcontract 选策略"]
  tc --> faer["faer matmul"]
  faer --> read["host_data 借出"]

第 2 步和第 4 步要先记住：engine 是调用方手里的一个普通值，每个运算以 &mut 借它，运算从调用线程开始执行；只有 provider 决定把活分给多个线程时，才用到 engine 里预留的 team（一次 matmul 里 lldb 停在 thread #1，也就是主线程）。

traced 主线：一次 y.grad(&x) 再执行

flowchart TB
  tt["TracedTensor"] --> ops["运算只记图"]
  ops --> gr["grad 变换出新图"]
  gr --> cp["GraphCompiler compile"]
  cp --> rb["Runtime builder 注册"]
  rb --> pr["prepare 按 target"]
  pr --> run["run 借 engine"]
  run --> out["into_tensor"]

和 JAX 一样，求导是对图的变换，产物还是图；要数值就得编译、准备、执行。各步的耗时见一次 grad。

eager 主线：一次 loss.backward(&mut engine)

flowchart TB
  er["EagerRuntime new"] --> var["variable_from"]
  var --> ses["with_eager_session"]
  ses --> op["运算立即执行并记录"]
  op --> bw["backward 借 engine"]
  bw --> g["grad 累加进槽"]
  g --> cl["clear_grad"]

einsum 线

README 的五条约定，逐条核实

README 在 Quickstart 之前列了五条「Conventions you must know before writing code」，0.8.0 的文字和 0.7.1 一字未改。下面每条都配一个程序。conventions 和 intro-chain 两个实验；conventions 是 release，intro-chain 是编不过的 debug 构建。

1. 列主序

原文：「Dense buffers are column-major: the leftmost dimension varies fastest. Row-major data passed to from_vec_col_major is silently reinterpreted as column-major — permuted/wrong values, never rejected.」

把 [[1,2,3],[4,5,6]] 按行写成 vec![1,2,3,4,5,6] 交给 from_vec_col_major(vec![2, 3], ..)，再乘一个全 1 的列向量求行和：

let mut engine = CpuEngine::serial();
let row_major = vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0];
let a = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], row_major.clone())?;
let ones = TypedTensor::<f64>::from_vec_col_major(vec![3, 1], vec![1.0; 3])?;
let sums = a.matmul(&ones, &mut engine)?;
let bridged = Tensor::from_vec_row_major(vec![2, 3], row_major)?;

1. row sums (want [6, 15]): [9.0, 12.0]
1. reordered input:          [6.0, 15.0]
1. Tensor::from_vec_row_major data: [1.0, 4.0, 2.0, 5.0, 3.0, 6.0]

形状和长度对得上，构造就成功，没有任何报错；张量里装的是 [[1,3,5],[2,4,6]]。按列写成 vec![1,4,2,5,3,6] 才是想要的结果。0.8.0 给动态 dtype 的 Tensor 加了 from_vec_row_major，它把行主序数据重排一次再存成列主序（输出第三行）；TypedTensor 上没有这个构造函数。为什么选列主序、行主序数据怎么不拷贝地桥接，见列主序与视图。

2. 没有门面 crate

原文：「cargo add tenferro fails by design; depend on the crates you need」。tag 上工作区的 members 是 16 个 crates/tenferro-*、docs/tutorial-code 和 ext/ 下的四个示例 crate（bf16-proof、df64-proof、scalar-consumer-algorithm、scalar-consumer-application），没有名叫 tenferro 的包。本卷离线写作，cargo add tenferro 在 crates.io 上会怎样没有实测；本机 crates.io 索引缓存里有 16 个 tenferro-* 名字，没有 tenferro。

3. 显式后端

原文：「Direct operations take an explicit backend argument; construct the backend/runtime once and reuse it — per-call construction discards the buffer pool.」

在 0.8.0 的代码里，这个「backend 参数」就是 engine：fn matmul(&self, rhs: &TypedTensor<T>, session: &mut dyn Engine)。参数名还叫 session，但已经没有会话可开了，CpuEngine 直接实现 Engine，&mut engine 传进去即可，只 use tenferro_runtime::prelude::* 就能调。

那么 engine 持有什么？CpuEngine 的字段是：执行资源（线程池或预留的 team、收缩用的工作区）、缓冲池 BufferPool、计划缓存 CpuPlanCache 的句柄、批处理策略、可选的分配域、运行期 engine id、扩展缓存。用同一个 engine 连做三次小 matmul 再看：

let c = a.matmul(&ones, &mut engine)?;
println!("3. pool before drop: {:?}", engine.buffer_pool_stats());
drop(c);
println!("3. pool after drop:  {:?}", engine.buffer_pool_stats());
println!("3. runtime cache:    {:?}", engine.runtime_cache_stats());
let fresh = CpuEngine::serial();
println!("3. fresh engine pool: {:?}", fresh.buffer_pool_stats());

3. pool before drop: BufferPoolStats { buffers: 0, capacity_bytes: 0 }
3. pool after drop:  BufferPoolStats { buffers: 1, capacity_bytes: 16 }
3. runtime cache:    CacheStats { entries: 2, retained_bytes: 717136, hits: 2, misses: 1, evictions: 0, clears: 0 }
3. fresh engine pool: BufferPoolStats { buffers: 0, capacity_bytes: 0 }

结果张量一 drop，它的 Vec 就经一个弱引用回到产生它的 engine 的缓冲池（存储里记着 Weak<dyn HostBufferRecycler<T>>，见存储与所有权）。计划缓存里第一次是 miss，之后两次是 hit。新建的 engine 两样都是空的。所以 README 这句话在 0.8.0 仍然成立，而且比字面更宽：每次新建 engine 丢掉的是缓冲池和计划缓存（计划缓存可以用 with_plan_cache 在几个 engine 之间共享）；多线程 engine 还要重新预留一次 team。每次新建 engine 的代价实测见一次 matmul。

4. einsum 方言

原文：「Equations need the explicit arrow ("ij,jk->ik"). NumPy-style ... ellipsis is supported in flat notation and through EinsumNotation; parenthesized ellipsis remains unsupported.」

let no_arrow = [&x, &y].einsum("ij,jk", &mut engine);
let ell = [&bx, &by].einsum("...ij,...jk->...ik", &mut engine);
println!("{:?}", NestedEinsum::parse("(...ij,jk),kl->...il").map(|n| n.count_leaves()));

4. "ij,jk": Err(InvalidSubscripts { message: "einsum notation must contain exactly one '->', got: ij,jk" })
4. "ij,jk->ik": Ok([2, 4])
4. "...ij,...jk->...ik" on [5,2,3]x[5,3,4]: Ok([5, 2, 4])
4. "ij...,jk...->ik..." on [2,3,5]x[3,4,5]: Ok([2, 4, 5])
4. NestedEinsum "(ij,jk),kl->il": Ok(3)
4. NestedEinsum "(...ij,jk),kl->...il": Err(InvalidSubscripts { message: "ellipsis with parenthesized contraction order is not supported" })
4. flat einsum "(ij,jk)->ik": Err(InvalidSubscripts { message: "EinsumNotation::parse does not accept parentheses; use NestedEinsum::parse for parenthesized contraction order" })

不写箭头是一个类型化的错误，不会像 NumPy 那样按字母顺序推出输出（检查在 split_and_validate_notation）。省略号放在前面、后面都行。README 说的「parenthesized」是另一种记法：用括号指定收缩顺序（"(ij,jk),kl->il"，来自 Julia 的 OMEinsum），它不进普通的 einsum，要用 NestedEinsum::parse，而且不能和 ... 一起用。几条报错的原文和 0.7.1 相同。

5. 运算返回 Result

原文：「Traced operators return Result; propagate with ?.」

let sum = &a + &b + &c; // a、b、c 都是 TracedTensor

error[E0369]: cannot add `&TracedTensor` to `Result<TracedTensor, tenferro_runtime::Error>`
   --> src/main.rs:7:21
    |
  7 |   let sum = &a + &b + &c;
    |             ------- ^ -- &TracedTensor
    |             |
    |             Result<TracedTensor, tenferro_runtime::Error>
    |
note: `Result<TracedTensor, tenferro_runtime::Error>` does not implement `std::ops::Add<&TracedTensor>`
...

&a + &b 的类型是 Result<TracedTensor, Error>，而 Result 没有实现 Add，所以每一步都得写 ?：(&(&a + &b)? + &c)?，或者用方法链 a.add(&b)?.add(&c)?。candle 在这里多做了一步，给 Result<Tensor> 也实现了运算符，一条链只要一个 ?（见 candle 卷的怎么读这一卷）。不只 traced：直接运算、eager 运算也都返回 Result。

feature 各打开什么

工作区里没有一个「总开关」：每个 crate 各有一组 feature，大多是往下转发给 tenferro-cpu。按功能归类：

0.7.1 的 cpu-faer、cpu-blas 在 #2026 改名成 native、blas；webgpu 和 cubecl-interop 已经删掉。几条从源码里能直接看到的规矩，都在 tenferro-cpu 的 lib.rs 开头：

• native 和 blas 互斥：compile_error!("native and blas are mutually exclusive; use --no-default-features for blas")。另外 provider-inject 要求 blas；三个 blas-* 最多开一个；provider-inject 不能和 blas-* 同时开。

• 两个都不开也能编。 源码注释说「A build with neither backend compiles: the CPU numerical routes report a typed Unsupported instead.」只依赖 tenferro-runtime 和 default-features = false 的 tenferro-cpu（intro-nofaer，debug）：

  Copy

  provider: tenferro.cpu.none
  matmul: Err(Unsupported { op: "dot_general", message: "this build selects no CPU numerical backend; enable the `native` or `blas` feature" })
  add:    Ok([2.0, 4.0, 6.0, 8.0])
  exp:    Ok([2, 2])
  

  逐元素运算照常工作，收缩和线代在运行期才报 Unsupported。0.7.1 在这里是编译期的 compile_error!。

• tenferro-runtime 上的 CPU feature 是空的。 仓库里它写着 native = ["tenferro-cpu/native"]，但 tenferro-cpu 只是它的 dev-dependency（反过来 tenferro-cpu 依赖 tenferro-runtime，见源码地图）。发布出去的清单里，native、blas、blas-* 都成了 []。从 crates.io 依赖时，要选 provider 就在 tenferro-cpu 和其他转发它的 crate 上开。

native 和 blas：所有 crate 要一致

互斥加上 feature 统一，结果是一个不可加的组合：依赖图里只要有一个 crate 留着默认的 native，另一个 crate 打开 blas，tenferro-cpu 就同时看到两个。intro-trap 只写了两行依赖，tenferro-cpu 要 Accelerate，tenferro-einsum 用默认 feature（debug）：

tenferro-cpu = { version = "=0.8.0", default-features = false, features = ["blas-accelerate"] }
tenferro-einsum = "=0.8.0"

error[E0428]: the name `Scalar` is defined multiple times
  --> .../tenferro-cpu-0.8.0/src/contraction.rs:74:1
...
error: native and blas are mutually exclusive; use --no-default-features for blas
  --> .../tenferro-cpu-0.8.0/src/lib.rs:68:1
...
error: could not compile `tenferro-cpu` (lib) due to 9 previous errors

cargo tree -e features -i tenferro-cpu 把来源说得很清楚：tenferro-cpu feature "native" 来自 tenferro-einsum feature "native"，后者来自它的 default。规则是：用 BLAS 时，依赖图里每一个转发 provider feature 的 tenferro crate（tenferro-cpu、-ad、-einsum、-linalg、-fft，以及开了 cuda 时的 -gpu）都要 default-features = false 并开同一个 blas-*。本卷的 BLAS 实验就是这样写的。报错里除了那条 compile_error!，还有 8 条重复定义、参数个数不对之类的错，它们都是两套 provider 代码同时编译的连带结果，读报错时先找 mutually exclusive 那一条。

GPU 一侧还留着 0.7.1 那种写法：tenferro-ad 的 EagerExtensionBackendKind 只剩 Cpu 和带 #[cfg(feature = "cuda")] 的 Cuda 两个变体，einsum、linalg、fft 在开了 autodiff 时对它 match，Cuda 那一支只在它们自己的 cuda 下编译。按源码看，依赖图里有谁打开了 tenferro-ad/cuda，所有开了 autodiff 的运算族 crate 也都得开 cuda，否则 match 不完整。本机跑不了 CUDA，但 cargo check 不需要 CUDA 工具链：只给 tenferro-fft 开 ["autodiff", "cuda"]、einsum 和 linalg 只开 autodiff 时，两个 crate 都报 error[E0004]: non-exhaustive patterns: `tenferro_ad::extension::EagerExtensionBackendKind::Cuda` not covered。

阅读路线

• 只想会用：先读本页的五条约定；再读 01 全景 的三页；02 的列主序与视图；03 的 CpuEngine 与线程池。
• 想读懂实现：按顺序读。02、03 讲清楚一次直接计算怎么落到 provider，04 的图和运行时、05 的两套 AD 才好读。
• 只关心求导：一次 grad → TracedTensor → 编译 → primitive AD → traced AD → eager AD。
• 只关心 einsum：einsum → semantic AD 与扩展 → 11 动手。

前置知识

• Rust 的 trait、&mut 借用和 ?；Cargo feature 怎么统一（上面的 native / blas 一节就是它的后果）。
• 线性代数：矩阵乘、SVD、QR；einsum 记法。
• 自动微分的两个方向：向量-雅可比积（VJP，反向）和雅可比-向量积（JVP，前向）。知道 JAX 的 grad 是图变换、PyTorch 的 backward() 是在记录上反向走一遍，读 04、05 会快很多；burn 和 candle 的 eager 自动微分见 burn 卷的 04 自动微分 和 candle 卷的 backward 与 GradStore。
• 线程池：tenferro 的 CPU 并行用 threadteam 的池和放置令牌（底下是每个池私有的 rayon 线程），不用 tokio；池由调用方建。

小结

• 全卷对着 tenferro-rs 0.8.0（a9f494cc，2026-10-30）写；CPU 计算在单独发布的 tcontract 0.9、cpueinsum 0.9、tlinalg 0.8、threadteam 0.2、strided-rs 0.9 和 t4a-faer 0.27 上，computegraph、omeco 不变。
• 直接计算主线：from_vec_col_major → 调用方建 CpuEngine → matmul 即 dot_general，在调用线程上执行 → cpueinsum → tcontract 选 faer → host_data。
• traced 主线：运算只记图 → grad 生成新图 → compile 物化去重 → Runtime 注册描述 → prepare → run(&mut [&mut engine]) → into_tensor。
• eager 主线：EagerRuntime（不持有 engine）→ variable_from → with_eager_session(&mut engine) 立即执行并记录 → backward(&mut engine) 累加进 grad() → clear_grad。
• README 五条约定都成立：行主序数据静默算错（Tensor::from_vec_row_major 是新加的桥）；没有 tenferro 包；新建 engine 丢掉缓冲池和计划缓存；einsum 必须写箭头；运算返回 Result，a + b + c 编不过。
• native 和 blas 互斥，一个 crate 留着默认 native、另一个开 blas 就编不过；两个都不开能编，但收缩在运行期报 Unsupported；tenferro-runtime 上的 CPU feature 在发布版里是空的。