UnFold

arti.nn.UnFold is a supported 1.x core layer in ARTI 1.7.0. It queries new values from a compact input, combines them with every original input instance, and learns a sample-conditioned 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)

Dynamic target length

exposed is maximum trainable expansion capacity. target_length lets one layer activate only the parameter prefix required by the current call:

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)

For input length N, the active queried count is target_length - N and must be in 1..exposed. This is a call-level output shape, not a different physical shape for each sample in one batch. Omitting target_length preserves [B, N + exposed, D].

What “value-preserving” means

Every original input instance is transported by a hard gather and appears exactly once in the output. It is not averaged, interpolated, projected, or discarded. Its position and adjacency may change. Queried values are learned transformations and do not carry the same preservation guarantee.

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

source_index < N identifies an original instance; indices at or above N identify queried values. The mapping is sample-conditioned.

Masks, guide, and canonical layout

Input masks travel through the same hard layout. guide can influence layout without changing the values being transported. layout_mode="canonical" accepts a one-dimensional ordering guide; optional exposed_guide fully specifies queried coordinates.

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

exposed_mask controls per-sample validity for active queried candidates, but does not change the tensor shape of a call.

Boundaries

• UnFold is unrelated to torch.nn.Unfold.
• It is not the mathematical inverse of Fold and cannot reconstruct information already discarded.
• Dynamic length is bounded by the configured exposed capacity.
• Dense greedy and auction research backends have separate limits; the default sort backend uses argsort and gather.
• The documented CUDA fused path has measured dtype, dimension, and workspace gates; other configurations fall back to PyTorch.

Try these constraints interactively in the Workspace Fusion Lab.