Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/scipy/fft/_helper.py: 75%

1from functools import update_wrapper, lru_cache 

2 

3from ._pocketfft import helper as _helper 

4 

5 

6def next_fast_len(target, real=False): 

7 """Find the next fast size of input data to ``fft``, for zero-padding, etc. 

8 

9 SciPy's FFT algorithms gain their speed by a recursive divide and conquer 

10 strategy. This relies on efficient functions for small prime factors of the 

11 input length. Thus, the transforms are fastest when using composites of the 

12 prime factors handled by the fft implementation. If there are efficient 

13 functions for all radices <= `n`, then the result will be a number `x` 

14 >= ``target`` with only prime factors < `n`. (Also known as `n`-smooth 

15 numbers) 

16 

17 Parameters 

18 ---------- 

19 target : int 

20 Length to start searching from. Must be a positive integer. 

21 real : bool, optional 

22 True if the FFT involves real input or output (e.g., `rfft` or `hfft` 

23 but not `fft`). Defaults to False. 

24 

25 Returns 

26 ------- 

27 out : int 

28 The smallest fast length greater than or equal to ``target``. 

29 

30 Notes 

31 ----- 

32 The result of this function may change in future as performance 

33 considerations change, for example, if new prime factors are added. 

34 

35 Calling `fft` or `ifft` with real input data performs an ``'R2C'`` 

36 transform internally. 

37 

38 Examples 

39 -------- 

40 On a particular machine, an FFT of prime length takes 11.4 ms: 

41 

42 >>> from scipy import fft 

43 >>> import numpy as np 

44 >>> rng = np.random.default_rng() 

45 >>> min_len = 93059 # prime length is worst case for speed 

46 >>> a = rng.standard_normal(min_len) 

47 >>> b = fft.fft(a) 

48 

49 Zero-padding to the next regular length reduces computation time to 

50 1.6 ms, a speedup of 7.3 times: 

51 

52 >>> fft.next_fast_len(min_len, real=True) 

53 93312 

54 >>> b = fft.fft(a, 93312) 

55 

56 Rounding up to the next power of 2 is not optimal, taking 3.0 ms to 

57 compute; 1.9 times longer than the size given by ``next_fast_len``: 

58 

59 >>> b = fft.fft(a, 131072) 

60 

61 """ 

62 pass 

63 

64 

65# Directly wrap the c-function good_size but take the docstring etc., from the 

66# next_fast_len function above 

67next_fast_len = update_wrapper(lru_cache()(_helper.good_size), next_fast_len) 

68next_fast_len.__wrapped__ = _helper.good_size 

69 

70 

71def _init_nd_shape_and_axes(x, shape, axes): 

72 """Handle shape and axes arguments for N-D transforms. 

73 

74 Returns the shape and axes in a standard form, taking into account negative 

75 values and checking for various potential errors. 

76 

77 Parameters 

78 ---------- 

79 x : array_like 

80 The input array. 

81 shape : int or array_like of ints or None 

82 The shape of the result. If both `shape` and `axes` (see below) are 

83 None, `shape` is ``x.shape``; if `shape` is None but `axes` is 

84 not None, then `shape` is ``numpy.take(x.shape, axes, axis=0)``. 

85 If `shape` is -1, the size of the corresponding dimension of `x` is 

86 used. 

87 axes : int or array_like of ints or None 

88 Axes along which the calculation is computed. 

89 The default is over all axes. 

90 Negative indices are automatically converted to their positive 

91 counterparts. 

92 

93 Returns 

94 ------- 

95 shape : array 

96 The shape of the result. It is a 1-D integer array. 

97 axes : array 

98 The shape of the result. It is a 1-D integer array. 

99 

100 """ 

101 return _helper._init_nd_shape_and_axes(x, shape, axes)