planfftw (planfftw)

planfftw provides Julia-inspired function planners for FFT and FFT-based functions. If available, the planned functions use pyfftw as a backend for great good. If not, automatic fallback to scipy.fftpack and numpy is provided.

Basic FFT Functions

planfftw.fft(a, nfft=None, axis=-1)

Plan a discrete Fourier transform function.

Parameters

anumber, shape or array-like

An input array, its shape or length.

nfftOptional[int]

Number of FFT points. Default is input size along specified axis

axisOptional[int]

Axis along which to perform the fft. Default is -1.

Returns

planned_fft(x)

Planned fft function.

planfftw.fft_pair(a, nfft=None, axis=-1, crop_ifft=False)

Plan a discrete Fourier transform function pair.

Parameters

anumber, shape or array-like

An input array, its shape or length.

nfftOptional[int]

Number of FFT points. Default is input size along specified axis

axisOptional[int]

Axis along which to perform the fft. Default is -1.

crop_ifftOptional[boolean]

Indicates whether the planned ifft function should crop its output to match input size. Default is False.

Returns

planned_fft(x)

Planned fft function.

planned_ifft(x)

Planned ifft function.

planfftw.fftn(a, shape=None, axes=None)

Returns a planned function that computes the N-D DFT of an array.

Parameters

aarray-like or shape

An input array or its shape

shapeOptional[List[int]]

Number of FFT points. Default is input size along specified axes

axesOptional[sequence of ints]

Axes along which to perform the fft. Default is all axes.

Returns

planned_fftn(x)

Planned fft function.

planfftw.fftn_pair(a, shape=None, axes=None, crop_ifft=False)

Returns a planned function that computes the N-D DFT of an array.

Parameters

aarray-like or shape

An input array or its shape

shapeOptional[List[int]]

Number of FFT points. Default is input size along specified axes

axesOptional[sequence of ints]

Axes along which to perform the fft. Default is all axes.

crop_ifftOptional[boolean]

Indicates whether the planned ifft function should crop its output to match input size. Default is False.

Returns

planned_fftn(x)

Planned fft function.

planned_ifftn(x)

Planned ifft function.

planfftw.rfft(a, nfft=None, axis=-1)

Returns a planned function that computes the 1-D DFT of a real-valued sequence or array.

Parameters

anumber, shape or array-like

An input array, its shape or length.

nfftOptional[int]

Number of FFT points. Default is input size along specified axis

axisOptional[int]

Axis along which to perform the fft. Default is -1.

Returns

planned_rfft(x)

Planned fft function.

planfftw.rfft_pair(a, nfft=None, axis=-1, crop_ifft=False)

Returns a planned function that computes the 1-D DFT of a real-valued sequence or array.

Parameters

anumber, shape or array-like

An input array, its shape or length.

nfftOptional[int]

Number of FFT points. Default is input size along specified axis

axisOptional[int]

Axis along which to perform the fft. Default is -1.

crop_ifftOptional[boolean]

Indicates whether the planned ifft function should crop its output to match input size. Default is False.

Returns

planned_rfft(x)

Planned fft function

planned_irfft(x)

Planned ifft function

planfftw.rfftn(a, shape=None, axes=None)

Returns a planned function that computes the N-D DFT of a real-valued array.

Parameters

aarray-like or shape

An input array or its shape.

shapeOptional[sequence of ints]

Number of FFT points. Default is input size along specified axes

axesOptional[sequence of ints]

Axes along which to perform the fft. Default is all axes.

Returns

planned_rfftn(x)

Planned fft function.

planfftw.rfftn_pair(a, shape=None, axes=None, crop_ifft=False)

Returns a planned function that computes the N-D DFT of a real-valued array.

Parameters

aarray-like or shape

An input array or its shape.

shapeOptional[sequence of ints]

Number of FFT points. Default is input size along specified axes

axesOptional[sequence of ints]

Axes along which to perform the fft. Default is all axes.

crop_ifftOptional[boolean]

