Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1# Author: Eric Larson 

2# 2014 

3 

4"""Tools for MLS generation""" 

5 

6import numpy as np 

7 

8from ._max_len_seq_inner import _max_len_seq_inner 

9 

10__all__ = ['max_len_seq'] 

11 

12 

13# These are definitions of linear shift register taps for use in max_len_seq() 

14_mls_taps = {2: [1], 3: [2], 4: [3], 5: [3], 6: [5], 7: [6], 8: [7, 6, 1], 

15 9: [5], 10: [7], 11: [9], 12: [11, 10, 4], 13: [12, 11, 8], 

16 14: [13, 12, 2], 15: [14], 16: [15, 13, 4], 17: [14], 

17 18: [11], 19: [18, 17, 14], 20: [17], 21: [19], 22: [21], 

18 23: [18], 24: [23, 22, 17], 25: [22], 26: [25, 24, 20], 

19 27: [26, 25, 22], 28: [25], 29: [27], 30: [29, 28, 7], 

20 31: [28], 32: [31, 30, 10]} 

21 

22def max_len_seq(nbits, state=None, length=None, taps=None): 

23 """ 

24 Maximum length sequence (MLS) generator. 

25 

26 Parameters 

27 ---------- 

28 nbits : int 

29 Number of bits to use. Length of the resulting sequence will 

30 be ``(2**nbits) - 1``. Note that generating long sequences 

31 (e.g., greater than ``nbits == 16``) can take a long time. 

32 state : array_like, optional 

33 If array, must be of length ``nbits``, and will be cast to binary 

34 (bool) representation. If None, a seed of ones will be used, 

35 producing a repeatable representation. If ``state`` is all 

36 zeros, an error is raised as this is invalid. Default: None. 

37 length : int, optional 

38 Number of samples to compute. If None, the entire length 

39 ``(2**nbits) - 1`` is computed. 

40 taps : array_like, optional 

41 Polynomial taps to use (e.g., ``[7, 6, 1]`` for an 8-bit sequence). 

42 If None, taps will be automatically selected (for up to 

43 ``nbits == 32``). 

44 

45 Returns 

46 ------- 

47 seq : array 

48 Resulting MLS sequence of 0's and 1's. 

49 state : array 

50 The final state of the shift register. 

51 

52 Notes 

53 ----- 

54 The algorithm for MLS generation is generically described in: 

55 

56 https://en.wikipedia.org/wiki/Maximum_length_sequence 

57 

58 The default values for taps are specifically taken from the first 

59 option listed for each value of ``nbits`` in: 

60 

61 http://www.newwaveinstruments.com/resources/articles/m_sequence_linear_feedback_shift_register_lfsr.htm 

62 

63 .. versionadded:: 0.15.0 

64 

65 Examples 

66 -------- 

67 MLS uses binary convention: 

68 

69 >>> from scipy.signal import max_len_seq 

70 >>> max_len_seq(4)[0] 

71 array([1, 1, 1, 1, 0, 1, 0, 1, 1, 0, 0, 1, 0, 0, 0], dtype=int8) 

72 

73 MLS has a white spectrum (except for DC): 

74 

75 >>> import matplotlib.pyplot as plt 

76 >>> from numpy.fft import fft, ifft, fftshift, fftfreq 

77 >>> seq = max_len_seq(6)[0]*2-1 # +1 and -1 

78 >>> spec = fft(seq) 

79 >>> N = len(seq) 

80 >>> plt.plot(fftshift(fftfreq(N)), fftshift(np.abs(spec)), '.-') 

81 >>> plt.margins(0.1, 0.1) 

82 >>> plt.grid(True) 

83 >>> plt.show() 

84 

85 Circular autocorrelation of MLS is an impulse: 

86 

87 >>> acorrcirc = ifft(spec * np.conj(spec)).real 

88 >>> plt.figure() 

89 >>> plt.plot(np.arange(-N/2+1, N/2+1), fftshift(acorrcirc), '.-') 

90 >>> plt.margins(0.1, 0.1) 

91 >>> plt.grid(True) 

92 >>> plt.show() 

93 

94 Linear autocorrelation of MLS is approximately an impulse: 

95 

96 >>> acorr = np.correlate(seq, seq, 'full') 

97 >>> plt.figure() 

98 >>> plt.plot(np.arange(-N+1, N), acorr, '.-') 

99 >>> plt.margins(0.1, 0.1) 

100 >>> plt.grid(True) 

101 >>> plt.show() 

102 

103 """ 

104 if taps is None: 

105 if nbits not in _mls_taps: 

106 known_taps = np.array(list(_mls_taps.keys())) 

107 raise ValueError('nbits must be between %s and %s if taps is None' 

108 % (known_taps.min(), known_taps.max())) 

109 taps = np.array(_mls_taps[nbits], np.intp) 

110 else: 

111 taps = np.unique(np.array(taps, np.intp))[::-1] 

112 if np.any(taps < 0) or np.any(taps > nbits) or taps.size < 1: 

113 raise ValueError('taps must be non-empty with values between ' 

114 'zero and nbits (inclusive)') 

115 taps = np.ascontiguousarray(taps) # needed for Cython 

116 n_max = (2**nbits) - 1 

117 if length is None: 

118 length = n_max 

119 else: 

120 length = int(length) 

121 if length < 0: 

122 raise ValueError('length must be greater than or equal to 0') 

123 # We use int8 instead of bool here because NumPy arrays of bools 

124 # don't seem to work nicely with Cython 

125 if state is None: 

126 state = np.ones(nbits, dtype=np.int8, order='c') 

127 else: 

128 # makes a copy if need be, ensuring it's 0's and 1's 

129 state = np.array(state, dtype=bool, order='c').astype(np.int8) 

130 if state.ndim != 1 or state.size != nbits: 

131 raise ValueError('state must be a 1-D array of size nbits') 

132 if np.all(state == 0): 

133 raise ValueError('state must not be all zeros') 

134 

135 seq = np.empty(length, dtype=np.int8, order='c') 

136 state = _max_len_seq_inner(taps, state, nbits, length, seq) 

137 return seq, state