QuatumQuill

Python API

公开函数、类型、参数、返回值与错误边界。

本页目录

公开导出

符号 用途
arctn_path 只寻找路径；返回 linear path 或 SSA path
arctn_schedule 只规划并返回结构化报告，可包含切片方案
arctn_plan 规划一次并返回可保存的 ArcTNExecutionPlan
ArcTNExecutionPlan 加载、验证、转换或执行一个已确定的计划
PlanValidationError 计划文件、网络或数组与执行契约不一致
arctn_tree 规划后返回 Cotengra ContractionTree
arctn_contract 规划并执行一次数值收缩
ArcTNCompiledContraction 编译并重复执行同一网络和 SSA path
ArcTNOptimizer 向 opt_einsum 返回 path，向 Cotengra/Quimb 返回 ContractionTree
arctn_simplify 只分析确定性网络化简

规划报告

完整规划报告由 arctn_schedule 返回；这个入口只规划，不执行张量数组。

arctn_plan 与 ArcTNExecutionPlan

text
arctn_plan(inputs, output, size_dict, *, preset="heavy", seed=0, target_size=None, slicing_mode="fixed", max_time=None, flops_weight=1.0, read_write_weight=64.0, rate_enabled=True)
参数 类型 说明
target_size int | None 可选的单片二元收缩结果元素数上限；单张量网络另检查最终输出。
slicing_mode Literal["fixed", "dynamic"] 固定路径切片或 slice-and-reconfigure。
rate_enabled bool 是否启用公开的协作式提前停止控制；不改变返回路径必须完整合法的要求。

返回： ArcTNExecutionPlan。函数只规划，不读取或执行 arrays。

方法 作用
from_schedule(report, ...) 把 use_ssa=True 的现有 schedule report 包装成 plan，不再次寻路
from_dict(artifact) / load(path) 用 Rust validator 读取 self-contained version 2 artifact
to_dict() / save(path) 导出或原子写入 JSON
validate(..., arrays=...) 复核网络结构、维度与可选数组元数据
to_linear_path() 转换为 opt_einsum recycled linear path
to_tree() 转换为 Cotengra ContractionTree，不重新规划
compile(backend=...) 只为无切片 plan 准备进程内 compiled object
execute(arrays, backend=...) 执行保存的 path 与 exact slice set，不重新规划

计划边界

ArcTNExecutionPlan 不保存数组、设备、backend 或已编译 kernel。Python load 只接受 self-contained version 2；带切片 plan 不能 compile，应使用 execute 或 to_tree。

arctn_path

text
arctn_path(inputs, output, size_dict, *, preset="heavy", seed=0, use_ssa=False, max_time=None, flops_weight=1.0, read_write_weight=64.0)
参数 类型 说明
inputs Sequence[Sequence[Hashable]] 按张量顺序给出腿标签；每个标签必须可哈希。
output Sequence[Hashable] 结果中保留的腿及轴顺序。
size_dict Mapping[Hashable, int] 精确覆盖已使用腿的正整数维度。
preset Literal["light", "heavy"] 默认 Heavy。
seed int 显式随机种子。
use_ssa bool false 返回 recycled linear path；true 返回 SSA path。
max_time float | None 有限正数；cooperative limit，不是硬超时。
flops_weight float FLOPs 权重，有限且非负。
read_write_weight float read/write complexity 权重，有限且非负；两个权重不能同时为 0。

返回： list[tuple[int, int]]。该函数不接收 target_size，因为 path 返回值无法同时携带 sliced legs。

arctn_schedule

text
arctn_schedule(inputs, output, size_dict, *, preset="heavy", seed=0, target_size=None, slicing_mode="fixed", max_time=None, use_ssa=False, flops_weight=1.0, read_write_weight=64.0, rate_enabled=True)
参数 类型 说明
target_size int | None 单个 slice 中二元收缩结果的元素数上限；单张量网络另检查最终输出。
slicing_mode Literal["fixed", "dynamic"] 默认 fixed；dynamic 必须同时提供 target_size。
rate_enabled bool 是否启用公开的协作式提前停止控制；false 主要用于固定工作量实验。
use_ssa bool 控制报告中的 path 编码。

