doc/neps/nep-0043-extensible-ufuncs.rst

42 This NEP proposes to expand the design of ufuncs.
73   DTypes.  This is often called the "inner-loop".
122    the NumPy ufunc struct directly for its own purposes.
136 * Existing inner-loops can be wrapped, adding an indirection to the call but
139   inner-loop functions (which are stored on the ufunc directly) in order
240         def resolve_descriptors(context, given_descrs):
247             assert isinstance(given_descrs[0], context.DTypes[0])
248             assert isinstance(given_descrs[1], context.DTypes[1])
251             return (given_descrs[0], given_descrs[1], context.DTypes[2]()), "safe"
253         def strided_loop(context, dimensions, data, strides, innerloop_data):
259             num_chars1 = context.descriptors[0].itemsize
260             num_chars2 = context.descriptors[1].itemsize
274 We use ``BoundArrayMethod`` and a ``context`` structure here.  These
277 * ``context`` is a generalization of the ``self`` that Python passes to its
361    * Find the C-implemented, light weight, inner-loop function.
362      Finding the inner-loop function can allow specialized implementations
366      inside the inner-loop function itself.
367    * Signal whether the inner-loop requires the Python API or whether
373    * Run the DType specific inner-loop function.
374    * The inner-loop may require access to additional data, such as dtypes or
376    * The inner-loop function may be called an undefined number of times.
386 customize the behaviour in steps 4 or 6, aside from the inner-loop function.
388 are step 3 and step 5 to provide the custom inner-loop function.
427                 Context: context, Tuple[DType]: given_descrs)-> Casting, Tuple[DType]:
435         def get_loop(Context : context, strides, ...) -> strided_loop_function, flags:
436             """Returns the low-level C (strided inner-loop) function which
440             a set of optimized inner-loop functions instead:
451                 Context : context, data, dimensions, strides, innerloop_data):
452             """The inner-loop (equivalent to the current ufunc loop)
473         # The actual dtypes instances the inner-loop operates on:
484 * the inner-loop function requires the Python API (GIL)
493 The "context" object is analogous to Python's ``self`` that is
495 To understand why the "context" object is necessary and its
551   and later pass on that information to the inner-loop function.
580 in the future, for example to allow specialized inner-loops.
582 Briefly, NumPy currently relies on strided inner-loops and this
590 * A new structure to be passed to the resolve function and inner-loop::
592         typedef struct {
619               PyArrayMethod_Context *context,
626   byteorder when needed by the inner-loop.
632   the existing ``NpyAuxData *`` struct::
634         struct {
641   This struct is currently mainly used for the NumPy internal casting
659             PyArrayMethod_Context *context,
670 * The inner-loop function::
672     int inner_loop(PyArrayMethod_Context *context, ..., void *innerloop_data);
674   Will have the identical signature to current inner-loops with the following
694     typedef struct {
767 Further, we could expand ``get_loop`` and allow the ``ArrayMethod`` implementer
768 to also control the outer iteration and not only the 1-D inner-loop.
771 Extending the inner-loop signature
774 Extending the inner-loop signature is another central and necessary part of
780 the signature by adding new fields to the context struct.
782 the inner-loop operates on.
790 In this NEP we propose passing the struct to simplify creation of loops for
820 We expect that future inner-loops will generally set Python errors as soon
821 as an error is found. This is complicated when the inner-loop is run without
826     inner_loop(PyArrayMethod_Context *context, ..., void *innerloop_data)
845 state which is too expensive if done within the inner-loop function itself.
875     integer_multiply(PyArrayMethod_Context *context, ..., npy_intp *innerloop_data)
899 the ``context`` in principle.
915 an existing ``ArrayMethod`` as directly as possible, so that its inner-loop function
973 fetch and reuse the inner-loop function from another ``ArrayMethod``.
1160 acceptable in the specific context.  This would require additional hooks
1295 `the github issue 12518 "What should be the calling convention for ufunc inner loop signatures?" <h…