---
title: "Auto 概览"
description: "通过 Light 或 Heavy 预设生成并比较多条完整收缩路径，按本次调用的 objective 返回已完成候选中的最佳路径。"
eyebrow: "Auto 寻路"
---

## Auto 的公开功能 {#scope}

Auto 是 ArcTN 的高层路径规划入口。它在给定资源范围内尝试探索多条完整收缩路径；每条路径都可以表示为一棵二叉收缩树。已经完成并通过验证的候选会用同一个 `PlannerObjective` 评价，最后返回其中目标值最低的一条。

```diagram
auto-candidate-selection
这是一张未切片路径搜索的机制示意图，不是一次运行的实测数据。每个图形代表同一张量网络的一棵完整候选收缩树；P* 只是已完成候选集合中的最优者。
```

## 公共 Python 接口 {#basic-usage}

```python
from arctn import arctn_path, arctn_plan, arctn_schedule

# 只需要一条路径
path = arctn_path(
    inputs, output, size_dict,
    preset="light", seed=0,
)

# 需要最终路径及其可核验指标
report = arctn_schedule(
    inputs, output, size_dict,
    preset="heavy", seed=0, use_ssa=True,
)
print(report["path"])
print(report["log10_flops"])
print(report["log2_max_size"])
print(report["log2_read_write"])

# 保存完整网络、SSA path 和切片集合
plan = arctn_plan(
    inputs, output, size_dict, preset="heavy", seed=0
)
plan.save("plan.json")
```

| 入口 | 公开职责 | 返回结果 |
| --- | --- | --- |
| arctn\_path | 选择 Light 或 Heavy 并规划路径 | 一条 SSA 或 linear path |
| arctn\_schedule | 规划并保留最终结果的结构化信息 | 路径、目标、路径指标与可选切片结果 |
| arctn\_plan | 规划并固定可执行计划 | 可保存的 ArcTNExecutionPlan |
| arctn\_tree | 把规划结果转换为 Cotengra ContractionTree | 可供 Cotengra / Quimb 使用的树 |
| arctn\_contract | 规划后立即执行数值收缩 | 数值结果，以及可选的最终信息 |

> **规划与执行分开**
>
> 需要保存网络、SSA path、切片和 target 声明时使用 `arctn_plan`。无切片 plan 可进一步 compile 后重复执行；反复调用 `arctn_contract` 会重新规划。

## 常用公开控制项 {#public-controls}

| 参数 | 作用 | 边界 |
| --- | --- | --- |
| preset | 选择 `light` 或 `heavy` | 默认值是 `heavy` |
| seed | 设置随机搜索的基础种子 | 固定 seed 不等于固定墙钟时间 |
| max\_time | 设置协作式规划时间限制 | 不是可抢占的硬进程超时 |
| flops\_weight / read\_write\_weight | 固定本次调用的完整路径目标函数 | 必须有限、非负，且不能同时为零 |
| target\_size | 限制每个切片允许的最大中间张量元素数 | 不等于 RSS、显存或并发切片总内存 |
| slicing\_mode | 选择 `fixed` 或 `dynamic` | `dynamic` 必须同时提供 `target_size` |

```python
report = arctn_schedule(
    inputs, output, size_dict,
    preset="light",
    seed=7,
    max_time=30.0,
    flops_weight=1.0,
    read_write_weight=64.0,
)
```

> [!WARNING]
> **时间限制**
>
> 严格的端到端墙钟上限由独立进程、watchdog 或作业调度器实施，并覆盖进程启动、导入、规划和退出。

## 结果保证 {#guarantees}

| 接口保证 | 未提供的保证 |
| --- | --- |
| 返回的是完整、通过验证的合法路径 | 找到全部收缩树中的全局最优路径 |
| 已完成候选使用同一个目标函数比较 | 返回值是严格意义上的局部最小值 |
| 启发式搜索只检查有限候选，不穷举全部收缩树 | 任何网络上都具有固定或极低的实际耗时 |
| Heavy 允许使用更积极的搜索配置 | Heavy 每次都比 Light 得到更好的路径 |

Auto 返回本次调用已完成候选中目标值最低的路径，也就是本次搜索观察到的最佳候选。