返回： dict。稳定结果字段包括最终 path、结构路径指标、objective 与可选 slicing 结果；额外诊断字段可能随版本变化。

python
report = arctn_schedule(
    inputs, output, size_dict,
    preset="heavy", seed=0, use_ssa=True,
    target_size=2**24, slicing_mode="fixed",
)
print(report["path"])
print(report["sliced_legs"])

arctn_tree

text
arctn_tree(inputs, output, size_dict, *, preset="heavy", seed=0, target_size=None, slicing_mode="fixed", max_time=None, flops_weight=1.0, read_write_weight=64.0, return_info=False)
参数 类型 说明
target_size int | None 可选的单片二元结果精确元素数上限；单张量网络另检查最终输出。
slicing_mode Literal["fixed", "dynamic"] 选择固定路径切片或 slice-and-reconfigure。
return_info bool true 返回 (tree, info)。

返回： cotengra.ContractionTree，或 (tree, info)。需要安装 Cotengra 和 opt_einsum。

arctn_tree 是 Python 高层转换入口，不是 TreeSA 算法，也不是 Rust 的 arctn::tree 模块。

arctn_contract

text
arctn_contract(inputs, output, size_dict, arrays, *, preset="heavy", seed=0, target_size=None, slicing_mode="fixed", max_time=None, backend="native", flops_weight=1.0, read_write_weight=64.0, return_info=False)
参数 类型 说明
arrays Sequence[array] 数量、shape 与 inputs 一致；所有数组使用相同 dtype。
backend str native，或显式 opt_einsum backend 名称；不接受 auto。
return_info bool true 返回 (result, info)。

返回： native 返回 numpy.ndarray；外部后端返回相应 backend 的数组对象。return_info=True 时返回 (result, info)。native 支持 float32、float64、complex64、complex128。

异步后端

外部数组后端可能异步，主机函数返回不代表设备已完成。arctn_contract 仅对 native 和 numpy 提供 execution_wall_s，其他后端均为 None。execution_dispatch_wall_s 记录主机端执行调用，execution_total_host_wall_s 还包括输入准备和执行设置。测量设备完成时间时，需要显式同步所选后端并单独计时。

ArcTNCompiledContraction

python
compiled = ArcTNCompiledContraction.compile(
    inputs, output, size_dict,
    ssa_path=ssa_path, backend="native",
)
result = compiled.execute(arrays)
stats = compiled.stats()

ArcTNOptimizer 与 arctn_simplify

text
ArcTNOptimizer(*, preset="heavy", seed=0, max_time=None, flops_weight=1.0, read_write_weight=64.0, target_size=None, slicing_mode="fixed")
参数 类型 说明
preset Literal["light", "heavy"] 选择公开 Auto preset；默认 Heavy。
seed int 显式 base seed。
max_time float | None 协作式 planning limit，不是硬墙钟。
flops_weight float FLOPs 权重；必须有限且非负。
read_write_weight float read/write complexity 权重；两个权重不能同时为 0。
target_size int | None tree 接口中每个 slice 的二元结果元素数硬上限；单张量网络另检查最终输出。
slicing_mode Literal["fixed", "dynamic"] 默认 fixed；dynamic 必须同时提供 target_size。

返回： __call__ 返回 recycled linear path；search 返回 cotengra.ContractionTree。

python
path_optimizer = ArcTNOptimizer(
    preset="heavy", seed=0, max_time=30,
)
linear_path = path_optimizer(inputs, output, size_dict)

tree_optimizer = ArcTNOptimizer(
    preset="heavy", seed=0,
    target_size=2**24, slicing_mode="fixed",
)
tree = tree_optimizer.search(inputs, output, size_dict)

summary = arctn_simplify(inputs, output, size_dict)

ArcTNOptimizer.__call__ 为 opt_einsum 的 path-only 协议返回 linear path，因此不能用 memory_limit 携带切片信息，并且配置了 target_size 时会拒绝 path-only 调用。ArcTNOptimizer.search() 委托给 arctn_tree，返回可携带 sliced indices 的 ContractionTree，供 Cotengra/Quimb 的 tree dispatch 使用。arctn_simplify 只返回确定性化简分析，不运行 Auto，也不执行数组。

统一错误边界

下载原始 Markdown 文档 ↓