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 #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]]