---
title: "ArcTN"
description: "ArcTN 接收已经构造好的张量网络，可作为 Quimb/Cotengra 的收缩规划器，也可直接完成路径规划、切片和数值收缩。"
eyebrow: "ArcTN 中文文档"
---

## 张量网络的规划与执行 {#position}

ArcTN 的输入是已经构造好的张量网络。OpenQASM、量子门序列或其他上层模型，需要先由 Quimb 等前端转换为张量、指标和维度。

```diagram
ecosystem
```

网络结构用 `inputs`、`output` 和 `size_dict` 表示，数值执行时再提供 `arrays`。ArcTN 可以只返回收缩路径，也可以生成 `ArcTNExecutionPlan`：它保存网络结构、SSA path 和切片集合，作为规划与执行之间的中间表示（IR）。

## 搜索一条路径 {#first-example}

下面为三矩阵乘积 `ABC` 搜索收缩顺序。`a`、`d` 是输出指标；`b`、`c` 在收缩中求和。这里仅使用网络结构，不需要生成数值数组。

最小 Python 例子

```python
from arctn import arctn_path

inputs = [("a", "b"), ("b", "c"), ("c", "d")]
output = ("a", "d")
size_dict = {"a": 2, "b": 3, "c": 4, "d": 2}

path = arctn_path(
    inputs, output, size_dict, preset="light", seed=0
)
print(path)
```

`arctn_path` 只规划路径，不读取数组；默认返回 opt\_einsum 使用的 recycled linear path，`use_ssa=True` 返回 SSA path。`arctn_contract` 用于执行收缩，`arctn_plan` 创建可复用的计划，再由 `plan.save(...)` 保存；`arctn_schedule` 返回完整报告。

- [快速开始](/docs/quick-start) — 继续执行这条矩阵链，并读取路径指标。

## 执行与集成 {#usage}

### 直接执行收缩 {#direct-execution}

提供数值数组后，`arctn_contract` 可在一次调用中完成规划、可选切片和执行。默认使用 ArcTN native CPU，也可以显式选择外部数组 backend。`return_info=True` 同时返回规划和执行报告。

```python
import numpy as np
from arctn import arctn_contract

arrays = [np.ones((2, 3)), np.ones((3, 4)), np.ones((4, 2))]
result = arctn_contract(
    inputs, output, size_dict, arrays,
    preset="light", backend="native",
)
```

需要限制中间张量大小时，设置 `target_size` 并选择 fixed 或 dynamic slicing。该参数限制每个 slice 的二元收缩结果元素数；单张量网络另检查最终输出。它不是进程内存或显存上限。

### 在 Quimb 中使用 {#quimb-integration}

向 Quimb 的 `optimize=` 传入 `ArcTNOptimizer`，即可使用 ArcTN 搜索路径。`ArcTNOptimizer.search()` 返回包含路径和 sliced indices 的 `ContractionTree`，后续数组执行由 Quimb / Cotengra 负责。

- [Quimb 教程](/docs/tutorial-quimb)

### 保存与复用计划 {#reuse-plan}

`arctn_plan` 返回 `ArcTNExecutionPlan`。可用 `save` / `load` 保存和加载计划，再调用 `execute` 执行；同一网络结构和维度下，数组值变化时无需重新寻路。计划不包含数值数组或设备状态，backend 在执行或编译时选择。

- [执行计划](/docs/execution-plan)
- [执行后端](/docs/execution-backends)

## 核心能力 {#capabilities}

| 能力 | 支持方式 | 从哪里继续 |
| --- | --- | --- |
| 路径生成 | greedy、random-greedy、小网络 exact DP 与递归超图二分 | 选择寻路算法 |
| 路径改进 | subtree reconfiguration、simulated annealing、parallel tempering、leaf-order DP | 树搜索与局部改进 |
| Auto | Light / Heavy 两个公开 preset；支持按调用设置 objective weights | Auto |
| 切片 | fixed 与 dynamic 两种公开模式；target\_size 使用精确元素数 | 切片 |
| 数值执行 | ArcTN native CPU，或显式 opt\_einsum array backend | 执行后端 |
| 并行与分布式 | Rayon 单机并行、slice chunks，以及通过 mpi feature 启用的 tnmpi | 并行层次 |

## 功能范围 {#boundaries}

- ArcTN 的 native executor 面向 CPU；CuPy、Torch 或 JAX 数组通过用户显式选择的 opt\_einsum backend 执行。
- ArcTN 不是通用近似张量网络压缩框架；公开切片接口执行精确分解，最终结果由全部 slice 求和得到。
- 大网络的 Auto 预设与多数局部搜索是 heuristic，不保证全局最优；`optimal` 只适合小网络。
- `max_time` 是 cooperative limit。需要严格墙钟上限时，应在独立进程外使用 watchdog 或作业调度器。

- [兼容性与功能边界](/docs/versioning) — 查看切片、执行后端、时间限制与求解保证的适用范围。
- [性能与证据边界](/docs/performance-boundaries) — 理解 objective、墙钟、核心数和 benchmark 分母。