scipy.signal.choose_conv_method

scipy.signal.choose_conv_method(in1, in2, mode='full', measure=False)

Find the fastest convolution/correlation method.

This primarily exists to be called during the method='auto' option in convolve and correlate, but can also be used when performing many convolutions of the same input shapes and dtypes, determining which method to use for all of them, either to avoid the overhead of the ‘auto’ option or to use accurate real-world measurements.

Parameters:

in1 : array_like

The first argument passed into the convolution function.

in2 : array_like

The second argument passed into the convolution function.

mode : str {‘full’, ‘valid’, ‘same’}, optional

A string indicating the size of the output:

full

The output is the full discrete linear convolution of the inputs. (Default)

valid

The output consists only of those elements that do not rely on the zero-padding.

same

The output is the same size as in1, centered with respect to the ‘full’ output.

measure : bool, optional

If True, run and time the convolution of in1 and in2 with both methods and return the fastest. If False (default), predict the fastest method using precomputed values.

Returns:

method : str

A string indicating which convolution method is fastest, either ‘direct’ or ‘fft’

times : dict, optional

A dictionary containing the times (in seconds) needed for each method. This value is only returned if measure=True.

See also

convolve, correlate

Notes

For large n, measure=False is accurate and can quickly determine the fastest method to perform the convolution. However, this is not as accurate for small n (when any dimension in the input or output is small).

In practice, we found that this function estimates the faster method up to a multiplicative factor of 5 (i.e., the estimated method is at most 5 times slower than the fastest method). The estimation values were tuned on an early 2015 MacBook Pro with 8GB RAM but we found that the prediction held fairly accurately across different machines.

If measure=True, time the convolutions. Because this function uses fftconvolve, an error will be thrown if it does not support the inputs. There are cases when fftconvolve supports the inputs but this function returns direct (e.g., to protect against floating point integer precision).

New in version 0.19.

Examples

Estimate the fastest method for a given input:

>>> from scipy import signal
>>> a = np.random.randn(1000)
>>> b = np.random.randn(1000000)
>>> method = signal.choose_conv_method(a, b, mode='same')
>>> method
'fft'

This can then be applied to other arrays of the same dtype and shape:

>>> c = np.random.randn(1000)
>>> d = np.random.randn(1000000)
>>> # `method` works with correlate and convolve
>>> corr1 = signal.correlate(a, b, mode='same', method=method)
>>> corr2 = signal.correlate(c, d, mode='same', method=method)
>>> conv1 = signal.convolve(a, b, mode='same', method=method)
>>> conv2 = signal.convolve(c, d, mode='same', method=method)