move spectrogram to utils module

Author: v923z

code/scipy/scipy.c

@@ -48,4 +48,4 @@ mp_obj_module_t ulab_scipy_module = {
     .base = { &mp_type_module },
     .globals = (mp_obj_dict_t*)&mp_module_ulab_scipy_globals,
 };
-#endif
+#endif /* ULAB_HAS_SCIPY */

code/scipy/signal/signal.c

@@ -19,39 +19,6 @@
 #include "../../ulab.h"
 #include "../../ndarray.h"
 #include "../../numpy/carray/carray_tools.h"
-#include "../../numpy/fft/fft_tools.h"
-
-#if ULAB_SCIPY_SIGNAL_HAS_SPECTROGRAM
-//| import ulab.numpy
-//|
-//| def spectrogram(r: ulab.numpy.ndarray) -> ulab.numpy.ndarray:
-//|     """
-//|     :param ulab.numpy.ndarray r: A 1-dimension array of values whose size is a power of 2
-//|
-//|     Computes the spectrum of the input signal.  This is the absolute value of the (complex-valued) fft of the signal.
-//|     This function is similar to scipy's ``scipy.signal.spectrogram``."""
-//|     ...
-//|
-
-mp_obj_t signal_spectrogram(size_t n_args, const mp_obj_t *args) {
-    #if ULAB_SUPPORTS_COMPLEX & ULAB_FFT_IS_NUMPY_COMPATIBLE
-        return fft_fft_ifft_spectrogram(args[0], FFT_SPECTROGRAM);
-    #else
-    if(n_args == 2) {
-        return fft_fft_ifft_spectrogram(n_args, args[0], args[1], FFT_SPECTROGRAM);
-    } else {
-        return fft_fft_ifft_spectrogram(n_args, args[0], mp_const_none, FFT_SPECTROGRAM);
-    }
-    #endif
-}
-
-#if ULAB_SUPPORTS_COMPLEX & ULAB_FFT_IS_NUMPY_COMPATIBLE
-MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(signal_spectrogram_obj, 1, 1, signal_spectrogram);
-#else
-MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(signal_spectrogram_obj, 1, 2, signal_spectrogram);
-#endif
-
-#endif /* ULAB_SCIPY_SIGNAL_HAS_SPECTROGRAM */
 
 #if ULAB_SCIPY_SIGNAL_HAS_SOSFILT & ULAB_MAX_DIMS > 1
 static void signal_sosfilt_array(mp_float_t *x, const mp_float_t *coeffs, mp_float_t *zf, const size_t len) {
@@ -155,9 +122,6 @@ MP_DEFINE_CONST_FUN_OBJ_KW(signal_sosfilt_obj, 2, signal_sosfilt);
 
 static const mp_rom_map_elem_t ulab_scipy_signal_globals_table[] = {
     { MP_OBJ_NEW_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_signal) },
-    #if ULAB_SCIPY_SIGNAL_HAS_SPECTROGRAM
-        { MP_OBJ_NEW_QSTR(MP_QSTR_spectrogram), (mp_obj_t)&signal_spectrogram_obj },
-    #endif
     #if ULAB_SCIPY_SIGNAL_HAS_SOSFILT & ULAB_MAX_DIMS > 1
         { MP_OBJ_NEW_QSTR(MP_QSTR_sosfilt), (mp_obj_t)&signal_sosfilt_obj },
     #endif

code/scipy/signal/signal.h

@@ -18,7 +18,6 @@
 
 extern mp_obj_module_t ulab_scipy_signal_module;
 
-MP_DECLARE_CONST_FUN_OBJ_VAR_BETWEEN(signal_spectrogram_obj);
 MP_DECLARE_CONST_FUN_OBJ_KW(signal_sosfilt_obj);
 
 #endif /* _SCIPY_SIGNAL_ */

code/ulab.c

@@ -33,7 +33,7 @@
 #include "user/user.h"
 #include "utils/utils.h"
 
-#define ULAB_VERSION 4.4.0
+#define ULAB_VERSION 4.4.1
 #define xstr(s) str(s)
 #define str(s) #s
 

code/ulab.h

@@ -663,10 +663,6 @@
 #define ULAB_SCIPY_HAS_SIGNAL_MODULE        (1)
 #endif
 
-#ifndef ULAB_SCIPY_SIGNAL_HAS_SPECTROGRAM
-#define ULAB_SCIPY_SIGNAL_HAS_SPECTROGRAM   (1)
-#endif
-
 #ifndef ULAB_SCIPY_SIGNAL_HAS_SOSFILT
 #define ULAB_SCIPY_SIGNAL_HAS_SOSFILT       (1)
 #endif
@@ -711,12 +707,7 @@
 #define ULAB_SCIPY_SPECIAL_HAS_GAMMALN      (1)
 #endif
 
-// user-defined module; source of the module and
-// its sub-modules should be placed in code/user/
-#ifndef ULAB_HAS_USER_MODULE
-#define ULAB_HAS_USER_MODULE                (0)
-#endif
-
+// functions of the utils module
 #ifndef ULAB_HAS_UTILS_MODULE
 #define ULAB_HAS_UTILS_MODULE               (1)
 #endif
@@ -737,4 +728,14 @@
 #define ULAB_UTILS_HAS_FROM_UINT32_BUFFER   (1)
 #endif
 
+#ifndef ULAB_UTILS_HAS_SPECTROGRAM
+#define ULAB_UTILS_HAS_SPECTROGRAM          (1)
+#endif
+
+// user-defined module; source of the module and
+// its sub-modules should be placed in code/user/
+#ifndef ULAB_HAS_USER_MODULE
+#define ULAB_HAS_USER_MODULE                (0)
+#endif
+
 #endif

code/utils/utils.c

@@ -16,6 +16,8 @@
 #include "py/misc.h"
 #include "utils.h"
 
+#include "../numpy/fft/fft_tools.h"
+
 #if ULAB_HAS_UTILS_MODULE
 
 enum UTILS_BUFFER_TYPE {
@@ -187,8 +189,41 @@ static mp_obj_t utils_from_uint32_buffer(size_t n_args, const mp_obj_t *pos_args
 MP_DEFINE_CONST_FUN_OBJ_KW(utils_from_uint32_buffer_obj, 1, utils_from_uint32_buffer);
 #endif
 
+#endif /* ULAB_UTILS_HAS_FROM_INT16_BUFFER | ULAB_UTILS_HAS_FROM_UINT16_BUFFER | ULAB_UTILS_HAS_FROM_INT32_BUFFER | ULAB_UTILS_HAS_FROM_UINT32_BUFFER */
+
+#if ULAB_UTILS_HAS_SPECTROGRAM
+//| import ulab.numpy
+//|
+//| def spectrogram(r: ulab.numpy.ndarray) -> ulab.numpy.ndarray:
+//|     """
+//|     :param ulab.numpy.ndarray r: A 1-dimension array of values whose size is a power of 2
+//|
+//|     Computes the spectrum of the input signal.  This is the absolute value of the (complex-valued) fft of the signal.
+//|     This function is similar to scipy's ``scipy.signal.welch`` https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.welch.html."""
+//|     ...
+//|
+
+mp_obj_t utils_spectrogram(size_t n_args, const mp_obj_t *args) {
+    #if ULAB_SUPPORTS_COMPLEX & ULAB_FFT_IS_NUMPY_COMPATIBLE
+        return fft_fft_ifft_spectrogram(args[0], FFT_SPECTROGRAM);
+    #else
+    if(n_args == 2) {
+        return fft_fft_ifft_spectrogram(n_args, args[0], args[1], FFT_SPECTROGRAM);
+    } else {
+        return fft_fft_ifft_spectrogram(n_args, args[0], mp_const_none, FFT_SPECTROGRAM);
+    }
+    #endif
+}
+
+#if ULAB_SUPPORTS_COMPLEX & ULAB_FFT_IS_NUMPY_COMPATIBLE
+MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(utils_spectrogram_obj, 1, 1, utils_spectrogram);
+#else
+MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(utils_spectrogram_obj, 1, 2, utils_spectrogram);
 #endif
 
+#endif /* ULAB_UTILS_HAS_SPECTROGRAM */
+
+
 static const mp_rom_map_elem_t ulab_utils_globals_table[] = {
     { MP_OBJ_NEW_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_utils) },
     #if ULAB_UTILS_HAS_FROM_INT16_BUFFER
@@ -203,6 +238,9 @@ static const mp_rom_map_elem_t ulab_utils_globals_table[] = {
     #if ULAB_UTILS_HAS_FROM_UINT32_BUFFER
         { MP_OBJ_NEW_QSTR(MP_QSTR_from_uint32_buffer), (mp_obj_t)&utils_from_uint32_buffer_obj },
     #endif
+    #if ULAB_UTILS_HAS_SPECTROGRAM
+        { MP_OBJ_NEW_QSTR(MP_QSTR_spectrogram), (mp_obj_t)&utils_spectrogram_obj },
+    #endif
 };
 
 static MP_DEFINE_CONST_DICT(mp_module_ulab_utils_globals, ulab_utils_globals_table);
@@ -212,4 +250,4 @@ mp_obj_module_t ulab_utils_module = {
     .globals = (mp_obj_dict_t*)&mp_module_ulab_utils_globals,
 };
 
-#endif
+#endif /* ULAB_HAS_UTILS_MODULE */

docs/manual/source/conf.py

@@ -27,7 +27,7 @@
 author = 'Zoltán Vörös'
 
 # The full version, including alpha/beta/rc tags
-release = '4.4.0'
+release = '4.4.1'
 
 
 # -- General configuration ---------------------------------------------------

docs/manual/source/scipy-signal.rst

@@ -6,7 +6,6 @@ Functions in the ``signal`` module can be called by prepending them by
 ``scipy.signal.``. The module defines the following two functions:
 
 1. `scipy.signal.sosfilt <#sosfilt>`__
-2. `scipy.signal.spectrogram <#spectrogram>`__
 
 sosfilt
 -------
@@ -69,69 +68,3 @@ initial values are assumed to be 0.
     
     
 
-
-spectrogram
------------
-
-In addition to the Fourier transform and its inverse, ``ulab`` also
-sports a function called ``spectrogram``, which returns the absolute
-value of the Fourier transform. This could be used to find the dominant
-spectral component in a time series. The arguments are treated in the
-same way as in ``fft``, and ``ifft``. This means that, if the firmware
-was compiled with complex support, the input can also be a complex
-array.
-
-.. code::
-        
-    # code to be run in micropython
-    
-    from ulab import numpy as np
-    from ulab import scipy as spy
-    
-    x = np.linspace(0, 10, num=1024)
-    y = np.sin(x)
-    
-    a = spy.signal.spectrogram(y)
-    
-    print('original vector:\t', y)
-    print('\nspectrum:\t', a)
-
-.. parsed-literal::
-
-    original vector:	 array([0.0, 0.009775015390171337, 0.01954909674625918, ..., -0.5275140569487312, -0.5357931822978732, -0.5440211108893639], dtype=float64)
-    
-    spectrum:	 array([187.8635087634579, 315.3112063607119, 347.8814873399374, ..., 84.45888934298905, 347.8814873399374, 315.3112063607118], dtype=float64)
-    
-    
-
-
-As such, ``spectrogram`` is really just a shorthand for
-``np.sqrt(a*a + b*b)``:
-
-.. code::
-        
-    # code to be run in micropython
-    
-    from ulab import numpy as np
-    from ulab import scipy as spy
-    
-    x = np.linspace(0, 10, num=1024)
-    y = np.sin(x)
-    
-    a, b = np.fft.fft(y)
-    
-    print('\nspectrum calculated the hard way:\t', np.sqrt(a*a + b*b))
-    
-    a = spy.signal.spectrogram(y)
-    
-    print('\nspectrum calculated the lazy way:\t', a)
-
-.. parsed-literal::
-
-    
-    spectrum calculated the hard way:	 array([187.8635087634579, 315.3112063607119, 347.8814873399374, ..., 84.45888934298905, 347.8814873399374, 315.3112063607118], dtype=float64)
-    
-    spectrum calculated the lazy way:	 array([187.8635087634579, 315.3112063607119, 347.8814873399374, ..., 84.45888934298905, 347.8814873399374, 315.3112063607118], dtype=float64)
-    
-    
-

docs/manual/source/ulab-utils.rst

@@ -137,7 +137,76 @@ These two functions are identical to ``utils.from_int32_buffer``, and
 ``utils.from_uint32_buffer``, with the exception that they convert
 16-bit integers to floating point ``ndarray``\ s.
 
+spectrogram
+-----------
+
+In addition to the Fourier transform and its inverse, ``ulab`` also
+sports a function called ``spectrogram``, which returns the absolute
+value of the Fourier transform, also known as the power spectrum. This
+could be used to find the dominant spectral component in a time series.
+The arguments are treated in the same way as in ``fft``, and ``ifft``.
+This means that, if the firmware was compiled with complex support, the
+input can also be a complex array.
+
+.. code::
+        
+    # code to be run in micropython
+    
+    from ulab import numpy as np
+    from ulab import utils as utils
+    
+    x = np.linspace(0, 10, num=1024)
+    y = np.sin(x)
+    
+    a = utils.spectrogram(y)
+    
+    print('original vector:\n', y)
+    print('\nspectrum:\n', a)
+
+.. parsed-literal::
+
+    original vector:
+     array([0.0, 0.009775015390171337, 0.01954909674625918, ..., -0.5275140569487312, -0.5357931822978732, -0.5440211108893697], dtype=float64)
+    
+    spectrum:
+     array([187.8635087634579, 315.3112063607119, 347.8814873399374, ..., 84.45888934298905, 347.8814873399374, 315.3112063607118], dtype=float64)
+    
+    
+
+
+As such, ``spectrogram`` is really just a shorthand for
+``np.sqrt(a*a + b*b)``, however, it saves significant amounts of RAM:
+the expression ``a*a + b*b`` has to allocate memory for ``a*a``,
+``b*b``, and finally, their sum. In contrast, ``spectrogram`` calculates
+the spectrum internally, and stores it in the memory segment that was
+reserved for the real part of the Fourier transform.
+
 .. code::
+        
+    # code to be run in micropython
+    
+    from ulab import numpy as np
+    from ulab import utils as utils
+    
+    x = np.linspace(0, 10, num=1024)
+    y = np.sin(x)
+    
+    a, b = np.fft.fft(y)
+    
+    print('\nspectrum calculated the hard way:\n', np.sqrt(a*a + b*b))
+    
+    a = utils.spectrogram(y)
+    
+    print('\nspectrum calculated the lazy way:\n', a)
+
+.. parsed-literal::
 
-    # code to be run in CPython
     
+    spectrum calculated the hard way:
+     array([187.8635087634579, 315.3112063607119, 347.8814873399374, ..., 84.45888934298905, 347.8814873399374, 315.3112063607118], dtype=float64)
+    
+    spectrum calculated the lazy way:
+     array([187.8635087634579, 315.3112063607119, 347.8814873399374, ..., 84.45888934298905, 347.8814873399374, 315.3112063607118], dtype=float64)
+    
+    
+