scipp.broadcast

scipp.broadcast(x, *, dims=None, shape=None, sizes=None)

Broadcast a Variable or a DataArray.

If the input is a DataArray, coordinates and attributes are shallow-copied and masks are deep-copied.

Note that Scipp operations broadcast automatically, so using this function directly is rarely required.

One and only one of these sets of arguments must be given:

• dims and shape

• sizes

Parameters:

• x (scipp.typing.VariableLike) – Input data to broadcast.

• dims (Sequence[str] | None, default: None) – List of new dimensions.

• shape (Sequence[int] | None, default: None) – New extents in each dimension.

• sizes (dict[str, int] | None, default: None) – New dimension labels to sizes map.

Returns:

Same type as input – New Variable or DataArray with requested dimension labels and shape.

Examples

Broadcast a scalar to an array:

>>> import scipp as sc
>>> x = sc.scalar(5, unit='m')
>>> sc.broadcast(x, sizes={'x': 3})
<scipp.Variable> (x: 3)      int64              [m]  [5, 5, 5]

Broadcast a 1-D array to 2-D:

>>> x = sc.array(dims=['x'], values=[1, 2, 3], unit='m')
>>> result = sc.broadcast(x, sizes={'x': 3, 'y': 2})
>>> result
<scipp.Variable> (x: 3, y: 2)      int64              [m]  [1, 1, ..., 3, 3]
>>> result.values
array([[1, 1],
       [2, 2],
       [3, 3]])

Using dims and shape instead of sizes:

>>> sc.broadcast(x, dims=['x', 'y'], shape=[3, 2])
<scipp.Variable> (x: 3, y: 2)      int64              [m]  [1, 1, ..., 3, 3]

Broadcasting fails if the target size conflicts with an existing dimension:

>>> x = sc.array(dims=['x'], values=[1, 2, 3])
>>> sc.broadcast(x, sizes={'x': 5})
Traceback (most recent call last):
    ...
scipp.core.DimensionError: Cannot broadcast existing dimension 'x' ...