Indicates whether the planned ifft function should crop its output to match input size. Default is False.

Returns

planned_rfftn(x)

Planned fft function.

planned_irfftn(x)

Planned ifft function.

planfftw.ifft(a, nfft=None, axis=-1)

Returns a planned function that computes the 1-D inverse DFT of a sequence or array.

Parameters

anumber, shape or array-like

An input array, its shape or length.

nfftOptional[int]

Number of FFT points. Default is input size along specified axis

axisOptional[int]

Axis along which to perform the fft. Default is -1.

Returns

planned_ifft(x)

Planned ifft function.

planfftw.ifft_pair(a, nfft=None, axis=-1, crop_fft=False)

Returns a planned function that computes the 1-D inverse DFT of a sequence or array.

Parameters

anumber, shape or array-like

An input array, its shape or length.

nfftOptional[int]

Number of FFT points. Default is input size along specified axis

axisOptional[int]

Axis along which to perform the fft. Default is -1.

crop_fftOptional[boolean]

Indicates that the fft function should crop its output to match the shape of the input to the ifft function

Returns

planned_ifft(x)

Planned ifft function.

planned_fft(x)

Planned fft function.

planfftw.ifftn(a, shape=None, axes=None)

Returns a planned function that computes the N-D DFT of an array.

Parameters

aarray-like or shape

An input array or its shape

nfftOptional[sequence of ints]

Number of FFT points. Default is input size along specified axes

axesOptional[sequence of ints]

Axes along which to perform the fft. Default is all axes.

Returns

planned_ifftn(x)

Planned fft function.

planfftw.ifftn_pair(a, shape=None, axes=None, crop_fft=False)

Returns a planned function that computes the N-D DFT of an array.

Parameters

aarray-like or shape

An input array or its shape

shapeOptional[sequence of ints]

Number of FFT points. Default is input size along specified axes

axesOptional[sequence of ints]

Axes along which to perform the fft. Default is all axes.

crop_fftOptional[boolean]

Indicates that the fft function should crop its output to match the shape of the input to the ifft function

Returns

planned_ifftn(x)

Planned fft function.

planned_fftn(x)

Planned ifft function.

planfftw.irfft(a, nfft=None, axis=-1)

Returns a planned function that computes the real-valued 1-D inverse DFT of a sequence or array.

Parameters

anumber, shape or array-like

An input array, its shape or length.

nfftOptional[int]

Number of FFT points. Default is input size along specified axis

axisOptional[int]

Axis along which to perform the fft. Default is -1.

Returns

planned_irfft(x)

Planned ifft function.

planfftw.irfft_pair(a, nfft=None, axis=-1)

Returns a planned function that computes the real-valued 1-D inverse DFT of a sequence or array.

Parameters

anumber, shape or array-like

An input array, its shape or length.

nfftOptional[int]

Number of FFT points. Default is input size along specified axis

axisOptional[int]

Axis along which to perform the fft. Default is -1.

Returns

planned_irfft(x)

Planned ifft function.

planned_rfft(x)

Planned fft function.

planfftw.irfftn(a, shape=None, axes=None)

Returns a planned function that computes the N-D DFT of a real-valued array.

Parameters

aarray-like or shape

An input array or its shape.

shapeOptional[sequence of ints]

Number of FFT points. Default is input size along specified axes

axesOptional[sequence of ints]

Axes along which to perform the fft. Default is all axes.

Returns

planned_irfftn(x)

Planned ifft function.

planfftw.irfftn_pair(a, shape=None, axes=None)

Returns a planned function that computes the N-D DFT of a real-valued array.

Parameters

aarray-like or shape

An input array or its shape.

shapeOptional[sequence of ints]

Number of FFT points. Default is input size along specified axes

axesOptional[sequence of ints]

Axes along which to perform the fft. Default is all axes.

Returns

planned_irfftn(x)

Planned ifft function.

planned_rfftn(x)

Planned fft function.

Advanced Planners

