5 分钟快速开始
用一条三矩阵链规划一次，保存、加载、验证并执行同一份 contraction plan。
本页目录
三种使用方式
本页使用 arctn_plan 把 planning 与 execution 分开。规划只运行一次；保存、加载和执行都复用同一条 SSA path 与同一组切片腿。最后再介绍不需要保存计划时的一次性快捷入口。
| 使用场景 | 对应入口 | 后续页面 |
|---|---|---|
| 需要保存或重复执行同一计划 | arctn_plan | 执行计划 |
| 只需要一次规划并执行 | arctn_contract | 一次性调用 |
| 已有 Quimb Circuit 或 TensorNetwork | ArcTNOptimizer | Quimb 前端教程 |
- Quimb 前端教程 — 通过 ArcTNOptimizer.search() 返回包含路径和 sliced indices 的 ContractionTree。
1. 定义网络与数组
import numpy as np
inputs = [("a", "b"), ("b", "c"), ("c", "d")]
output = ("a", "d")
size_dict = {"a": 2, "b": 3, "c": 4, "d": 2}
a = np.arange(6, dtype=np.float64).reshape(2, 3)
b = np.arange(12, dtype=np.float64).reshape(3, 4)
c = np.arange(8, dtype=np.float64).reshape(4, 2)
arrays = [a, b, c]
inputs 的第 i 项必须与 arrays[i] 的轴顺序一致。output 决定最终结果保留哪些腿及其轴顺序；size_dict 必须精确覆盖网络中使用的标签。
2. 规划一次
from arctn import arctn_plan
plan = arctn_plan(
inputs, output, size_dict,
preset="light", seed=0,
)
print("SSA path:", plan.ssa_path)
print("sliced legs:", plan.sliced_legs)
print("metrics:", dict(plan.metrics))
plan 是 ArcTNExecutionPlan。它包含规范化网络、SSA path、精确切片腿集合和紧凑的规划信息，但不包含数组或执行 backend。preset="light" 适合快速开始；默认 preset 是 Heavy。
3. 保存并加载
from arctn import ArcTNExecutionPlan
plan.save("contraction-plan.json")
loaded = ArcTNExecutionPlan.load("contraction-plan.json")
loaded.validate(inputs, output, size_dict, arrays=arrays)
version 2 JSON 按标签首次出现顺序生成稠密整数编号，因此不会 pickle 任意 Python 对象。内存中新建的 plan 可以保留原标签供查看；保存后再加载时使用规范化整数标签。validate() 检查张量顺序、输出顺序、维度和可选数组元数据。
4. 执行同一计划
result, info = loaded.execute(
arrays, backend="native", return_info=True
)
np.testing.assert_allclose(result, a @ b @ c)
print(info["execution_backend"])
execute() 不会重新调用 Light 或 Heavy。默认 backend="native" 使用 ArcTN Rust CPU executor；其他 opt_einsum 数组后端通过 backend 参数指定。ArcTN 不根据数组类型自动选择后端，也不在执行失败后自动切换。
重复执行
无切片 plan 还可以调用
loaded.compile(backend=...)，得到当前进程内可重复使用的ArcTNCompiledContraction。有切片 plan 使用execute()或to_tree()，不能静默丢弃切片后再编译。
5. 不保存计划时的一次性调用
from arctn import arctn_contract
result = arctn_contract(
inputs, output, size_dict, arrays,
preset="light", seed=0, backend="native",
)
arctn_contract 是一次性调用接口：每次都会重新规划，然后按得到的路径和切片方案执行。重复执行同一网络结构时，先用 arctn_plan 创建一次计划，再通过 plan.execute(arrays) 复用该对象，不重复寻路。