dpnp.fromfunction¶

dpnp.fromfunction(function, shape, *, dtype=<class 'float'>, like=None, device=None, usm_type='device', sycl_queue=None, **kwargs)[source]¶

Construct an array by executing a function over each coordinate.

The function is called once with one coordinate array for each dimension of shape instead of once per coordinate.

For functions that operate elementwise on array arguments, the resulting array has a value fn(x, y, z) at coordinate (x, y, z).

For full documentation refer to numpy.fromfunction.

Parameters:

functioncallable

The function is called once with N coordinate arrays as parameters, where N is the length of shape. Each array represents the coordinates along a specific axis. For example, if shape were (2, 2), then the parameters would be array([[0, 0], [1, 1]]) and array([[0, 1], [0, 1]]).

shape(N,) tuple of ints

Shape of the coordinate arrays passed to function. The shape of the output is determined by the value returned by function and may be different from shape.

dtype{None, str, dtype object}, optional

Data-type of the coordinate arrays passed to function. If None, uses a default floating point data type for the device on which the returned array is allocated.

Default: float.

device{None, string, SyclDevice, SyclQueue, Device}, optional

An array API concept of device where the output array is created. device can be None, a oneAPI filter selector string, an instance of dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a dpnp.tensor.Device object returned by dpnp.ndarray.device.

Default: None.

usm_type{None, "device", "shared", "host"}, optional

The type of SYCL USM allocation for the output array.

Default: "device".

sycl_queue{None, SyclQueue}, optional

A SYCL queue to use for output array allocation and copying. The sycl_queue can be passed as None (the default), which means to get the SYCL queue from device keyword if present or to use a default queue.

Default: None.

Returns:

outdpnp.ndarray: The result of the call to function is passed back directly. Therefore the shape of fromfunction is completely determined by function.

Limitations

Parameter like is supported only with default value None. Otherwise, the function raises NotImplementedError exception.

See also

dpnp.indices: Return an array representing the indices of a grid.
dpnp.meshgrid: Return coordinate matrices from coordinate vectors.

Notes

This uses numpy.fromfunction and coerces the result to a DPNP array. Keywords other than dtype and like are passed to function.

Warning

shape determines the shape of the coordinate arrays passed to function. It does not enforce that the function returns a result with that shape. If function returns a scalar, the result is a zero-dimensional array rather than an array with the given shape.

Examples

>>> import dpnp as np
>>> np.fromfunction(lambda i, j: i, (2, 2), dtype=float)
array([[0., 0.],
       [1., 1.]])

>>> np.fromfunction(lambda i, j: j, (2, 2), dtype=float)
array([[0., 1.],
       [0., 1.]])

>>> np.fromfunction(lambda i, j: i == j, (3, 3), dtype=int)
array([[ True, False, False],
       [False,  True, False],
       [False, False,  True]])

>>> np.fromfunction(lambda i, j: i + j, (3, 3), dtype=int)
array([[0, 1, 2],
       [1, 2, 3],
       [2, 3, 4]])

Creating an array on a different device or with a specified usm_type

>>> x = np.fromfunction(lambda i, j: i - j, (3, 3)) # default case
>>> x.device, x.usm_type
(Device(level_zero:gpu:0), 'device')

>>> y = np.fromfunction(lambda i, j: i - j, (3, 3), device='cpu')
>>> y.device, y.usm_type
(Device(opencl:cpu:0), 'device')

>>> z = np.fromfunction(lambda i, j: i - j, (3, 3), usm_type="host")
>>> z.device, z.usm_type
(Device(level_zero:gpu:0), 'host')