planfftw.convolve(plan_x, plan_y, mode='full', axis=None)

Plan a function for convolving two arrays.

This planner distinguishes between several different cases:

1. 1-D convolution of 1-D sequences or along single axis in N-D arrays

2. N-D convolution of N-D sequences

3. 1-D convolution along single axis in N-D array with 1-D sequence

4. 1-D convolution of 1-D sequence along single axis in N-D array

The shapes of the two inputs are usually sufficient to determine which case should be used. However, to get 1-D convolution along single axis in N-D arrays, ‘axes’ must be a single integer or a length 1 sequence.

Parameters

plan_xinteger, shape or array-like

First input sequence, it’s shape or length.

plan_yinteger, shape or array-like

Second input sequence, it’s shape or length.

modeOptional[str]

A string indicating the output size.

‘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 zero-padding.

‘same’

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

axisOptional[int or sequence of ints]

The axis or axes along which the convolution is computed. Default is the last N axes of the highest-rank input where N is the rank of the lowest-rank input.

Returns

planned_convolve(x, y)

Planned convolution function.

Raises

ValueError

If no function can be planned for the given arguments.

planfftw.convolve_const_x(x, plan_y, mode='full', axis=None)

Plan a function for convolving a constant array with another array.

This planner distinguishes between several different cases:

1. 1-D convolution of 1-D sequences or along single axis in N-D arrays

2. N-D convolution of N-D sequences

3. 1-D convolution along single axis in N-D array with 1-D sequence

4. 1-D convolution of 1-D sequence along single axis in N-D array

The shapes of the two inputs are usually sufficient to determine which case should be used. However, to get 1-D convolution along single axis in N-D arrays, ‘axes’ must be a single integer or a length 1 sequence.

Parameters

x: Array-like

First input (constant)

plan_y: integer, shape or array-like

Second input or it’s shape or length.

mode: Optional[str]

A string indicating the output size.

‘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 zero-padding.

‘same’

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

axis: Optional[int or sequence of ints]

The axis or axes along which the convolution is computed. Default is the last N axes of the highest-rank input where N is the rank of the lowest-rank input.

Returns

planned_convolve(y)

Planned convolution function.

Raises

ValueError

If no function can be planned for the given arguments.

planfftw.convolve_const_y(plan_x, y, mode='full', axis=None)

Plan a function for convolving an array with another constant array.

This planner distinguishes between several different cases:

1. 1-D convolution of 1-D sequences or along single axis in N-D arrays

2. N-D convolution of N-D sequences

3. 1-D convolution along single axis in N-D array with 1-D sequence

4. 1-D convolution of 1-D sequence along single axis in N-D array

The shapes of the two inputs are usually sufficient to determine which case should be used. However, to get 1-D convolution along single axis in N-D arrays, ‘axes’ must be a single integer or a length 1 sequence.

Parameters

plan_x: integer, shape or Array-like

First input or it’s shape or length.

y: Array-like

Second input (constant)

mode: Optional[str]

A string indicating the output size.

‘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 zero-padding.

‘same’

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

axis: Optional[int or sequence of ints]

The axis or axes along which the convolution is computed. Default is the last N axes of the highest-rank input where N is the rank of the lowest-rank input.

Returns

planned_convolve(x)

Planned convolution function.

Raises

ValueError

If no function can be planned for the given arguments.

planfftw.convolve2(plan_x, plan_y, mode='full', axis=None)

Plan a function for convolving two arrays.

The planned function is returned along with separate input transform functions. This is intended for more advanced use cases, such as when precise control of transforms is required for memoization or other reasons. For most use cases, convolve, convolve_const_x or convolve_const_y are more appropriate.

This planner distinguishes between several different cases:

1. 1-D convolution of 1-D sequences or along single axis in N-D arrays

2. N-D convolution of N-D sequences

3. 1-D convolution along single axis in N-D array with 1-D sequence

4. 1-D convolution of 1-D sequence along single axis in N-D array

