QuatumQuill

执行计划

用 ArcTNExecutionPlan 固定网络、SSA path 和切片集合，在不重新寻路的前提下保存、验证、转换或执行。

本页目录

五种表示及其边界

表示 保存什么 主要用途
SSA path 二元收缩拓扑 重放收缩顺序；本身不含网络或切片集合
arctn_schedule report 路径、指标和搜索诊断 检查一次 planning；不是长期执行格式
ArcTNExecutionPlan 规范化网络、SSA path、切片集合和 target 声明 跨进程保存、验证和重放
ArcTNCompiledContraction 面向一个 backend 的进程内执行几何 重复执行无切片计划
Cotengra ContractionTree 树结构和 sliced indices Quimb/Cotengra 生态互操作

术语边界

ArcTNExecutionPlan 是 planning 与 numerical execution 之间稳定的 backend-neutral data boundary。它不是数组程序的通用 compiler IR，也不是已编译 kernel。

生命周期

先用 arctn_plan 生成计划，再保存或执行。加载后的计划复用原有路径和切片集合，不重新运行 planner；backend 在 execute 或 compile 时选择。

python
from arctn import ArcTNExecutionPlan, arctn_plan

plan = arctn_plan(
    inputs, output, size_dict,
    preset="heavy", seed=0,
    target_size=2**24, slicing_mode="fixed",
)
plan.save("plan.json")

loaded = ArcTNExecutionPlan.load("plan.json")
loaded.validate(inputs, output, size_dict, arrays=arrays)
result = loaded.execute(arrays, backend="native")

version 2 JSON 的保存内容

字段 含义
schema / schema_version arctn-execution-plan / 2
path_format ssa-v1；不会用整数对形状猜测路径坐标系
network 稠密整数标签的 inputs、output 和有序 size_dict
network_canon 保留张量顺序、输出顺序和维度的 canonical identity
ssa_path 已经验证可在 embedded network 上完整重放的路径
sliced.legs 执行时必须使用的精确切片腿集合；无切片时明确为空数组
target_size 可选的每个 slice 二元收缩结果元素数上限；单张量网络则检查最终输出
metrics / planning / provenance 紧凑指标、公开调用设置和版本来源

Python 调用可以使用任意可哈希腿标签。持久化时按首次出现顺序映射为稠密整数标签，避免 pickle 任意 Python 对象。内存中新建的 plan 可保留原标签供查看；加载后的 plan 使用文件中的整数标签。

加载 version 2 文件时，Rust 会重新验证网络、SSA path、切片集合和 target 声明，并复算文件中出现的核心路径与切片指标。planning 和 provenance 用于说明计划怎样产生，不参与数值执行正确性的判定。

精确 target 声明

target_size 不是 RSS、VRAM、allocator cache 或 backend workspace 上限。version 2 只要声明 target，就必须同时保存正整数 target_size、匹配的 log2 值，以及 memory_constraint_metric="max_intermediate_elements_per_slice"；加载时 Rust 会在真实路径与切片集合上重新复核。

转换与执行

方法 是否重新规划 限制
to_linear_path() 否 返回 opt_einsum recycled linear path
to_tree() 否 需要 Cotengra；把保存的 sliced legs 写入 tree
execute(arrays, backend=...) 否 执行文件中确定的 path 与 slice set
compile(backend=...) 否 只接受无切片 plan；返回进程内 compiled object

plan 不保存数组、device、backend 或 kernel。plan.execute()、plan.to_tree() 和 plan.compile() 都不重新运行 planner。native 使用 ArcTN Rust CPU executor；其他显式名称交给 opt_einsum 和相应数组库。external backend 的切片当前由 Python 顺序枚举 assignments；native 切片由 Rust/Rayon 执行。

切片计划

有切片 plan 不能 compile，因为 ArcTNCompiledContraction 当前不承载 sliced legs；应使用 plan.execute() 或 plan.to_tree()。

兼容性

下载原始 Markdown 文档 ↓