feat: add broadcast_shapes to the specification
#983
Conversation
kgryte
added
API extension
| - 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. |
There was a problem hiding this comment.
This can be phrased such that it works for computation graphs in the expected manner I believe, since the broadcasting math is abstract anyway and any sentinels can propagate correctly. To be discussed in the next call I think.
There was a problem hiding this comment.
I've updated the copy to now be normative with regard to sentinel propagation.
There was a problem hiding this comment.
There is the question regarding what happens when two shapes use different sentinels, but we can likely resolve this ambiguity in a future PR when someone asks for explicit clarification.
|
the array-api-extra docs just say |
ev-br
left a comment
ev-br
left a comment
There was a problem hiding this comment.
One small suggestion about the unknown dimensions, LGTM otherwise.
| ----- | ||
|
|
||
| - If not provided one or more arguments, the function **must** return an empty tuple. | ||
| - An array-conforming library **may** accept a non-integer value (e.g., ``None``) for one or more dimensions. This is common for array libraries which build computation graphs (e.g., ndonnx and Dask) and which need to provide a mechanism for indicating dimensions of unknown size. Array-conforming libraries which accept non-integer values for dimensions of unknown size **must** propagate such values (e.g., if a shape contains a dimension size of ``None``, the returned broadcasted shape **must** also have a corresponding dimension having a size equal to ``None``); otherwise, an array-conforming library **must** raise a ``ValueError``. |
There was a problem hiding this comment.
Is this deliberately less strict than https://data-apis.org/array-api/draft/API_specification/generated/array_api.array.shape.html#shape, which seems to imply that None is the only acceptable non-integer value in a shape (at least where that value is supposed to represent an unknown dimension)?
E.g. this appears to be accommodating Dask's math.nan, suggesting that it should propagate that math.nan? That would differ from the existing behaviour in https://data-apis.org/array-api-extra/generated/array_api_extra.broadcast_shapes.html which replaces that non-standard math.nan with a None.
| - An array-conforming library **may** accept a non-integer value (e.g., ``None``) for one or more dimensions. This is common for array libraries which build computation graphs (e.g., ndonnx and Dask) and which need to provide a mechanism for indicating dimensions of unknown size. Array-conforming libraries which accept non-integer values for dimensions of unknown size **must** propagate such values (e.g., if a shape contains a dimension size of ``None``, the returned broadcasted shape **must** also have a corresponding dimension having a size equal to ``None``); otherwise, an array-conforming library **must** raise a ``ValueError``. | |
| - An array-conforming library **may** accept a ``None`` value for one or more shape dimensions. This is common for array libraries which build computation graphs (e.g., ndonnx and Dask) and which need to provide a mechanism for indicating dimensions of unknown size. Array-conforming libraries which accept ``None`` values for dimensions of unknown size **must** propagate those values (i.e., if a shape contains a dimension size of ``None``, the returned broadcasted shape **must** also have a corresponding dimension having a size equal to ``None``); otherwise, an array-conforming library **must** raise a ``ValueError``. |
4 participants
This PR
broadcast_shapesto the specification #893 by adding support forbroadcast_shapesto the specification.Nonefor a dimension of unknown size, behavior is left unspecified and thus implementation-defined.