__array_ufunc__#

caput.mpiarray.MPIArray.__array_ufunc__(ufunc: numpy.ufunc, method: Literal['__call__', 'reduce', 'accumulate'], *inputs: tuple[numpy.typing.NDArray], **kwargs: Any) → MPIArray | tuple[MPIArray, Ellipsis] | None[source]#

Handles ufunc operations for MPIArray.

In NumPy, ufuncs are the various fundamental operations applied to ndarrays in an element-by-element fashion, such as add() and divide(). https://numpy.org/doc/stable/reference/ufuncs.html

ndarray has lots of built-in ufuncs. In order to use them, the MPIArrays need to be converted into ndarrays, otherwise NumPy reports a NotImplemented error.

Not all ufunc methods make sense when operating over distributed inputs. The “__call__”, “reduce”, and “accumulate” types are supported, but the “outer”, “at” and “reduceat” types have more complex behaviour that can’t be easily generalised to a distributed case so they are not supported.

Each of the supported methods has slightly different restrictions:

  • “__call__”: for single array operations there are no restrictions (e.g. np.exp), for binary operations (e.g. A + B) both operands must share broadcast against each other and have the same shape distributed axis, which must be at a position consistent with the broadcasting.

  • “accumulate”: the accumulation axis must not be the distributed axis, otherwise there are no restrictions (e.g. np.cumsum).

  • “reduce”: the reduction cannot take place along the distributed axis (i.e. axis must not include the distributed axis), except for a total reduction over all axes (axis = None) which will return an array with a single element on each rank.

For all of these method types, out keyword arguments, used for directly placing the result in an existing array, are supported. However where arguments, used for selecting which elements to apply the function to, are not.

If the operation that you want to do is not supported then you should use numpy arrays directly to achieve what you want, first using local_array to get the local numpy data, then applying the ufunc, and finally using an wrap() call to construct a distributed array from the output.

Parameters:
ufuncufunc

ufunc object to call

method{“__call__”, “accumulate”, “reduce”}

indicates which ufunc method was called. Only the methods “__call__”, “accumulate” and “reduce” are supported. The other defined methods “outer”, “reduceat” and “at” will cause a ValueError to be thrown.

inputstuple[npt.NDArray]

Sequence of the input arguments to the ufunc. At least one of the inputs is an MPIArray.

**kwargsAny

Optional input arguments of the ufunc. Important kwargs considered here are out and axis.

Returns:
resultMPIArray | tuple[MPIArray, …] | None

Result of the ufunc operation.

Raises:
UnsupportedOperation

  • If the ufunc method is not supported for MPIArrays. Some more complicated methods are not possible without custom implementations.

  • If the where argument is provided.

TypeError

If at least one output is not an MPIArray.

ValueError

If the distribution of at least one output does not match expectation.