UnFold

arti.nn.UnFold 是 ARTI 1.7.0 受支持的 1.x 核心层。它从紧凑输入中查询新值，把新值与每个原输入实例合并，并学习随样本变化的 hard layout。

import torch
from arti.nn import UnFold

x = torch.randn(4, 16, 64)
layer = UnFold(dim=64, exposed=8)
y = layer(x)

assert y.shape == (4, 24, 64)

动态目标长度

exposed 表示最大可训练展开容量。target_length 让同一个层只激活当前调用所需的参数前缀：

layer = UnFold(dim=64, exposed=32)

short = layer(torch.randn(4, 8, 64), target_length=12)
wide = layer(torch.randn(4, 32, 64), target_length=48)

assert short.shape == (4, 12, 64)
assert wide.shape == (4, 48, 64)

输入长度为 N 时，活跃查询数是 target_length - N，且必须落在 1..exposed。这是调用级输出 shape，不代表同一 batch 中每个样本可以拥有不同物理 shape。省略 target_length 时仍返回 [B, N + exposed, D]。

“保值”的准确含义

每个原输入实例都通过 hard gather 传输，并在输出中恰好出现一次；它不会被平均、插值、投影或丢弃，但位置与邻接关系可以改变。新查询值是可学习变换，不享有同样的保值保证。

y, queried, source_index = layer(
    x,
    return_exposed_mask=True,
    return_source_index=True,
)

source_index < N 表示原输入实例；大于等于 N 的索引表示查询值。该映射会随样本变化。

Mask、guide 与规范布局

输入 mask 由同一个 hard layout 传输。guide 只影响布局选择，不改变被传输的值。layout_mode="canonical" 接受一维排序坐标；可选 exposed_guide 可以完整指定查询值坐标。

layout = UnFold(
    dim=64,
    exposed=8,
    guide_dim=1,
    layout_mode="canonical",
)
y = layout(x, guide=guide, exposed_guide=exposed_guide)

exposed_mask 可按样本控制活跃查询候选是否有效，但不会改变一次调用的 tensor shape。

能力边界

• UnFold 与 torch.nn.Unfold 无关。
• 它不是 Fold 的数学逆，也不能恢复此前已经丢失的信息。
• 动态长度受构造时 exposed 容量限制。
• dense greedy 和 auction 研究后端有独立限制；默认 sort 后端使用 argsort 与 gather。
• 文档列出的 CUDA 融合路径有受测 dtype、维度与工作区门禁；其他配置回退普通 PyTorch。

可在工作区融合实验室中交互检查这些约束。