diff --git a/spec/draft/API_specification/manipulation_functions.rst b/spec/draft/API_specification/manipulation_functions.rst index 395c1c3e2..57cff6e62 100644 --- a/spec/draft/API_specification/manipulation_functions.rst +++ b/spec/draft/API_specification/manipulation_functions.rst @@ -19,6 +19,7 @@ Objects in API :template: method.rst broadcast_arrays + broadcast_shapes broadcast_to concat expand_dims diff --git a/src/array_api_stubs/_draft/manipulation_functions.py b/src/array_api_stubs/_draft/manipulation_functions.py index 6d977d870..d6ff0adbd 100644 --- a/src/array_api_stubs/_draft/manipulation_functions.py +++ b/src/array_api_stubs/_draft/manipulation_functions.py @@ -1,5 +1,6 @@ __all__ = [ "broadcast_arrays", + "broadcast_shapes", "broadcast_to", "concat", "expand_dims", @@ -35,6 +36,35 @@ def broadcast_arrays(*arrays: array) -> List[array]: """ +def broadcast_shapes(*shapes: Tuple[int, ...]) -> Tuple[int, ...]: + """ + Broadcasts one or more shapes against one another. + + Parameters + ---------- + shapes: Tuple[int, ...] + an arbitrary number of to-be broadcasted shapes. + + Returns + ------- + out: Tuple[int, ...] + a broadcasted shape. + + Raises + ------ + ValueError + If provided shapes which are not broadcast compatible (see :ref:`broadcasting`), a ``ValueError`` **should** be raised. + + Notes + ----- + + - If not provided one or more arguments, the function **must** return an empty tuple. + + .. note:: + Array libraries which build computation graphs (e.g., ndonnx and Dask) commonly support shapes having dimensions of unknown size. If a shape contains a value other than an integer (e.g., ``None`` for a dimension of unknown size), behavior is unspecified and thus implementation-defined. Array-conforming libraries **may** choose to propagate such values (e.g., if a shape contains a dimension size of ``None``, the returned broadcasted shape also has a corresponding dimension having a size equal to ``None``) or raise an exception. + """ + + def broadcast_to(x: array, /, shape: Tuple[int, ...]) -> array: """ Broadcasts an array to a specified shape.