This PR

• adds specifications for array manipulation functions.
• is derived from comparing API signatures across array libraries.

Notes

• This list of array manipulation functions is an initial set of array manipulation functions which can pave the way for additional specs in subsequent pull requests. These functions were identified as the set of functions with the broadest support among array libraries and relatively higher usage among downstream libraries.

• Some comments/questions regarding particular APIs...

  • concat: CuPy requires a tuple rather than a sequence for first argument. Went with tuple as more consistent with rest of specification (e.g., we require a list of axes to be specified as a tuple, but not a sequence). What happens if provided arrays having different dtypes? What should we the dtype of the returned array? How do type promotion rules factor in here?

    • Answer: regular type promotion rules. Between data type families, behavior is left unspecified.

  • expand_dims: NumPy supports providing a tuple or an int. All other array libraries considered support only an int. Torch names this method unsqueeze. Went with expand_dims and only accepting an int for the second positional argument.

  • flip: TensorFlow lacks this exact API. Torch/CuPy/ spec axis/dims as position argument. Based proposal on NumPy where axis is a keyword argument, as more versatile.

  • reshape: Torch requires a tuple (does not allow int). TensorFlow requires shape to be a int32/int64 tensor. NumPy allows providing an int as shorthand. Based proposal on Torch's more restricted API for consistency.

  • roll: TensorFlow requires tensors for axis and shifts.

  • squeeze: Torch only allows specifying one axis and does not error if you attempt to squeeze non-singleton dimensions. NumPy/TensorFlow error if you attempt to squeeze a dimension which is not 1. Sided with Torch regarding error behavior, as not clear why attempting to squeeze a non-singleton dimension should error.

  • stack: CuPy requires a tuple rather than a sequence for the first argument. Went with tuple for same reasons as in concat. Same dtype question(s) apply as for concat above.