方法组合调度

组合调用路径生成与局部改进方法，通过 Light 或 Heavy 预设完成收缩序优化。

本页目录

一次调用怎样完成搜索

ArcTN 提供 Light 和 Heavy 两种搜索模式，将路径生成、局部改进和结果选择组织在一次调用中。调用者提供张量网络和优化目标，通过 preset="light" 或 preset="heavy" 选择模式，不必逐个调用底层搜索方法。

这里的“候选”是一条完整收缩路径，已经指定从输入张量到最终结果的全部两两收缩步骤，而不是某一步选中的两个张量。方法组合调度负责安排这些路径的生成和改进，再按本次优化目标比较结果。

环节	处理内容
生成候选	在原始网络及化简网络上，按预设调用随机贪心、超图二分等方法
改进路径	按预设和停止条件，对候选进行子树重构、回火等局部搜索
返回结果	按本次目标函数选择路径；请求 `target_size` 时，再处理切片约束

化简会先确定一部分收缩步骤，再在剩下的较小网络上搜索。把两部分接起来后，得到的仍是原始输入网络上的完整路径，因此可以与直接在原网络上生成的路径比较。具体采用哪些生成方法和改进步骤取决于预设；某些步骤也可能因停止条件而跳过。两种预设的区别见Light / Heavy 接口。

候选树图和选择原理统一放在张量网络与收缩路径，目标函数见路径指标与优化目标。

入口	适用情况	返回结果
arctn_path	选择 Light 或 Heavy 并规划路径	一条 SSA 或 linear path
arctn_schedule	需要查看收缩序、工作量和切片信息	包含路径、目标、指标与可选切片结果的字典
arctn_plan	优化收缩序，并保存网络与切片信息	可保存的 ArcTNExecutionPlan
arctn_tree	把规划结果转换为 Cotengra ContractionTree	可供 Cotengra / Quimb 使用的树
arctn_contract	规划后立即执行数值收缩	数值结果，以及可选的最终信息

可运行的例子见快速开始，完整签名见 Python API。

参数	作用	说明
preset	选择 `light` 或 `heavy`	默认值是 `heavy`
seed	设置本次随机搜索的基础种子	影响搜索过程中的随机选择，不设置输入数组的数值
max_time	搜索时间限制，单位为秒	在算法检查点生效，实际返回时间可能稍晚
flops_weight / read_write_weight	固定本次调用的完整路径目标函数	必须有限、非负，且不能同时为零
target_size	限制每个切片允许的最大中间张量元素数	不等于 RSS、显存或并发切片总内存
slicing_mode	选择 `fixed` 或 `dynamic`	`dynamic` 必须同时提供 `target_size`
rate_enabled	是否启用基于估计收缩工作量的提前停止	适用于 `arctn_schedule` 和 `arctn_plan`，默认 `True`

target_size 和 slicing_mode 适用于 arctn_schedule、arctn_plan、arctn_tree 和 arctn_contract。只返回路径的 arctn_path 不接收这两个参数。

权重决定比较路径时更重视什么。例如，flops_weight=1、read_write_weight=0 表示只按 FLOPs 选优；默认的 (1, 64) 同时考虑 FLOPs 与逻辑读写量。定义及数值例子见优化目标。

rate_enabled=False 只关闭这一项提前停止，不关闭搜索自身的收敛判断或 max_time。固定随机种子也不代表每次耗时完全一致。若任务要求到时立即结束整个进程，应在调用程序外设置超时控制，例如使用作业调度器的时间限制。

arctn_schedule 返回收缩序和结构化报告；arctn_plan 返回 ArcTNExecutionPlan，同时保存网络、收缩序和切片信息，供后续执行。

报告可用于检查返回路径及其指标，但仅凭最终报告不能重建搜索中所有未公开的候选。字段说明见使用 Heavy：读取返回结果。

Light 和 Heavy 采用启发式搜索，不保证全局最优，也不把提前停止当作局部最优的证明。具体说明见最佳候选的含义。

提供 target_size 时，成功返回的方案满足每个切片中二元收缩结果的元素数限制；单张量网络另检查最终输出。若无法满足限制，接口返回错误。target_size 不等于进程 RSS、显存或所有并发切片的总内存。