Half、Fold、Pulse 与 UnFold

这些 arti.nn 模块都可作为独立 PyTorch 层使用。它们与半透膜可见性路由不是同一机制：Half 改变特征幅值，半透膜则为 token 分配可见域。

Half：无状态生存激活

对输入 x，Half 根据 abs(x) 计算显著性不足量，并用 base ** deficit 缩放各值。默认配置下，绝对值至少为 1 的值原样通过，较弱值平滑衰减。shape 与 dtype 保持不变，模块没有可训练参数。

import torch
import arti.nn as ann

x = torch.randn(4, 128, 64)                    # 任意 shape
y = ann.Half(threshold=1.0, base=0.5, scale=1.0)(x)
assert y.shape == x.shape

stochastic=True 只在训练模式采样生存状态；评估仍是确定性的。它是激活函数，不是“半透膜”。

Fold：从 N 个槽压缩到 K 个槽

fold = ann.Fold(k=16, dim=64)
x = torch.randn(4, 128, 64)                    # [B, N, D]
mask = torch.ones(4, 128, dtype=torch.bool)     # [B, N]
q = torch.rand(4, 128)                         # [B, N]，值截断到 [0, 1]
z = fold(x, q=q, mask=mask)
assert z.shape == (4, 16, 64)                  # [B, K, D]

mask 表示槽位是否有效；q 引导显著性，两者应分开。默认 soft 模式使用可微分配；topk 稀疏化每个输出槽的输入候选。mode="attention" 要求静态 dim 且可被 heads 整除。

Pulse：投影、生存、压缩

pulse = ann.Pulse(k=8, dim=64, hidden_dim=128)
workspace, info = pulse(x, q=q, mask=mask, return_info=True)
assert workspace.shape == (4, 8, 64)

Pulse 是 LearnedPulse 的公开别名。它依次执行可学习片段投影、可选 Half 与 Fold。q_topk 在投影前按外部引导剪枝；fold_topk 控制 Fold 稀疏度。refine=True 要求提供 dim，并增加 MLP 或门控残差细化。

x [B,N,D] + q/mask [B,N]
→ 可选 q_topk
→ 可学习片段投影
→ Half（除非 use_half=False）
→ Fold 在 N 个片段上分配
→ 工作区 [B,K,D]
→ 可选残差细化

为什么 Pulse 输入可以 concat

Pulse 把 N 维视为过完备片段地址空间，并始终输出 K 个槽，因此兼容片段集合可先沿 N 拼接，再交给同一组 Pulse 参数。concat_visual_fields 是经过约束检查的辅助函数：

field = ann.VisualField(patch_size=(4, 4))
left = field(glyph, window=(0, 0, 16, 48), field_id=0.0)
right = field(glyph, window=(0, 48, 16, 48), field_id=1.0)
visual = ann.concat_visual_fields(left, right)

assert visual.fragments.shape[1] == left.fragments.shape[1] + right.fragments.shape[1]
workspace = ann.Pulse(k=8, dim=visual.fragments.shape[-1])(
    visual.fragments, mask=visual.mask
)

成立条件是：batch、源几何、片段宽度、位置策略、device 和 dtype 一致。像素不会混合或缩放；绝对边界与 field_id 仍保留在各片段中。如果特征 schema 不同、位置缺失或坐标框架不兼容、任一 mask 被丢弃，直接 torch.cat 都不安全。沿 D 拼接会改变模型契约，并不表示“增加输入槽”。

何时改用 FusionPulse

在一个 Pulse 前拼接兼容原始片段，与融合多个已经形成的 Pulse 工作区，是两种不同操作。ARTI 在 1.6.0 为后一种情况引入 Alpha FusionPulse，并在 1.7.0 中继续提供：

兼容原始片段 → 单个 Pulse → [B,K,D]
多个紧凑 Pulse 工作区 → FusionPulse → 单个 [B,K,D]

整页、区域与细节证据可以先使用各自的 Pulse 容量，再进入联合生存与融合。来源数及各来源槽位数可随调用变化，而 FusionPulse 的下游 K 保持固定。

UnFold：暴露可学习布局

UnFold 查询新值，并把它们与每个原输入实例共同排入输出。自 1.6.0 起，target_length 让一个最大容量服务不同调用级长度。它对原输入实例保值，但不是 Fold 的逆，也不能恢复已经丢失的信息。

稳定性与部署

Half、Fold、Pulse 与 UnFold 是 ARTI 1.7.0 的受支持 1.x API。
FusionPulse 在 1.7.0 中属于 Alpha；tensor 契约已有文档，但结构损失默认值仍在演进。
空输入序列和不兼容 shape 会报错；Fold(k) 始终要求 k > 0。
随机初始化输出没有任务语义，必须训练所在模型或加载任务权重。
ARTI Web 导出目前接受 soft Fold 路径；attention Fold 不是可移植 Web 导出承诺。