The shapes of the two inputs are usually sufficient to determine which case should be used. However, to get 1-D convolution along single axis in N-D arrays, ‘axes’ must be a single integer or a length 1 sequence.

Parameters

plan_xinteger, shape or array-like

First input sequence, it’s shape or length.

plan_yinteger, shape or array-like

Second input sequence, it’s shape or length.

modeOptional[str]

A string indicating the output size.

‘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 zero-padding.

‘same’

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

axisOptional[int or sequence of ints]

The axis or axes along which the convolution is computed. Default is the last N axes of the highest-rank input where N is the rank of the lowest-rank input.

Returns

planned_convolve(x_transformed, y_transformed)

Planned convolution function.

x_transform_function(x)

Planned transform function for first sequence

y_transform_function(y)

Planned transform function for second sequence

Raises

ValueError

If no function can be planned for the given arguments.

See also

convolve, convolve_const_x, convolve_const_y

planfftw.correlate(plan_x, plan_y, mode='full', axis=None)

Plan a function for correlating two arrays.

This planner distinguishes between several different cases:

1. 1-D correlation of 1-D sequences or along single axis in N-D arrays

2. N-D correlation of N-D sequences

3. 1-D correlation along single axis in N-D array with 1-D sequence

4. 1-D correlation of 1-D sequence along single axis in N-D array

The shapes of the two inputs are usually sufficient to determine which case should be used. However, to get 1-D correlation along single axis in N-D arrays, ‘axes’ must be a single integer or a length 1 sequence.

Parameters

plan_xinteger, shape or array-like

First input sequence, it’s shape or length.

plan_yinteger, shape or array-like

Second input sequence, it’s shape or length.

modeOptional[str]

A string indicating the output size.

‘full’

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

‘valid’

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

‘same’

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

axisOptional[int or sequence of ints]

The axis or axes along which the correlation is computed. Default is the last N axes of the highest-rank input where N is the rank of the lowest-rank input.

Returns

planned_correlate(x, y)

Planned correlation function.

Raises

ValueError

If no function can be planned for the given arguments.

planfftw.correlate_const_x(x, plan_y, mode='full', axis=None)

Plan a function for correlating a constant array with another array.

This planner distinguishes between several different cases:

1. 1-D correlation of 1-D sequences or along single axis in N-D arrays

2. N-D correlation of N-D sequences

3. 1-D correlation along single axis in N-D array with 1-D sequence

4. 1-D correlation of 1-D sequence along single axis in N-D array

The shapes of the two inputs are usually sufficient to determine which case should be used. However, to get 1-D correlation along single axis in N-D arrays, ‘axes’ must be a single integer or a length 1 sequence.

Parameters

x: Array-like

First input (constant)

plan_y: integer, shape or array-like

Second input or it’s shape or length.

mode: Optional[str]

A string indicating the output size.

‘full’

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

‘valid’

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

‘same’

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

axis: Optional[int or sequence of ints]

The axis or axes along which the correlation is computed. Default is the last N axes of the highest-rank input where N is the rank of the lowest-rank input.

Returns

planned_correlate(y)

Planned correlation function.

Raises

ValueError

If no function can be planned for the given arguments.

planfftw.correlate_const_y(plan_x, y, mode='full', axis=None)

Plan a function for correlating an array with another constant array.

This planner distinguishes between several different cases:

1. 1-D correlation of 1-D sequences or along single axis in N-D arrays

2. N-D correlation of N-D sequences

3. 1-D correlation along single axis in N-D array with 1-D sequence

4. 1-D correlation of 1-D sequence along single axis in N-D array

The shapes of the two inputs are usually sufficient to determine which case should be used. However, to get 1-D correlation along single axis in N-D arrays, ‘axes’ must be a single integer or a length 1 sequence.

Parameters

x: Array-like

First input (constant)

plan_y: integer, shape or array-like

Second input or it’s shape or length.

mode: Optional[str]

A string indicating the output size.

‘full’

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

‘valid’

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

‘same’

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

