---

name: named-einsum-and-packing description: "Use einops.einsum, pack, and unpack for named-axis contractions and reversible heterogeneous tensor packing." disable-model-invocation: true metadata: disco-role: operating license: MIT

Named Einsum And Packing

Use this sub-skill when the task needs named-axis tensor contractions or reversible packing of tensors with heterogeneous middle structure. It covers einops.einsum, einops.pack, and einops.unpack as public runtime APIs.

Load When

• Translating NumPy/backend einsum formulas into readable named-axis patterns.
• Computing attention scores, dot products, linear projections, traces, diagonal reductions, or ellipsis-aware contractions.
• Packing class tokens, image tokens, text tokens, or other modalities into one sequence-like tensor and unpacking the processed result.
• Carrying packed-shape bookkeeping (PS) through transformer/model flows.
• Splitting one prediction tensor into multiple logical outputs with manual packed_shapes.
• Debugging failures involving ->, tensors-first call order, unsupported grouped einsum axes, invalid * packing patterns, bad packed_shapes, or -1 inference.

Route Elsewhere

• Ordinary reshape, transpose, split, stack, reduce, repeat, pooling, or dimension parsing recipes belong to sibling sub-skill tensor-operations.
• Framework layer abstractions such as EinMix and einops.layers.* belong to sibling sub-skill framework-integrations.
• Repository development commands, native test selection, packaging, docs builds, or source maintenance belong to sibling sub-skill repo-development.

Public APIs

from einops import einsum, pack, unpack

• einsum(*tensors_and_pattern) takes one or more tensors first and the pattern string last. This is the reverse of numpy.einsum(pattern, *tensors).
• pack(tensors, pattern) returns (packed_tensor, packed_shapes).
• unpack(tensor, packed_shapes, pattern) returns a list of tensors.

See references/api-reference.md for signatures, parameters, return contracts, limitations, and error behavior.

Golden Rules

1. Always call einsum as einsum(tensor1, tensor2, ..., "axes -> axes"). A non-string last argument is a call-order bug.
2. Always include an explicit -> in einsum; implicit-output NumPy-style shorthand is intentionally rejected.
3. Use semantic multi-letter axis names such as batch, query, head, and channel. Internally they are compacted to backend single-letter einsum symbols, but user code should stay named and readable.
4. einsum supports ellipsis and repeated axes on an input term for diagonal or trace-style operations. It does not support grouped axes like (h w), singleton (), or anonymous numeric axes like 2.
5. Use pack/unpack, not manual concatenate/slice/reshape, when tensors have heterogeneous axes in the packed position or when the inverse split must be carried safely through later code.
6. A packing pattern is not an arrow expression. It is a space-separated list of axes with exactly one literal *, for example "batch * channel".
7. Keep packed_shapes (PS) next to the packed tensor. Treat it as part of the data contract, especially across model calls that change only non-packed axes such as channel -> channel_out.
8. In manual unpack, use at most one -1 across the entire packed_shapes argument, and validate round trips when shapes are computed dynamically.
9. Zero-length packed items are valid and should usually be preserved through PS instead of special-cased away.

Pattern Quick Reference

Named einsum

scores = einsum(
    queries, keys,
    "batch query head channel, batch key head channel -> batch head query key",
)

• Axes absent from the right side are summed over.
• Axes repeated within one input term select diagonals before summation.
• Ellipsis (...) carries arbitrary leading, middle, or trailing dimensions.

Packing and unpacking

packed, ps = pack([class_token_bc, image_tokens_bhwc, text_tokens_btc], "batch * channel")
class_out, image_out, text_out = unpack(processed_packed, ps, "batch * channel_out")

• Axes before * match leading axes of every input.
• Axes after * match trailing axes of every input.
• Every remaining input axis is flattened into the packed axis, concatenated, and recorded in the corresponding PS entry.
• PS entries are shapes that replace * during unpack; () means the item contributed one element with no explicit packed axes.

Workflow References

Use references/workflows.md for these recipes:

• Convert backend/NumPy attention or dot-product formulas to named einsum.
• Catch unsupported grouped-axis einsum and repair it with a separate reshape step owned by tensor-operations.
• Pack class tokens and patch tokens for ViT-like flows.
• Pack multimodal token streams, including zero-length modalities.
• Split multi-output prediction tensors with manual packed_shapes.
• Auto-batch single examples and batches with pack([x], "* ...") style flows.
• Validate reversible pack/unpack round trips and PS bookkeeping.

Use references/troubleshooting.md for the failure matrix and fixes for common error fragments.

Bundled Smoke Scripts

The scripts are deterministic, NumPy-only checks derived from public behavior covered by the repository tests and examples. They do not import repo tests or require a source checkout.

• scripts/einsum_smoke.py checks named einsum, attention, ellipsis, traces, and expected unsupported-syntax errors.
• scripts/packing_smoke.py checks trivial packing, heterogeneous round trips, class-token and multimodal flows, multi-output unpacking, auto-batching, zero-length cases, and expected packing errors.

Run from the sub-skill directory or pass the script path explicitly:

python scripts/einsum_smoke.py --help
python scripts/einsum_smoke.py
python scripts/packing_smoke.py --help
python scripts/packing_smoke.py

Recovery Checklist

When a user reports a broken named-axis contraction or packing flow:

1. Identify whether the operation is a contraction (einsum) or reversible shape bookkeeping (pack/unpack). Do not solve a packing problem with a lossy manual slice unless reversibility is irrelevant.
2. Check API call order first: tensors before pattern for einsum; sequence of tensors before pattern for pack; packed tensor, PS, then pattern for unpack.
3. Validate pattern family: arrow pattern for einsum, one-star no-arrow pattern for pack/unpack.
4. For einsum, remove unsupported groups, singletons, and anonymous axes by doing explicit reshapes or singleton insertion outside einsum.
5. For pack/unpack, inspect the PS entries and the product they imply for the packed axis; then run a minimal round-trip assertion.
6. Reproduce with the bundled smoke script case nearest to the failure, then adapt its small deterministic arrays to the user's shapes.