---
title: "Python API"
description: "按收缩序优化、保存与复用、数值执行和第三方接入查阅函数、参数与返回值。"
eyebrow: "API 参考"
---

## 通用参数与分类 {#exports}

调用 Light / Heavy 的入口需要完整 Python wheel，或另行配置兼容的编译库，见[安装](/docs/installation)。执行已有收缩序与网络化简不需要 Light / Heavy。

| 类别 | API | 返回内容 |
| --- | --- | --- |
| 收缩序优化 | `arctn_path`、`arctn_schedule` | 路径，或包含路径与指标的报告 |
| 保存与加载 | `arctn_plan`、`ArcTNExecutionPlan` | 保存网络、收缩序和切片信息的对象 |
| 数值收缩 | `arctn_contract` | 计算结果，可选执行报告 |
| 编译与复用 | `ArcTNCompiledContraction` | 可重复调用的编译对象 |
| 第三方接入 | `arctn_tree`、`ArcTNOptimizer` | Cotengra 收缩树，或 `ArcTNOptimizer` 对象 |
| 网络化简 | `arctn_simplify` | 化简前缀与缩减网络信息 |

### 通用参数 {#parameters}

以下参数只在对应函数签名列出时可用。签名中的 `*` 表示后续参数必须按名称传入。下面按签名列出参数和默认值；可直接运行的调用见[快速开始](/docs/quick-start)和各[示例](/docs/tutorial-heavy)。

