---
title: "执行计划"
description: "用 ArcTNExecutionPlan 固定网络、SSA path 和切片集合，在不重新寻路的前提下保存、验证、转换或执行。"
eyebrow: "数值执行"
---

## 五种表示及其边界 {#representations}

| 表示 | 保存什么 | 主要用途 |
| --- | --- | --- |
| SSA path | 二元收缩拓扑 | 重放收缩顺序；本身不含网络或切片集合 |
| arctn\_schedule report | 路径、指标和搜索诊断 | 检查一次 planning；不是长期执行格式 |
| ArcTNExecutionPlan | 规范化网络、SSA path、切片集合和 target 声明 | 跨进程保存、验证和重放 |
| ArcTNCompiledContraction | 面向一个 backend 的进程内执行几何 | 重复执行无切片计划 |
| Cotengra ContractionTree | 树结构和 sliced indices | Quimb/Cotengra 生态互操作 |

> **术语边界**
>
> `ArcTNExecutionPlan` 是 planning 与 numerical execution 之间稳定的 backend-neutral data boundary。它不是数组程序的通用 compiler IR，也不是已编译 kernel。

## 生命周期 {#lifecycle}

先用 `arctn_plan` 生成计划，再保存或执行。加载后的计划复用原有路径和切片集合，不重新运行 planner；backend 在 `execute` 或 `compile` 时选择。

```python
from arctn import ArcTNExecutionPlan, arctn_plan

plan = arctn_plan(
    inputs, output, size_dict,
    preset="heavy", seed=0,
    target_size=2**24, slicing_mode="fixed",
)
plan.save("plan.json")

loaded = ArcTNExecutionPlan.load("plan.json")
loaded.validate(inputs, output, size_dict, arrays=arrays)
result = loaded.execute(arrays, backend="native")
```

## version 2 JSON 的保存内容 {#schema}

| 字段 | 含义 |
| --- | --- |
| schema / schema\_version | arctn-execution-plan / 2 |
| path\_format | ssa-v1；不会用整数对形状猜测路径坐标系 |
| network | 稠密整数标签的 inputs、output 和有序 size\_dict |
| network\_canon | 保留张量顺序、输出顺序和维度的 canonical identity |
| ssa\_path | 已经验证可在 embedded network 上完整重放的路径 |
| sliced.legs | 执行时必须使用的精确切片腿集合；无切片时明确为空数组 |
| target\_size | 可选的每个 slice 二元收缩结果元素数上限；单张量网络则检查最终输出 |
| metrics / planning / provenance | 紧凑指标、公开调用设置和版本来源 |

Python 调用可以使用任意可哈希腿标签。持久化时按首次出现顺序映射为稠密整数标签，避免 pickle 任意 Python 对象。内存中新建的 plan 可保留原标签供查看；加载后的 plan 使用文件中的整数标签。

加载 version 2 文件时，Rust 会重新验证网络、SSA path、切片集合和 target 声明，并复算文件中出现的核心路径与切片指标。`planning` 和 `provenance` 用于说明计划怎样产生，不参与数值执行正确性的判定。

> **精确 target 声明**
>
> `target_size` 不是 RSS、VRAM、allocator cache 或 backend workspace 上限。version 2 只要声明 target，就必须同时保存正整数 `target_size`、匹配的 log2 值，以及 `memory_constraint_metric="max_intermediate_elements_per_slice"`；加载时 Rust 会在真实路径与切片集合上重新复核。

## 转换与执行 {#operations}

| 方法 | 是否重新规划 | 限制 |
| --- | --- | --- |
| to\_linear\_path() | 否 | 返回 opt\_einsum recycled linear path |
| to\_tree() | 否 | 需要 Cotengra；把保存的 sliced legs 写入 tree |
| execute(arrays, backend=...) | 否 | 执行文件中确定的 path 与 slice set |
| compile(backend=...) | 否 | 只接受无切片 plan；返回进程内 compiled object |

plan 不保存数组、device、backend 或 kernel。`plan.execute()`、`plan.to_tree()` 和 `plan.compile()` 都不重新运行 planner。`native` 使用 ArcTN Rust CPU executor；其他显式名称交给 opt\_einsum 和相应数组库。external backend 的切片当前由 Python 顺序枚举 assignments；native 切片由 Rust/Rayon 执行。

> **切片计划**
>
> 有切片 plan 不能 compile，因为 ArcTNCompiledContraction 当前不承载 sliced legs；应使用 plan.execute() 或 plan.to\_tree()。

## 兼容性 {#compatibility}

- Python ArcTNExecutionPlan.load() 只接受自包含的 version 2 文件。
- Rust 与 CLI 读取器兼容 version 1 和 version 2；version 1 必须由调用者提供并核对外部网络。
- tnpath --save-path 写 version 2；tnexec 当前仍要求 --net，并复核 embedded network 与当前网络一致。
- schema-less legacy 文件只有显式允许时才读取，不属于默认安全格式。