---
title: "Light / Heavy 接口"
description: "选择 Light 或 Heavy，并通过 Python、Rust 或命令行完成收缩序优化。"
eyebrow: "自动收缩序优化"
---

## 预设选择 {#comparison}

Light 侧重较低的搜索开销，适合快速取得一条路径；Heavy 投入更多搜索工作，适合更重视路径质量的任务。两者使用相同的网络输入和优化目标。

| 项目 | Light | Heavy |
| --- | --- | --- |
| 侧重点 | 搜索开销 | 路径质量 |
| 常见用法 | 快速求得可执行路径 | 为较昂贵的收缩或重复执行投入更多搜索时间 |
| 公共调用方式 | `preset="light"` | `preset="heavy"` |

两者都返回完整路径及可选报告。Light / Heavy 的实现由单独的编译库提供，完整 Python wheel 已包含并自动加载它；源码构建版本需要[单独配置](/docs/installation#engine)。具体的内部候选分配与阶段记录不属于公开接口。

Light 和 Heavy 不表示不同的数值精度。数组类型与执行后端另行指定；不同收缩顺序可能产生不同的浮点舍入误差。

## Python、Rust 与命令行接口 {#interfaces}

```python
from arctn import arctn_path

light_path = arctn_path(
    inputs, output, size_dict, preset="light", seed=3
)
heavy_path = arctn_path(
    inputs, output, size_dict, preset="heavy", seed=3
)
```

```rust
use arctn::{auto_path_preset, AutoPreset};

let result = auto_path_preset(
    &network, AutoPreset::Light, 3, None,
)?;
```

```bash
tnpath network.json --method auto --preset light --seed 3
```

## 在自己的网络上比较 {#comparison-protocol}

选择预设时，可以在自己的代表性网络上比较收缩序优化的实际耗时与最终路径指标。Light 与 Heavy 的相对收益会随网络结构、目标函数、线程环境、随机种子和时间限制变化。

| 固定条件 | 记录结果 |
| --- | --- |
| 相同网络、输出 index 与维度 | 规划是否成功以及返回路径格式 |
| 相同 PlannerObjective 权重 | log10\_flops、log2\_read\_write 与 log2\_max\_size |
| 相同物理核、线程设置和外部负载 | 规划接口耗时与端到端耗时 |
| 明确随机种子集合、成功运行次数与总运行次数 | 每次运行的结果，而不只报告最好一次 |

Heavy 使用较大的搜索预算，但不保证每次都优于 Light。具体的速度和路径质量差异需在相同测试条件下测量。

## 线程设置 {#threads}

推荐从 8 个工作线程开始，在程序启动前设置 Rayon 线程池宽度：

```bash
RAYON_NUM_THREADS=8 python plan.py
```

| 设置 | 控制内容 |
| --- | --- |
| `RAYON_NUM_THREADS` | Rayon 工作线程数，不预留独占物理核心 |
| CPU affinity | 进程可在哪些 CPU 上运行 |
| NUMA 绑定 | CPU 和内存的放置位置 |

有更多 CPU 资源时，可按 8 个线程递增，具体起点数量见[推荐线程配置](/docs/parallelism#recommended-threads)。各起点共享线程池；更多线程可能增加搜索工作量，不表示线程数翻倍就能使寻路时间减半。计时方法见[计时与 CPU 使用量](/docs/performance-boundaries)。

## 接口约定 {#preset-boundary}

更换 Light 或 Heavy 不改变网络输入格式、路径格式与返回类型。公共接口选择预设并设置目标、种子和时间限制，不要求调用者安排各个内部阶段。