DOC: Add examples/graphs to max_len_seq

scipy/signal/_max_len_seq.py

@@ -34,7 +34,7 @@ def max_len_seq(nbits, state=None, length=None, taps=None):
         (bool) representation. If None, a seed of ones will be used,
         producing a repeatable representation. If ``state`` is all
         zeros, an error is raised as this is invalid. Default: None.
-    length : int | None, optional
+    length : int, optional
         Number of samples to compute. If None, the entire length
         ``(2**nbits) - 1`` is computed.
     taps : array_like, optional
@@ -62,6 +62,45 @@ def max_len_seq(nbits, state=None, length=None, taps=None):
             m_sequence_linear_feedback_shift_register_lfsr.htm
 
     .. versionadded:: 0.15.0
+
+    Examples
+    --------
+    MLS uses binary convention:
+
+    >>> from scipy.signal import max_len_seq
+    >>> max_len_seq(4)[0]
+    array([1, 1, 1, 1, 0, 1, 0, 1, 1, 0, 0, 1, 0, 0, 0], dtype=int8)
+
+    MLS has a white spectrum (except for DC):
+
+    >>> import matplotlib.pyplot as plt
+    >>> from numpy.fft import fft, ifft, fftshift, fftfreq
+    >>> seq = max_len_seq(6)[0]*2-1  # +1 and -1
+    >>> spec = fft(seq)
+    >>> N = len(seq)
+    >>> plt.plot(fftshift(fftfreq(N)), fftshift(np.abs(spec)), '.-')
+    >>> plt.margins(0.1, 0.1)
+    >>> plt.grid(True)
+    >>> plt.show()
+
+    Circular autocorrelation of MLS is an impulse:
+
+    >>> acorrcirc = ifft(spec * np.conj(spec))
+    >>> plt.figure()
+    >>> plt.plot(arange(-N/2+1, N/2+1), fftshift(acorrcirc), '.-')
+    >>> plt.margins(0.1, 0.1)
+    >>> plt.grid(True)
+    >>> plt.show()
+
+    Linear autocorrelation of MLS is approximately an impulse:
+
+    >>> acorr = np.correlate(seq, seq, 'full')
+    >>> plt.figure()
+    >>> plt.plot(arange(-N+1, N), acorr, '.-')
+    >>> plt.margins(0.1, 0.1)
+    >>> plt.grid(True)
+    >>> plt.show()
+
     """
     if taps is None:
         if nbits not in _mls_taps: