---
title: "Python API"
description: "公开函数、类型、参数、返回值与错误边界。"
eyebrow: "API Reference"
---

## 公开导出 {#exports}

| 符号 | 用途 |
| --- | --- |
| arctn\_path | 只寻找路径；返回 linear path 或 SSA path |
| arctn\_schedule | 只规划并返回结构化报告，可包含切片方案 |
| arctn\_plan | 规划一次并返回可保存的 ArcTNExecutionPlan |
| ArcTNExecutionPlan | 加载、验证、转换或执行一个已确定的计划 |
| PlanValidationError | 计划文件、网络或数组与执行契约不一致 |
| arctn\_tree | 规划后返回 Cotengra ContractionTree |
| arctn\_contract | 规划并执行一次数值收缩 |
| ArcTNCompiledContraction | 编译并重复执行同一网络和 SSA path |
| ArcTNOptimizer | 向 opt\_einsum 返回 path，向 Cotengra/Quimb 返回 ContractionTree |
| arctn\_simplify | 只分析确定性网络化简 |

> **规划报告**
>
> 完整规划报告由 `arctn_schedule` 返回；这个入口只规划，不执行张量数组。

## arctn\_plan 与 ArcTNExecutionPlan {#plan}

```text
arctn_plan(inputs, output, size_dict, *, preset="heavy", seed=0, target_size=None, slicing_mode="fixed", max_time=None, flops_weight=1.0, read_write_weight=64.0, rate_enabled=True)
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| target\_size | int \| None | 可选的单片二元收缩结果元素数上限；单张量网络另检查最终输出。 |
| slicing\_mode | Literal\["fixed", "dynamic"\] | 固定路径切片或 slice-and-reconfigure。 |
| rate\_enabled | bool | 是否启用公开的协作式提前停止控制；不改变返回路径必须完整合法的要求。 |

**返回：** ArcTNExecutionPlan。函数只规划，不读取或执行 arrays。

| 方法 | 作用 |
| --- | --- |
| from\_schedule(report, ...) | 把 use\_ssa=True 的现有 schedule report 包装成 plan，不再次寻路 |
| from\_dict(artifact) / load(path) | 用 Rust validator 读取 self-contained version 2 artifact |
| to\_dict() / save(path) | 导出或原子写入 JSON |
| validate(..., arrays=...) | 复核网络结构、维度与可选数组元数据 |
| to\_linear\_path() | 转换为 opt\_einsum recycled linear path |
| to\_tree() | 转换为 Cotengra ContractionTree，不重新规划 |
| compile(backend=...) | 只为无切片 plan 准备进程内 compiled object |
| execute(arrays, backend=...) | 执行保存的 path 与 exact slice set，不重新规划 |

> **计划边界**
>
> ArcTNExecutionPlan 不保存数组、设备、backend 或已编译 kernel。Python load 只接受 self-contained version 2；带切片 plan 不能 compile，应使用 execute 或 to\_tree。

## arctn\_path {#path}

```text
arctn_path(inputs, output, size_dict, *, preset="heavy", seed=0, use_ssa=False, max_time=None, flops_weight=1.0, read_write_weight=64.0)
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| inputs | Sequence\[Sequence\[Hashable\]\] | 按张量顺序给出腿标签；每个标签必须可哈希。 |
| output | Sequence\[Hashable\] | 结果中保留的腿及轴顺序。 |
| size\_dict | Mapping\[Hashable, int\] | 精确覆盖已使用腿的正整数维度。 |
| preset | Literal\["light", "heavy"\] | 默认 Heavy。 |
| seed | int | 显式随机种子。 |
| use\_ssa | bool | false 返回 recycled linear path；true 返回 SSA path。 |
| max\_time | float \| None | 有限正数；cooperative limit，不是硬超时。 |
| flops\_weight | float | FLOPs 权重，有限且非负。 |
| read\_write\_weight | float | read/write complexity 权重，有限且非负；两个权重不能同时为 0。 |

**返回：** list\[tuple\[int, int\]\]。该函数不接收 target\_size，因为 path 返回值无法同时携带 sliced legs。

## arctn\_schedule {#schedule}

```text
arctn_schedule(inputs, output, size_dict, *, preset="heavy", seed=0, target_size=None, slicing_mode="fixed", max_time=None, use_ssa=False, flops_weight=1.0, read_write_weight=64.0, rate_enabled=True)
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| target\_size | int \| None | 单个 slice 中二元收缩结果的元素数上限；单张量网络另检查最终输出。 |
| slicing\_mode | Literal\["fixed", "dynamic"\] | 默认 fixed；dynamic 必须同时提供 target\_size。 |
| rate\_enabled | bool | 是否启用公开的协作式提前停止控制；false 主要用于固定工作量实验。 |
| use\_ssa | bool | 控制报告中的 path 编码。 |

**返回：** dict。稳定结果字段包括最终 path、结构路径指标、objective 与可选 slicing 结果；额外诊断字段可能随版本变化。

```python
report = arctn_schedule(
    inputs, output, size_dict,
    preset="heavy", seed=0, use_ssa=True,
    target_size=2**24, slicing_mode="fixed",
)
print(report["path"])
print(report["sliced_legs"])
```

## arctn\_tree {#tree}

```text
arctn_tree(inputs, output, size_dict, *, preset="heavy", seed=0, target_size=None, slicing_mode="fixed", max_time=None, flops_weight=1.0, read_write_weight=64.0, return_info=False)
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| target\_size | int \| None | 可选的单片二元结果精确元素数上限；单张量网络另检查最终输出。 |
| slicing\_mode | Literal\["fixed", "dynamic"\] | 选择固定路径切片或 slice-and-reconfigure。 |
| return\_info | bool | true 返回 (tree, info)。 |

