Skip to content

Commit 57f78df

Browse files
committed
ENH: Clarifies meta_from_array function in NEP-35
1 parent b6f2c16 commit 57f78df

1 file changed

Lines changed: 26 additions & 6 deletions

File tree

‎doc/neps/nep-0035-array-creation-dispatch-with-array-function.rst‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -56,12 +56,14 @@ experience, all using NumPy syntax. For example, say we have some CuPy array
5656
write the following:
5757

5858
.. code:: python
59+
5960
x = cupy.identity(3)
6061
6162
Instead, the better way would be using to only use the NumPy API, this could now
6263
be achieved with:
6364

6465
.. code:: python
66+
6567
x = np.identity(3, like=cp_arr)
6668
6769
As if by magic, ``x`` will also be a CuPy array, as NumPy was capable to infer
@@ -165,12 +167,30 @@ that are not of much use elsewhere.
165167

166168
To enable proper identification of the array type we use Dask's utility function
167169
``meta_from_array``, which was introduced as part of the work to support
168-
``__array_function__``, allowing Dask to handle ``_meta`` appropriately. That
169-
function is primarily targeted at the library's internal usage to ensure chunks
170-
are created with correct types. Without the ``like=`` argument, it would be
171-
impossible to ensure ``my_pad`` creates a padding array with a type matching
172-
that of the input array, which would cause a ``TypeError`` exception to
173-
be raised by CuPy, as discussed above would happen to the CuPy case alone.
170+
``__array_function__``, allowing Dask to handle ``_meta`` appropriately. Readers
171+
can think of ``meta_from_array`` as a special function that just returns the
172+
type of the underlying Dask array, for example:
173+
174+
.. code:: python
175+
176+
np_arr = da.arange(5)
177+
cp_arr = da.from_array(cupy.arange(5))
178+
179+
meta_from_array(np_arr) # Returns a numpy.ndarray
180+
meta_from_array(cp_arr) # Returns a cupy.ndarray
181+
182+
Since the value returned by ``meta_from_array`` is a NumPy-like array, we can
183+
just pass that directly into the ``like=`` argument.
184+
185+
The ``meta_from_array`` function is primarily targeted at the library's internal
186+
usage to ensure chunks are created with correct types. Without the ``like=``
187+
argument, it would be impossible to ensure ``my_pad`` creates a padding array
188+
with a type matching that of the input array, which would cause a ``TypeError``
189+
exception to be raised by CuPy, as discussed above would happen to the CuPy case
190+
alone. Combining Dask's internal handling of meta arrays and the proposed
191+
``like=`` argument, it now becomes possible to handle cases involving creation
192+
of non-NumPy arrays, which is likely the heaviest limitation Dask currently
193+
faces from the ``__array_function__`` protocol.
174194

175195
Backward Compatibility
176196
----------------------

0 commit comments

Comments
 (0)