utilities.arrays.broadcast_labels

utilities.arrays.broadcast_labels(*inputs)

Broadcast shapes and propagate semantic axis labels, with singleton suppression.

Each input is a tuple (shape, labels):

• shape is a standard tuple of integers.

• labels is a sequence of axis names or None. If None, the shape is treated as unlabeled.

Axis labels are propagated to the output broadcast shape only if:

• They come from a dimension with size > 1 (i.e., not a singleton),

• And there are no conflicting labels on that axis from other inputs.

If multiple non-singleton labeled inputs contribute different labels to the same axis, a ValueError is raised. Labels from singleton dimensions are ignored unless no dominant label exists.

Parameters:

*inputs (Tuple[(shape, labels)]) – Input shapes and optional axis labels. Each shape must match the length of its label list if labels are provided.

Returns:

• broadcast_shape (Tuple[int, ]) – The final broadcasted shape.

• broadcast_labels (Tuple[Optional[str], ]) – The labels associated with each axis in the broadcasted shape. May contain None.

Raises:

ValueError – If label lengths don’t match their shapes, or if conflicting non-singleton labels exist for a broadcasted axis.

Examples

>>> broadcast_labels(((1, 5, 4), ['r', 'phi', 'z']), ((10, 5, 4), [None, 'phi', 'z']))
((10, 5, 4), (None, 'phi', 'z'))

>>> broadcast_labels(((3, 4), ['x', 'y']), ((1, 4), ['z', 'y']))
ValueError: conflicting non-singleton labels on axis 0