**返回：** cotengra.ContractionTree，或 (tree, info)。需要安装 Cotengra 和 opt\_einsum。

`arctn_tree` 是 Python 高层转换入口，不是 TreeSA 算法，也不是 Rust 的 `arctn::tree` 模块。

## arctn\_contract {#contract}

```text
arctn_contract(inputs, output, size_dict, arrays, *, preset="heavy", seed=0, target_size=None, slicing_mode="fixed", max_time=None, backend="native", flops_weight=1.0, read_write_weight=64.0, return_info=False)
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| arrays | Sequence\[array\] | 数量、shape 与 inputs 一致；所有数组使用相同 dtype。 |
| backend | str | native，或显式 opt\_einsum backend 名称；不接受 auto。 |
| return\_info | bool | true 返回 (result, info)。 |

**返回：** native 返回 numpy.ndarray；外部后端返回相应 backend 的数组对象。return\_info=True 时返回 (result, info)。native 支持 float32、float64、complex64、complex128。

> **异步后端**
>
> 外部数组后端可能异步，主机函数返回不代表设备已完成。`arctn_contract` 仅对 `native` 和 `numpy` 提供 `execution_wall_s`，其他后端均为 `None`。`execution_dispatch_wall_s` 记录主机端执行调用，`execution_total_host_wall_s` 还包括输入准备和执行设置。测量设备完成时间时，需要显式同步所选后端并单独计时。

## ArcTNCompiledContraction {#compiled}

```python
compiled = ArcTNCompiledContraction.compile(
    inputs, output, size_dict,
    ssa_path=ssa_path, backend="native",
)
result = compiled.execute(arrays)
stats = compiled.stats()
```

- 必须提供完整 SSA path；compile 不寻路。
- execute 与直接调用对象都执行固定网络和路径。
- compiled object 当前不支持 sliced legs。
- 它是进程内对象，不是跨版本持久化的 binary plan。

## ArcTNOptimizer 与 arctn\_simplify {#optimizer-simplify}

```text
ArcTNOptimizer(*, preset="heavy", seed=0, max_time=None, flops_weight=1.0, read_write_weight=64.0, target_size=None, slicing_mode="fixed")
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| preset | Literal\["light", "heavy"\] | 选择公开 Auto preset；默认 Heavy。 |
| seed | int | 显式 base seed。 |
| max\_time | float \| None | 协作式 planning limit，不是硬墙钟。 |
| flops\_weight | float | FLOPs 权重；必须有限且非负。 |
| read\_write\_weight | float | read/write complexity 权重；两个权重不能同时为 0。 |
| target\_size | int \| None | tree 接口中每个 slice 的二元结果元素数硬上限；单张量网络另检查最终输出。 |
| slicing\_mode | Literal\["fixed", "dynamic"\] | 默认 fixed；dynamic 必须同时提供 target\_size。 |

**返回：** \_\_call\_\_ 返回 recycled linear path；search 返回 cotengra.ContractionTree。

```python
path_optimizer = ArcTNOptimizer(
    preset="heavy", seed=0, max_time=30,
)
linear_path = path_optimizer(inputs, output, size_dict)

tree_optimizer = ArcTNOptimizer(
    preset="heavy", seed=0,
    target_size=2**24, slicing_mode="fixed",
)
tree = tree_optimizer.search(inputs, output, size_dict)

summary = arctn_simplify(inputs, output, size_dict)
```

`ArcTNOptimizer.__call__` 为 opt\_einsum 的 path-only 协议返回 linear path，因此不能用 `memory_limit` 携带切片信息，并且配置了 `target_size` 时会拒绝 path-only 调用。`ArcTNOptimizer.search()` 委托给 `arctn_tree`，返回可携带 sliced indices 的 `ContractionTree`，供 Cotengra/Quimb 的 tree dispatch 使用。`arctn_simplify` 只返回确定性化简分析，不运行 Auto，也不执行数组。

- [Quimb 前端教程](/docs/tutorial-quimb)

## 统一错误边界 {#errors}

- preset 只接受 light / heavy；slicing\_mode 只接受 fixed / dynamic。
- dynamic 没有 target\_size 会报错；target\_size 必须是严格正整数且不可达时不会回退。
- objective 权重必须有限、非负、不能同时为 0。
- arrays 的数量和每个数组的 shape 必须与网络一致，同一次执行的所有输入使用相同 dtype；重复 output legs 在 native execution 中不支持。
- 执行后端默认为 native；其他后端通过 backend 参数指定。ArcTN 不根据数组类型自动选择后端，也不在执行失败后切换执行器。