@@ -56,12 +56,14 @@ experience, all using NumPy syntax. For example, say we have some CuPy array
5656write 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
6263be 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
166168To 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
175195Backward Compatibility
176196----------------------
0 commit comments