canvas_engineering.masks¶
Attention mask specifications and utilities. Attach a MaskSpec to a
ConnectionProgram.mask_spec to control the sparsity pattern of
attention between two regions. The dispatcher pre-computes
mask_to_index_pairs(...) at construction time and iterates the
resulting (src_idx, dst_idx) pairs in its dense branch.
canvas_engineering.masks.MaskSpec
dataclass
¶
Attention mask specification for a connection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kind
|
str
|
Mask type. "full" = dense attention (default). "tile" = tile-based block-sparse attention. "sparse" = greedy rectangle covering of an explicit binary mask. |
'full'
|
tile_h
|
int
|
For kind="tile", tile height (2D compat). |
1
|
tile_w
|
int
|
For kind="tile", tile width (2D compat). |
1
|
tile_shape
|
Optional[Tuple[int, ...]]
|
For kind="tile", N-D tile shape. Mutually exclusive with tile_h/tile_w. |
None
|
canvas_engineering.masks.Rect
¶
Axis-aligned hyperrectangle in N-dimensional space.
ranges is a tuple of (lo, hi) pairs, one per dimension. For (T, H, W): ranges = ((t0, t1), (h0, h1), (w0, w1)).
Supports backward-compat construction: Rect(t0, t1, h0, h1, w0, w1).
volume
property
¶
Number of positions covered.
canvas_engineering.masks.rect_cover(mask, min_area=4)
¶
Greedy hyperrectangle covering of an N-D boolean mask.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mask
|
Tensor
|
N-dimensional boolean tensor (e.g. (T, H, W) or (T, X)). |
required |
min_area
|
int
|
Minimum volume for a rectangle. |
4
|
Returns:
| Type | Description |
|---|---|
List[Rect]
|
List of Rect objects covering all True positions in mask. |
canvas_engineering.masks.mask_to_index_pairs(mask_spec, layout, src, dst)
¶
Convert a MaskSpec to pairs of (src_indices, dst_indices) for dispatch.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mask_spec
|
MaskSpec
|
The mask specification. |
required |
layout
|
CanvasLayout
|
Canvas layout with region definitions. |
required |
src
|
str
|
Source region name. |
required |
dst
|
str
|
Destination region name. |
required |
Returns:
| Type | Description |
|---|---|
List[Tuple[List[int], List[int]]]
|
List of (src_indices, dst_indices) pairs. Each pair represents |
List[Tuple[List[int], List[int]]]
|
a group of src positions that should attend to a group of dst |
List[Tuple[List[int], List[int]]]
|
positions. For "full" mode, returns a single pair with all indices. |