数值执行
沿已验证的 SSA path 执行稠密精确收缩，并把寻路、树互操作和数组执行分开。
本页目录
数组执行入口
| 入口 | 路径规划 | 数值执行 |
|---|---|---|
| arctn_path | 是 | 否；只返回路径 |
| arctn_schedule | 是，可返回切片报告 | 否 |
| arctn_plan | 是，可返回切片计划 | 否；返回 ArcTNExecutionPlan |
| ArcTNExecutionPlan.execute | 否；使用已保存计划 | 是；默认 native，也可显式选择其他 backend |
| ArcTNExecutionPlan.to_tree | 否 | 否；转换为 Cotengra ContractionTree |
| ArcTNExecutionPlan.compile | 否 | 否；准备无切片 compiled object |
| ArcTNOptimizer.search | 是，可写入 sliced indices | 否；返回 Cotengra ContractionTree |
| arctn_tree | 是，可写入 sliced legs | 否；返回 Cotengra ContractionTree |
| arctn_contract | 是，可切片 | 是；默认 native，也可显式选择其他 backend |
| contract_network | 否；使用给定 SSA path | 是；Rust 原生未切片 |
| contract_network_sliced | 否；使用给定 path 和 sliced legs | 是；Rust 原生切片 |
| tnexec | 可现场寻找简单路径，也可加载计划 | 是；单进程 CLI |
树对象不等于已执行
Cotengra ContractionTree 是互操作对象。只有调用者随后显式执行它时，Cotengra/autoray 才负责数组收缩；
arctn_tree本身不是一次数值执行。
原生二元收缩步骤
原生执行在进入 GEMM 前验证网络、输入数量、shape、连续数据长度和路径引用。每个二元步骤把腿按当前 live holders 和 output 语义重新分类。
C[b,i,j] = Σk A[b,i,k] B[b,k,j]
- b
- 两侧共享，保留为 batch 轴
- k
- 两侧共享，本步求和消去
- i、j
- 分别来自 A、B 的自由轴
预处理后，对轴进行排列和合并，即可转为 batched GEMM；结果再恢复为输出张量的轴顺序。
共享且外部仍需要的腿成为 batch legs；共享且收缩后不再需要的腿成为 contraction legs。只在一侧保留的腿进入 free-A 或 free-B。路径决定二叉步骤，但最终执行器仍负责把输出轴恢复成 output 的声明顺序。
输入、dtype 与结果
| Rust Scalar | Python dtype | 要求 |
|---|---|---|
| f32 | float32 | 同一次执行全部输入 dtype 一致 |
| f64 | float64 | shape 与每个输入腿维度完全匹配 |
| Complex32 | complex64 | Python native 输入形成 C-contiguous NumPy buffer |
| Complex64 | complex128 | 返回轴顺序与 output 一致 |
执行是稠密、精确的二元收缩；没有 bond-dimension truncation 或低秩近似。PathStats 中的 FLOPs 是结构性的 scalar multiplication count，不能直接等同于 CPU 指令数、内存流量或墙钟时间。
指标不是完整性能模型
两条路径即使 PathStats 相同，也可能因轴排列、转置和 GEMM 形状不同而有不同运行时间。后端性能需要在相同路径、输入、dtype、线程和计时边界下单独测量。
直接执行
Rust：沿已有路径执行，不重新寻路
use arctn::contract_network;
let result = contract_network(&net, tensors, &ssa_path)?;
Python：寻路并执行
from arctn import arctn_contract
result, info = arctn_contract(
inputs, output, size_dict, arrays,
preset="heavy", backend="native",
return_info=True,
)
Python 高层默认使用 backend="native"，也可显式选择其他后端；调用报告会保存实际 backend 和 implementation。需要保存并复用路径和切片集合时先用 arctn_plan；同一无切片计划在一个进程内高频执行时再调用 plan.compile()。