ArcTN
ArcTN 接收已经构造好的张量网络，可作为 Quimb/Cotengra 的收缩规划器，也可直接完成路径规划、切片和数值收缩。
本页目录
张量网络的规划与执行
ArcTN 的输入是已经构造好的张量网络。OpenQASM、量子门序列或其他上层模型，需要先由 Quimb 等前端转换为张量、指标和维度。
电路定义：Qiskit 或 Quimb
其他张量网络方法：MPS 状态更新与可选截断；PEPS 更新与收缩算法。
其他方法：稠密状态向量／密度矩阵、稳定子方法、Pauli 传播。
inputs · output · size_dict
arrays (用于执行)
Qiskit 电路需要转换；兼容的 OpenQASM 2 电路可由 Quimb 导入。
收缩路径 + 切片索引
arctn_contract(…)
或可复用的计划: ArcTNExecutionPlan (IR)
Native CPU 执行器（Rust）
或 opt_einsum + NumPy / CuPy / Torch / JAX
ArcTNOptimizer.search()
↓ cotengra.ContractionTree
Quimb / Cotengra 执行 → autoray
CPU 或 GPU 数组后端
收缩结果：标量或张量
ArcTN 处理张量收缩问题，也可处理 MPS／PEPS 算法中的收缩子问题。状态更新、截断、采样与噪声模型由调用方管理。
网络结构用 inputs、output 和 size_dict 表示，数值执行时再提供 arrays。ArcTN 可以只返回收缩路径，也可以生成 ArcTNExecutionPlan：它保存网络结构、SSA path 和切片集合，作为规划与执行之间的中间表示（IR）。
搜索一条路径
下面为三矩阵乘积 ABC 搜索收缩顺序。a、d 是输出指标；b、c 在收缩中求和。这里仅使用网络结构，不需要生成数值数组。
最小 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 返回完整报告。
- 快速开始 — 继续执行这条矩阵链，并读取路径指标。
执行与集成
直接执行收缩
提供数值数组后，arctn_contract 可在一次调用中完成规划、可选切片和执行。默认使用 ArcTN native CPU，也可以显式选择外部数组 backend。return_info=True 同时返回规划和执行报告。
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 的 optimize= 传入 ArcTNOptimizer，即可使用 ArcTN 搜索路径。ArcTNOptimizer.search() 返回包含路径和 sliced indices 的 ContractionTree，后续数组执行由 Quimb / Cotengra 负责。
保存与复用计划
arctn_plan 返回 ArcTNExecutionPlan。可用 save / load 保存和加载计划，再调用 execute 执行；同一网络结构和维度下，数组值变化时无需重新寻路。计划不包含数值数组或设备状态，backend 在执行或编译时选择。
核心能力
| 能力 | 支持方式 | 从哪里继续 |
|---|---|---|
| 路径生成 | 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 | 并行层次 |
功能范围
ArcTN 的 native executor 面向 CPU；CuPy、Torch 或 JAX 数组通过用户显式选择的 opt_einsum backend 执行。
ArcTN 不是通用近似张量网络压缩框架；公开切片接口执行精确分解，最终结果由全部 slice 求和得到。
大网络的 Auto 预设与多数局部搜索是 heuristic，不保证全局最优；
optimal只适合小网络。max_time是 cooperative limit。需要严格墙钟上限时，应在独立进程外使用 watchdog 或作业调度器。兼容性与功能边界 — 查看切片、执行后端、时间限制与求解保证的适用范围。
性能与证据边界 — 理解 objective、墙钟、核心数和 benchmark 分母。