---
title: "数值执行"
description: "沿已验证的 SSA path 执行稠密精确收缩，并把寻路、树互操作和数组执行分开。"
eyebrow: "切片与执行"
---

## 数组执行入口 {#planning-vs-execution}

| 入口 | 路径规划 | 数值执行 |
| --- | --- | --- |
| 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` 本身不是一次数值执行。

## 原生二元收缩步骤 {#native-step}

原生执行在进入 GEMM 前验证网络、输入数量、shape、连续数据长度和路径引用。每个二元步骤把腿按当前 live holders 和 output 语义重新分类。

```diagram
execution-step
二元收缩转为 batched matrix multiplication 的例子：b 保留，k 求和，i、j 组成结果的自由轴。多个同类轴可排列并合并为一个矩阵维度。
```

共享且外部仍需要的腿成为 batch legs；共享且收缩后不再需要的腿成为 contraction legs。只在一侧保留的腿进入 free-A 或 free-B。路径决定二叉步骤，但最终执行器仍负责把输出轴恢复成 `output` 的声明顺序。

## 输入、dtype 与结果 {#data-contract}

| 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、线程和计时边界下单独测量。

## 直接执行 {#usage}

Rust：沿已有路径执行，不重新寻路

```rust
use arctn::contract_network;

let result = contract_network(&net, tensors, &ssa_path)?;
```

Python：寻路并执行

```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()`。