axis: Optional[int or sequence of ints]

The axis or axes along which the correlation is computed. Default is the last N axes of the highest-rank input where N is the rank of the lowest-rank input.

Returns

planned_correlate(x)

Planned correlation function.

Raises

ValueError

If no function can be planned for the given arguments.

planfftw.correlate2(plan_x, plan_y, mode='full', axis=None)

Plan a function for correlating two arrays.

The planned function is returned along with separate input transform functions. This is intended for more advanced use cases, such as when precise control of transforms is required for memoization or other reasons. For most use cases, correlate, correlate_const_x or correlate_const_y are more appropriate.

This planner distinguishes between several different cases:

1. 1-D correlation of 1-D sequences or along single axis in N-D arrays

2. N-D correlation of N-D sequences

3. 1-D correlation along single axis in N-D array with 1-D sequence

4. 1-D correlation of 1-D sequence along single axis in N-D array

The shapes of the two inputs are usually sufficient to determine which case should be used. However, to get 1-D correlation along single axis in N-D arrays, ‘axes’ must be a single integer or a length 1 sequence.

Parameters

plan_xinteger, shape or array-like

First input sequence, it’s shape or length.

plan_yinteger, shape or array-like

Second input sequence, it’s shape or length.

modeOptional[str]

A string indicating the output size.

‘full’

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

‘valid’

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

‘same’

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

axisOptional[int or sequence of ints]

The axis or axes along which the correlation is computed. Default is the last N axes of the highest-rank input where N is the rank of the lowest-rank input.

Returns

planned_correlate(x_transformed, y_transformed)

Planned correlation function

x_transform_function(x)

Planned transform function for the first array

y_transform_function(y)

Planned transform function for the second array

Raises

ValueError

If no function can be planned for the given arguments.

planfftw.firfilter(plan_b, plan_x, axis=-1)

Returns a planned function that filters a signal using the frequency domain overlap-and-add method with pyfftw.

Parameters

plan_binteger, shape or array-like

A filter vector or its length or shape

plan_xinteger, shape or array-like

A signal vector or its length or shape

axisoptional[int]

Axis in plan_x along which the filter is applied

Returns

planned_filter(b, x)

The filtering function

Raises

ValueError

If filter has more than one dimensions.

planfftw.firfilter_const_filter(b, plan_x, axis=-1)

Returns a planned function that filters a signal using the frequency domain overlap-and-add method with pyfftw.

Parameters

barray-like

A filter vector

plan_xinteger, shape or array-like

A signal vector or its length or shape

axisoptional[int]

Axis in plan_x along which the filter is applied

Returns

planned_firfilter(x)

The planned FIR-filtering function.

Raises

ValueError

If filter has more than one dimensions.

planfftw.firfilter_const_signal(plan_b, x, axis=-1)

Returns a planned function that filters a signal using the frequency domain overlap-and-add method with pyfftw.

Parameters

plan_binteger, shape or array-like

A filter vector or its length or shape

xArray-like

A signal vector or array

axisoptional[int]

Axis in plan_x along which the filter is applied

Returns

planned_firfilter(b)

The planned FIR-filtering function.

Raises

ValueError

If filter has more than one dimensions.

planfftw.firfilter2(filter_coefficients, signal, axis=-1)

Returns a planned FIR-filter function.

The planned function is returned along with separate input transform functions. This is intended for more advanced use cases, such as when precise control of transforms is required for memoization or other reasons. For most use cases, firfilter, firfilter_const_filter or firfilter_const_signal are more appropriate.

Parameters

filter_coefficients: Union[Array-like, int]

An array of filter coefficients or a filter length

signal: Union[Array-like, Tuple[int, int], int]

A signal array, shape or length

axis: int

The axis of signal along which the filter shall be applied

Returns

planned_filter(b_transformed, x_transformed)

The filtering function

b_transform_function(b)

The filter transform function

x_transform_function(x)

The signal transform function

See also

firfilter, firfilter_const_filter, firfilter_const_signal