Should meshgrid return a list or a tuple of coordinate arrays?

[ev-br]

The spec stipulates that meshgrid returns a list of arrays, https://data-apis.org/array-api/draft/API_specification/generated/array_api.meshgrid.html

NumPy and Pytorch, however, return tuples. Jax and CuPy return lists. Makes me wonder if specifying a list is a conscious decision: I seem to recall that tuples are generally more JIT-friendly.

[kgryte]

@ev-br The spec likely reflects pre-NumPy v2.0. See https://numpy.org/doc/1.26/reference/generated/numpy.meshgrid.html and https://github.com/numpy/numpy/blob/v1.26.0/numpy/lib/function_base.py#L5163.

[ev-br]

So it might be worth revisiting this in the spec then.

[ev-br]

Assuming that List[array] is the correct annotation for functions which return lists of arrays, the only functions which return a list of arrays are meshgrid and broadcast_arrays, cf https://github.com/data-apis/array-api/issues/934.

Two other instances in the search below are stack and concat which accept sequences.

The current spec requirement, List[arrays], comes from NumPy 1.x. Given that NumPy 2.x deliberately changed return type to tuple[arrays], it seems reasonable to change the spec for 2025.12, too. Alternatively, allow a union of a list and a tuple, with a recommendation along the lines of should return a tuple but may return a list.

$ git grep -n "List\[arr" src/array_api_stubs/_draft/
src/array_api_stubs/_draft/creation_functions.py:454:def meshgrid(*arrays: array, indexing: Literal["xy", "ij"] = "xy") -> List[array]:
src/array_api_stubs/_draft/creation_functions.py:467:    out: List[array]
src/array_api_stubs/_draft/manipulation_functions.py:22:def broadcast_arrays(*arrays: array) -> List[array]:
src/array_api_stubs/_draft/manipulation_functions.py:33:    out: List[array]
src/array_api_stubs/_draft/manipulation_functions.py:60:    arrays: Union[Tuple[array, ...], List[array]], /, *, axis: Optional[int] = 0
src/array_api_stubs/_draft/manipulation_functions.py:67:    arrays: Union[Tuple[array, ...], List[array]]
src/array_api_stubs/_draft/manipulation_functions.py:302:def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) -> array:
src/array_api_stubs/_draft/manipulation_functions.py:308:    arrays: Union[Tuple[array, ...], List[array]]

[ev-br]

@jakevdp while not exactly the master list , the functions which return List[array] in the Array API spec but have been changed in NumPy 2.0 to return tuples are meshgrid and broadcast_arrays, https://github.com/data-apis/array-api/issues/938#issuecomment-2995923732

[kgryte]

Currently, in the specification, the list is as follows:

• meshgrid
• broadcast_arrays
• info.devices

In the following APIs, we return tuples:

• unique_all
• unique_counts
• unique_inverse
• nonzero
• unstack
• linalg.svg
• linalg.slogdet
• linalg.qr
• linalg.eigh
• array.shape
• array.dlpack_device

[kgryte]

I've opened https://github.com/data-apis/array-api/pull/981.