Missing description of `out` keyword for accumulation functions

[antonwolfy]

There is no description of out keyword for accumulation functions and so the expected behavior might not be clear.
In Python array API spec there is no such keyword.

The code below shows different behavior between dpctl and numpy in case when dtype of out array mismatches type x array or default integer type (while numpy supports type casting for out array if necessary):

import numpy, dpctl, dpctl.tensor as dpt

a = dpt.ones(10, dtype='i4')
out = dpt.ones_like(a, dtype='c8')
dpt.cumulative_sum(a, out=out) # expected default integer type != a.dtype
---------------------------------------------------------------------------
ValueError Traceback (most recent call last)
Cell In[7], line 1
----> 1 dpt.cumulative_sum(a, out=out).dtype

File ~/miniconda3/envs/dpnp_dev/lib/python3.9/site-packages/dpctl/tensor/_accumulation.py:281, in cumulative_sum(x, axis, dtype, include_initial, out)
 220 def cumulative_sum(
 221 x, /, *, axis=None, dtype=None, include_initial=False, out=None
 222 ):
 223 """
 224 cumulative_sum(x, /, *, axis=None, dtype=None, include_initial=False,
 225 out=None)
 (...)
 279 along.
 280 """
--> 281 return _accumulate_common(
 282 x,
 283 axis,
 284 dtype,
 285 include_initial,
 286 out,
 287 tai._cumsum_over_axis,
 288 tai._cumsum_final_axis_include_initial,
 289 tai._cumsum_dtype_supported,
 290 _default_accumulation_dtype,
 291 )

File ~/miniconda3/envs/dpnp_dev/lib/python3.9/site-packages/dpctl/tensor/_accumulation.py:108, in _accumulate_common(x, axis, dtype, include_initial, out, _accumulate_fn, _accumulate_include_initial_fn, _dtype_supported, _default_accumulation_type_fn)
 103 raise ValueError(
 104 "The shape of input and output arrays are inconsistent. "
 105 f"Expected output shape is {final_res_sh}, got {out_sh}"
 106 )
 107 if res_dt != out.dtype:
--> 108 raise ValueError(
 109 f"Output array of type {res_dt} is needed, " f"got {out.dtype}"
 110 )
 111 if dpctl.utils.get_execution_queue((q, out.sycl_queue)) is None:
 112 raise ExecutionPlacementError(
 113 "Input and output allocation queues are not compatible"
 114 )

ValueError: Output array of type int64 is needed, got complex64

na = dpt.asnumpy(a)
nout = dpt.asnumpt(out)
numpy.cumsum(a, out=nout).dtype
# Out: dtype('complex64')

Thus the question arises whether dpctl (as opposed to numpy) was intended to have a strict requirement for data type of the out array.

[ndgrigorian]

This behavior itself is intended, for consistency with how we've chosen to implement the out keyword for elementwise functions and matmul.

The lack of documentation is not, it will need to be added.