---
title: "5 分钟快速开始"
description: "用一条三矩阵链规划一次，保存、加载、验证并执行同一份 contraction plan。"
eyebrow: "开始使用"
---

## 三种使用方式 {#choose-route}

本页使用 `arctn_plan` 把 planning 与 execution 分开。规划只运行一次；保存、加载和执行都复用同一条 SSA path 与同一组切片腿。最后再介绍不需要保存计划时的一次性快捷入口。

| 使用场景 | 对应入口 | 后续页面 |
| --- | --- | --- |
| 需要保存或重复执行同一计划 | arctn\_plan | 执行计划 |
| 只需要一次规划并执行 | arctn\_contract | 一次性调用 |
| 已有 Quimb Circuit 或 TensorNetwork | ArcTNOptimizer | Quimb 前端教程 |

- [Quimb 前端教程](/docs/tutorial-quimb) — 通过 ArcTNOptimizer.search() 返回包含路径和 sliced indices 的 ContractionTree。

## 1. 定义网络与数组 {#network}

```python
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. 规划一次 {#plan}

```python
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. 保存并加载 {#save-load}

```python
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. 执行同一计划 {#execute}

```python
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. 不保存计划时的一次性调用 {#one-shot}

```python
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)` 复用该对象，不重复寻路。

## 下一步 {#next}

- [张量网络输入](/docs/tensor-network) — 理解 labels、open legs、trace 与 diagonal。
- [收缩树与路径](/docs/contraction-path) — 区分 tree、SSA path 与 recycled linear path。
- [执行计划](/docs/execution-plan) — 查看 schema、切片、后端和兼容性边界。
- [Auto](/docs/auto) — 继续理解 Light / Heavy 的接口、候选选择思想和保证边界。
- [重复执行固定路径](/docs/compiled-contraction) — 避免每次都重新寻路。