| 参数 | 类型 | 含义 |
| --- | --- | --- |
| `inputs` | `Sequence[Sequence[Hashable]]` | 每个张量的 index 标签，内层顺序对应数组轴 |
| `output` | `Sequence[Hashable]` | 保留的 index，顺序决定结果轴顺序 |
| `size_dict` | `Mapping[Hashable, int]` | 已使用 index 的正整数维度，不得缺少或多出条目 |
| `preset` | `"light" \| "heavy"` | 规划预设，默认 Heavy |
| `seed` | `int` | 基础随机种子；Light 和 Heavy 的额外独立起点种子由其派生，见[单机并行](/docs/parallelism#auto-starts) |
| `max_time` | `float \| None` | 规划时间限制，单位秒；提供时必须有限且为正，在算法检查点生效 |
| `flops_weight` | `float` | FLOPs 权重，有限且非负 |
| `read_write_weight` | `float` | 读写量权重，有限且非负；两项权重不能同时为 0 |
| `target_size` | `int \| None` | 每个切片中二元收缩结果的元素数上限；单张量网络检查最终输出 |
| `slicing_mode` | `"fixed" \| "dynamic"` | Fixed 保持路径；Dynamic 允许调整路径，且必须提供 `target_size` |
| `use_ssa` | `bool` | 是否返回 SSA 编码；否则返回逐步重新编号的线性路径 |
| `rate_enabled` | `bool` | 是否启用 rate 提前停止条件；关闭它不会关闭其他停止条件 |
| `backend` | `str` | `"native"` 或显式数组后端名，不接受 `"auto"` |
| `return_info` | `bool` | 是否同时返回信息字典 |

网络输入规则见[张量网络输入](/docs/tensor-network#validation)。`target_size` 的单位是元素，不是字节、RSS 或显存。数组后端和异步计时见[执行后端](/docs/execution-backends)。

## 收缩序优化 {#search-apis}

### arctn_path {#path}

```python
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,
)
```

**返回** `list[tuple[int, int]]`。只寻路，不执行数组。默认返回线性路径；`use_ssa=True` 返回 SSA 路径。此函数不接收切片参数，因为路径列表不能同时携带切片 index。

### arctn_schedule {#schedule}

```python
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,
)
```

**返回** `dict`，包含路径、目标权重、路径指标、编译库记录的搜索耗时 `wall_s` 和可选切片信息。不读取或执行数值数组，不返回内部候选和阶段记录。字段含义及示例见[使用 Heavy：读取返回结果](/docs/tutorial-heavy#read)。

## 保存与加载 {#saved-paths}

### arctn_plan {#plan}

```python
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,
)
```

**返回** `ArcTNExecutionPlan`。只规划，不执行数组。该对象保存网络、SSA 路径和切片信息，不保存数值数组、设备或已编译的计算内核。

### ArcTNExecutionPlan {#execution-plan}

`ArcTNExecutionPlan` 可保存为文件，在其他进程中加载；也可转换为收缩树，或在无切片时编译后重复执行。完整示例见[保存与复用收缩序](/docs/tutorial-reuse)。

#### 从报告创建 {#plan-from-schedule}

```python
ArcTNExecutionPlan.from_schedule(
    report,
    *,
    inputs,
    output,
    size_dict,
)
```

`report` 必须包含 SSA 路径，即用 `arctn_schedule(..., use_ssa=True)` 生成。三个网络参数均为必填项。返回 `ArcTNExecutionPlan`，不再次寻路。

#### 从文件加载 {#plan-load}

```python
ArcTNExecutionPlan.load(path)
```

读取并验证包含完整网络的 version 2 JSON 文件，返回 `ArcTNExecutionPlan`。验证失败抛出 `PlanValidationError`；文件不存在或无法读取时，仍可能抛出文件系统异常。

#### 从字典加载 {#plan-from-dict}

```python
ArcTNExecutionPlan.from_dict(artifact)
```

从已解析的字典加载，使用与文件加载相同的验证规则。

#### 保存文件 {#plan-save}

```python
plan.save(path)
```

以 JSON 保存网络、收缩序和切片信息，采用原子写入；不保存数组或进程内编译状态。

#### 导出字典 {#plan-to-dict}

```python
plan.to_dict()
```

返回包含网络、收缩序和切片信息的可序列化字典。

#### 检查网络或数组 {#plan-validate}

```python
plan.validate(
    inputs=None,
    output=None,
    size_dict=None,
    *,
    arrays=None,
)
```

三个网络参数要么全部省略，要么一起提供。可以另传 `arrays` 检查数组数量、形状和数据类型。成功返回 `None`，失败抛出 `PlanValidationError`。

#### 转换为线性路径 {#plan-to-linear-path}

```python
plan.to_linear_path()
```

返回 opt_einsum 使用的线性路径，不重新规划。该列表本身不携带切片信息。

#### 转换为收缩树 {#plan-to-tree}

```python
plan.to_tree()
```

返回 Cotengra `ContractionTree`，包含已有路径和 sliced indices。需要安装 Cotengra，不重新寻路。

#### 编译收缩序 {#plan-compile}

```python
plan.compile(
    *,
    backend="native",
)
```

返回 `ArcTNCompiledContraction`。仅在实际切片集合为空时可用；有切片时应使用 `plan.execute()`。

#### 按保存的收缩序执行 {#plan-execute}

```python
plan.execute(
    arrays,
    *,
    backend="native",
    return_info=False,
)
```

沿保存的路径和切片方案执行，不重新规划。默认返回结果数组；`return_info=True` 返回 `(result, info)`。信息字段随执行方式而异，不应假设与 `arctn_contract` 的计时字段完全相同。

## 数值收缩 {#execution-apis}

### arctn_contract {#contract}

```python
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,
)
```

**返回** 结果数组，或 `(result, info)`。原生后端返回 NumPy 数组；外部后端返回相应数组库的对象。所有输入须使用同一种受支持的数据类型：`float32`、`float64`、`complex64` 或 `complex128`。

外部后端可能异步执行。主机函数返回不代表设备计算完成；GPU 耗时需要显式同步后测量。`execution_wall_s` 只对 `native` 和 `numpy` 提供，其他后端为 `None`。完整字段见[执行后端](/docs/execution-backends)。

## 编译与复用 {#compiled-apis}

### ArcTNCompiledContraction {#compiled}

按固定网络和 SSA 收缩序预先准备执行：原生后端准备轴变换与矩阵乘法参数，外部后端编译 opt_einsum 表达式。该对象只在当前进程中使用，不能保存为文件。

#### 创建编译对象 {#compiled-compile}

```python
ArcTNCompiledContraction.compile(
    inputs,
    output,
    size_dict,
    *,
    ssa_path,
    backend="native",
)
```

`ssa_path` 必须完整合法。编译不寻路，也不支持切片集合。

#### 执行与统计 {#compiled-execute}

```python
result = compiled.execute(arrays)
info = compiled.stats()
```

直接调用 `compiled(arrays)` 与 `execute` 等价。多次调用使用同一网络和路径；每次调用仍验证输入。示例见[编译并重复执行](/docs/tutorial-reuse#compile)。

## 第三方接入 {#integration-apis}

### arctn_tree {#tree}

```python
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,
)
```

**返回** Cotengra `ContractionTree`，或 `(tree, info)`。需要 Cotengra 和 opt_einsum。树携带收缩路径及切片 index，可供 Quimb / Cotengra 执行。

### ArcTNOptimizer {#optimizer}

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

`ArcTNOptimizer` 将 ArcTN 的收缩序优化接入两类接口：opt_einsum 的路径接口与 Cotengra / Quimb 的收缩树接口。使用示例见[在 Quimb 中使用](/docs/tutorial-quimb)。

#### 返回路径 {#optimizer-call}

```python
optimizer(inputs, output, size_dict, memory_limit=None)
```

对应 `ArcTNOptimizer.__call__`，返回线性路径。由于列表无法表达切片集合，提供 `memory_limit` 或在 `ArcTNOptimizer` 中配置 `target_size` 后使用此调用，均会抛出 `NotImplementedError`。

#### 返回收缩树 {#optimizer-search}

```python
optimizer.search(inputs, output, size_dict)
```

对应 `ArcTNOptimizer.search`，委托 `arctn_tree` 返回含切片信息的 `ContractionTree`。

#### 收缩序优化与网络化简 {#optimizer-simplify}

`ArcTNOptimizer` 用于收缩序优化；只需要化简结构信息时，使用下面的 `arctn_simplify`。

## 网络化简 {#simplification-api}

### arctn_simplify {#simplify}

```python
arctn_simplify(inputs, output, size_dict)
```

**返回** 化简统计、前缀和缩减网络信息。不执行 Light / Heavy 搜索，也不执行数组计算。规则见[网络化简](/docs/simplification)。

## 错误处理 {#errors}

- `output` 中的 index 不得重复，且必须来自输入网络；该限制也适用于纯规划调用。
- 同一个 index 在单个输入张量中最多出现两次。
- 所有输入数组的数量、形状必须匹配网络，同一次执行使用同一种受支持的数据类型。
- 权重必须有限、非负，且不能同时为零。
- `target_size` 必须为正整数；如果未找到符合约束的方案，接口返回错误，不自动放宽约束。
- `backend` 默认为 `native`，不会根据数组自动选择或在失败后更换后端。

常见异常包括 `TypeError`、`ValueError`、`PlanValidationError`、`NotImplementedError` 和缺少可选依赖时的 `ImportError`。具体例子见[检查输入与处理错误](/docs/validation)。