Rust API

按自动收缩序优化、路径生成、树搜索、网络化简、切片和文件读写查阅接口。

本页目录

自动收缩序优化

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

类型 / 函数	用途
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,
)?;

核心类型与模块

类型	含义
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、切片数与单片路径指标，字段见切片结果

低层模块

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

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

路径生成

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

greedy

rust

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

导入 arctn::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

rust

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

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

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 在末尾增加目标参数；精确性范围见动态规划。

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

rust

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

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

树搜索与重构

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

reconfigure_path

rust

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

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

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

rust

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

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

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

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

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 关闭连续无改善停止条件；仍返回运行期间保留的最佳路径。

网络化简与路径检查

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

simplify

rust

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

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

stitch

rust

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

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

simulate_path

rust

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

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

切片选择

固定路径的切片选择不改变传入路径。切片执行见固定路径切片与执行。

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。

数值执行

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，见编译与复用。

切片执行

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,
)?;

收缩序文件读写

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

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

下载原始 Markdown 文档 ↓