`scipy.special._ufunc_tools:_with_cache_optimization`

source: /scipy/special/_ufunc_tools.py:15

Signature

def _with_cache_optimization(*, name, arg_names, docstring, ufunc, cache_arg_indices)

Summary

Helper to ensure optimal iteration order for ufuncs that use caching.

Extended Summary

This concerns internal caches which are only live over the course of one call to a ufunc to avoid repeated computations during the course of the loops. See the notes below for more information.

Parameters

name : str
arg_names : list[str]: The function name and arg names are passed in so that the wrapper can be generated with the create name and argument names, improving documentation and autocomplete.
docstring : str
ufunc : numpy.ufunc
cache_arg_indices : list[int]: Arguments to ufunc which are used in the kernel to compute an output which is being cached for reuse when iterating over other arguments.

Returns

: callable: A wrapper for ufunc which transposes the axes of the inputs to ensure iteration precedes in such a way to allow the cache within the ufunc kernel to eliminate redundant computation.

Notes

There is a common pattern in ufunc kernels exemplified by the situation where some of the arguments are used to compute coeffients of an expansion that is taken over one or more of the other arguments. A classic example is Mathieu functions, which compute coefficients corresponding to the shape parameter q and order m which in principle could be reused for varying values of the parameter x.

It had long been the case that the expensive computation of coefficients is repeated unnecessarily across values of x. It is possible to add a cache to the ufunc kernel which stores the expansion coefficients and only updates if the pointers into the q and m arrays advance during the course of the ufunc loops. Such a cache is instantiated each time a ufunc is called and only lives during the course of the loops that are carried out for that particular call.

Whether such a cache actually helps depends on the order in which iteration occurs. Ideally, one would want q and m to advance most slowly and for the iterations over x for fixed q and m to be pushed to the inner most loops. This helper replaces each input array (and a pre-allocated output array) with a view where the axes which should vary most slowly are transposed to the ends and forces computation in C order. This ensures iteration proceeds in the optimal order.

Note that because the pre-allocated output array used internally is C contiguous, the output will be C contiguous regardless of contiguity of the inputs.

Aliases

scipy.special._spfun_stats._with_cache_optimization