---
title: "Rust API"
description: "按自动收缩序优化、路径生成、树搜索、网络化简、切片和文件读写查阅接口。"
eyebrow: "API 参考"
---

## 自动收缩序优化 {#facade}

Rust 调用 Light / Heavy 前，需通过 `ARCTN_ENGINE_LIBRARY` 指定兼容的编译库，见[安装配置](/docs/installation#engine)。下面的独立算法与数值执行函数不依赖该编译库。

| 类型 / 函数 | 用途 |
| --- | --- |
| AutoPreset::{Light, Heavy} | 搜索预设，默认 Heavy |
| SlicingMode::{Fixed, Dynamic} | 两种公开切片模式 |
| auto\_path\_preset | 使用默认目标，不切片 |
| auto\_path\_preset\_with\_objective | 显式指定 PlannerObjective |
| auto\_path\_preset\_to\_size | 使用固定路径切片 |
| auto\_path\_preset\_to\_size\_with\_mode | 指定 Fixed 或 Dynamic |
| auto\_path\_preset\_to\_size\_with\_objective | 固定路径切片，指定目标 |
| auto\_path\_preset\_to\_size\_with\_mode\_and\_objective | 指定切片模式、目标函数与 rate\_enabled |

```rust
use arctn::{
    auto_path_preset_with_objective, AutoPreset,
    PlannerObjective, TensorNetwork,
};

let objective = PlannerObjective::new(1.0, 64.0)?;
let plan = auto_path_preset_with_objective(
    &net, AutoPreset::Heavy, 0, None, objective,
)?;
```

## 核心类型与模块 {#core-types}

| 类型 | 含义 |
| --- | --- |
| TensorNetwork | 整数 index 编号、输入张量、输出 index 与维度 |
| SsaPath | 每一步引用当前 SSA 节点编号的二元收缩序列 |
| PathStats | 路径模型指标，不是硬件计数器 |
| PlannerObjective | 每次调用指定的 FLOPs 与读写量权重 |
| AutoResult | `path`、`stats`、可选 `sliced: Option<SliceResult>` 和搜索耗时 `wall_s` |
| ExecutionPlanNetwork | 第 2 版收缩序文件中保存的整数标签网络 |
| LoadedExecutionPlan | 验证后的 SSA 路径、切片和大小限制 |
| EmbeddedExecutionPlan | 第 2 版收缩序文件中的网络与执行信息 |
| DenseTensor\<T\> | 原生执行器使用的行主序稠密张量 |
| Scalar | 原生执行器对元素类型的要求 |
| CompiledContraction | 为固定网络与 SSA 路径准备的可复用执行对象；不保存输入数组 |
| SliceResult | 切片 index、切片数与单片路径指标，字段见[切片结果](/docs/slicing#result) |

### 低层模块 {#modules}

| 模块 | 职责 | 调用条件 |
| --- | --- | --- |
| paths | 贪心、动态规划、超图二分和预算控制搜索 | 按所需算法直接调用 |
| tree | 收缩树、局部旋转、子树重构、模拟退火和副本交换 | 需要提供初始路径并设置参数 |
| simplify | 确定性网络化简与路径拼接 | 可单独使用 |
| slice | 切片 index 选择、切片与重构交替优化、切片执行 | 使用 Light / Heavy 时可通过相应的收缩序优化接口调用 |
| contract / compiled | 一次执行与可复用编译执行 | 需要合法 SSA path |

低层函数可以单独调用。它们的参数独立于 Python 的 Light / Heavy 接口。

## 路径生成 {#path-search}

以下签名省略 `pub`，类型名称使用短名。除单次确定性贪心外，不带目标参数的函数默认使用 `PlannerObjective::FIXED`，即 $F+64R$。

### greedy {#greedy}

~~~rust
fn greedy(
    net: &TensorNetwork,
) -> Result<(SsaPath, PathStats), String>;
~~~

导入 `arctn::greedy`。运行一次确定性贪心；没有额外目标参数。

### random_greedy {#random-greedy}

~~~rust
fn random_greedy(
    net: &TensorNetwork,
    ntrials: usize,
    seed: u64,
) -> Result<(SsaPath, PathStats), String>;
~~~

导入 `arctn::random_greedy`。`ntrials` 必须大于零。自定义目标使用 `arctn::paths::greedy::random_greedy_with_objective`，在上述参数后增加 `objective: PlannerObjective`。

### random_greedy_simplified {#random-greedy-simplified}

~~~rust
fn random_greedy_simplified(
    net: &TensorNetwork,
    ntrials: usize,
    seed: u64,
) -> Result<(SsaPath, PathStats), String>;
~~~

导入 `arctn::random_greedy_simplified`。在缩减网络上搜索，返回原网络的完整路径。

### optimal_dp {#optimal-dp}

~~~rust
fn optimal_dp(
    net: &TensorNetwork,
    max_n: usize,
) -> Result<(SsaPath, PathStats), String>;
~~~

导入 `arctn::optimal_dp`。`max_n` 限制完整输入网络的张量数。`arctn::paths::optimal::optimal_dp_with_objective` 在末尾增加目标参数；精确性范围见[动态规划](/docs/structured-search#optimal-dp)。

### bisect {#bisect}

~~~rust
fn bisect(
    net: &TensorNetwork,
    ntrials: usize,
    seed: u64,
    cutoff: usize,
) -> Result<(SsaPath, PathStats), String>;
~~~

导入 `arctn::paths::bisect::bisect`。`cutoff` 限制在 2–20。同模块的 `bisect_with_objective` 在末尾增加目标参数，用于比较完整候选；小问题中的 DP 仍使用默认目标。

### order_dp {#order-dp}

~~~rust
fn order_dp(
    net: &TensorNetwork,
    order: &[usize],
) -> Result<(SsaPath, PathStats), String>;
~~~

导入 `arctn::paths::ordertree::order_dp`。`order` 必须包含所有输入编号且不重复；只在该叶节点顺序下优化括号结构。同模块的 `order_dp_with_objective` 在末尾增加目标参数。

## 树搜索与重构 {#tree-search}

以下函数位于 `arctn::tree`。除 `treesa_path` 外，也从 `arctn` 根模块导出。每个函数都有同模块的 `*_with_objective` 版本，最后增加 `objective: PlannerObjective`；不带该参数的版本使用默认目标 $F+64R$。

### reconfigure_path {#reconfigure-path}

~~~rust
fn reconfigure_path(
    net: &TensorNetwork,
    path: &SsaPath,
    subtree_size: usize,
    max_sweeps: usize,
) -> Result<(SsaPath, PathStats), String>;
~~~

`subtree_size` 是局部小网络的输入节点上限，不一定等于原始张量数。

### anneal_path {#anneal-path}

~~~rust
fn anneal_path(
    net: &TensorNetwork,
    path: &SsaPath,
    niters: usize,
    seed: u64,
    t0_rel: f64,
    t1_rel: f64,
) -> Result<(SsaPath, PathStats), String>;
~~~

一条模拟退火链；相对温度从 `t0_rel` 向 `t1_rel` 变化。

### anneal_paths {#anneal-paths}

~~~rust
fn anneal_paths(
    net: &TensorNetwork,
    path: &SsaPath,
    chains: usize,
    niters: usize,
    seed: u64,
) -> (SsaPath, PathStats);
~~~

多条独立退火链，返回一条最佳路径。`chains=0` 按至少一条链处理。此函数不返回 `Result`，非法初始路径可能触发 panic；调用前应验证网络与路径。

### treesa_path {#treesa-path}

~~~rust
fn treesa_path(
    net: &TensorNetwork,
    path: &SsaPath,
    chains: usize,
    beta0: f64,
    beta1: f64,
    beta_steps: usize,
    sweeps_per_beta: usize,
    reconf_interval: usize,
    reconf_size: usize,
    seed: u64,
) -> Result<(SsaPath, PathStats), String>;
~~~

按逆温度推进，逐次遍历树。`reconf_interval=0` 关闭周期性子树重构。

### temper_path {#temper-path}

~~~rust
fn temper_path(
    net: &TensorNetwork,
    path: &SsaPath,
    n_replicas: usize,
    rounds: usize,
    moves_per_round: usize,
    t_min: f64,
    t_max: f64,
    reconf_interval: usize,
    reconf_size: usize,
    seed: u64,
) -> Result<(SsaPath, PathStats), String>;
~~~

所有副本由同一路径初始化；局部更新与相邻温度交换交替进行。

### temper_paths {#temper-paths}

~~~rust
fn temper_paths(
    net: &TensorNetwork,
    init_paths: &[SsaPath],
    n_replicas: usize,
    rounds: usize,
    moves_per_round: usize,
    t_min: f64,
    t_max: f64,
    reconf_interval: usize,
    reconf_size: usize,
    seed: u64,
    patience: usize,
) -> Result<(SsaPath, PathStats), String>;
~~~

从非空起始路径集合初始化。`patience=0` 关闭连续无改善停止条件；仍返回运行期间保留的最佳路径。

## 网络化简与路径检查 {#simplification}

以下函数均从 `arctn` 根模块导出。结构化简不执行数值数组。

### simplify {#simplify}

~~~rust
fn simplify(
    net: &TensorNetwork,
) -> Simplified;
~~~

返回 `prefix`、`reduced` 和 `map`。该函数不通过 `Result` 报告输入错误；调用前应验证网络。

### stitch {#stitch}

~~~rust
fn stitch(
    n_orig: usize,
    prefix: &SsaPath,
    map: &[usize],
    reduced_path: &SsaPath,
) -> SsaPath;
~~~

前缀与映射必须来自同一次化简，缩减路径须匹配该缩减网络。拼接后用 `simulate_path` 检查。

### simulate_path {#simulate-path}

~~~rust
fn simulate_path(
    net: &TensorNetwork,
    path: &SsaPath,
) -> Result<PathStats, String>;
~~~

检查 SSA 引用和最终结果，重算路径指标；不执行张量数组。

## 切片选择 {#slice-selection}

固定路径的切片选择不改变传入路径。切片执行见[固定路径切片与执行](#sliced)。

### find_slices_to_size {#find-slices-to-size}

~~~rust
fn find_slices_to_size(
    net: &TensorNetwork,
    path: &SsaPath,
    target_size: usize,
) -> Option<SliceResult>;
~~~

导入 `arctn::find_slices_to_size`。目标为元素数；目标为零或未找到满足限制的合法方案时返回 `None`。

## 数值执行 {#contraction}

### contract_network {#contract-network}

~~~rust
fn contract_network<T: Scalar>(
    net: &TensorNetwork,
    tensors: Vec<DenseTensor<T>>,
    path: &SsaPath,
) -> Result<DenseTensor<T>, String>;
~~~

导入 `arctn::contract_network`。沿传入的 SSA 路径执行，不重新寻路，也不选择切片。输入数组的顺序与维度须匹配网络；返回张量的轴顺序与 `net.output` 一致。`tensors` 按值传入，所有权移入函数。输入或路径无效时返回 `Err(String)`。

固定网络和路径的重复执行可使用 `CompiledContraction`，见[编译与复用](/docs/compiled-contraction)。

## 切片执行 {#sliced}

```rust
use arctn::{
    auto_path_preset_to_size, contract_network_sliced,
    AutoPreset,
};

let plan = auto_path_preset_to_size(
    &net, AutoPreset::Heavy, 0, None, 1 << 24,
)?;
let slice = plan.slice.as_ref().ok_or("missing slice plan")?;
let out = contract_network_sliced(
    &net, &tensors, &plan.path, &slice.legs,
)?;
```

## 收缩序文件读写 {#execution-plan}

| 函数 | 用途 |
| --- | --- |
| complete\_execution\_plan\_v2 | 在 tnpath 记录中加入网络、格式标识和规范化元数据，并验证保存内容 |
| parse\_embedded\_execution\_plan | 读取包含网络结构的第 2 版收缩序文件 |
| parse\_execution\_plan\_for\_network | 读取第 1 版、第 2 版或显式允许的旧格式收缩序文件，并与传入网络核对 |

第 1 版文件只保存用于核对网络的标识，不包含网络结构，因此读取时必须提供网络。第 2 版文件还包含规范化后的网络结构。没有格式标识的旧文件仍需要显式允许才能读取。