:mod:`ulab` --- Manipulate numeric data similar to numpy ======================================================== .. module:: ulab :synopsis: Manipulate numeric data similar to numpy `ulab` is a numpy-like module for micropython, meant to simplify and speed up common mathematical operations on arrays. The primary goal was to implement a small subset of numpy that might be useful in the context of a microcontroller. This means low-level data processing of linear (array) and two-dimensional (matrix) data. `ulab` is adapted from micropython-ulab, and the original project's documentation can be found at https://micropython-ulab.readthedocs.io/en/latest/ `ulab` is modeled after numpy, and aims to be a compatible subset where possible. Numpy's documentation can be found at https://docs.scipy.org/doc/numpy/index.html .. contents:: .. attribute:: __version__ The closest corresponding version of micropython-ulab ulab.array -- 1- and 2- dimensional array ----------------------------------------- .. class:: ulab.array(values, \*, dtype=float) :param sequence values: Sequence giving the initial content of the array. :param dtype: The type of array values, ``int8``, ``uint8``, ``int16``, ``uint16``, or ``float`` The `values` sequence can either be another ~ulab.array, sequence of numbers (in which case a 1-dimensional array is created), or a sequence where each subsequence has the same length (in which case a 2-dimensional array is created). Passing a ~ulab.array and a different dtype can be used to convert an array from one dtype to another. In many cases, it is more convenient to create an array from a function like `zeros` or `linspace`. `ulab.array` implements the buffer protocol, so it can be used in many places an `array.array` can be used. .. attribute:: shape The size of the array, a tuple of length 1 or 2 .. attribute:: size The number of elements in the array .. attribute:: itemsize The number of elements in the array .. method:: flatten(\*, order='C') :param order: Whether to flatten by rows ('C') or columns ('F') Returns a new `ulab.array` object which is always 1 dimensional. If order is 'C' (the default", then the data is ordered in rows; If it is 'F', then the data is ordered in columns. "C" and "F" refer to the typical storage organization of the C and Fortran languages. .. method:: sort(\*, axis=1) :param axis: Whether to sort elements within rows (0), columns (1), or elements (None) .. method:: transpose() Swap the rows and columns of a 2-dimensional array .. method:: __add__() Adds corresponding elements of the two arrays, or adds a number to all elements of the array. A number must be on the right hand side. If both arguments are arrays, their sizes must match. .. method:: __sub__() Subtracts corresponding elements of the two arrays, or subtracts a number from all elements of the array. A number must be on the right hand side. If both arguments are arrays, their sizes must match. .. method:: __mul__() Multiplies corresponding elements of the two arrays, or multiplies all elements of the array by a number. A number must be on the right hand side. If both arguments are arrays, their sizes must match. .. method:: __div__() Multiplies corresponding elements of the two arrays, or divides all elements of the array by a number. A number must be on the right hand side. If both arguments are arrays, their sizes must match. .. method:: __getitem__() Retrieve an element of the array. .. method:: __setitem__() Set an element of the array. Array type codes ---------------- .. attribute:: int8 Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array` .. attribute:: int16 Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array` .. attribute:: float Type code for floating point values, like the 'f' typecode of `array.array` .. attribute:: uint8 Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array` .. attribute:: uint8 Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array` Basic Array defining functions ------------------------------ .. method:: ones(shape, \*, dtype=float) .. param: shape Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) .. param: dtype Type of values in the array Return a new array of the given shape with all elements set to 1. .. method:: zeros .. param: shape Shape of the array, either an integer (for a 1-D array) or a tuple of 2 integers (for a 2-D array) .. param: dtype Type of values in the array Return a new array of the given shape with all elements set to 0. .. method:: eye(size, \*, dtype=float) Return a new square array of size, with the diagonal elements set to 1 and the other elements set to 0. .. method:: linspace(start, stop, \*, dtype=float, num=50, endpoint=True) .. param: start First value in the array .. param: stop Final value in the array .. param int: num Count of values in the array .. param: dtype Type of values in the array .. param bool: endpoint Whether the ``stop`` value is included. Note that even when endpoint=True, the exact ``stop`` value may not be included due to the inaccuracy of floating point arithmetic. Return a new 1-D array with ``num`` elements ranging from ``start`` to ``stop`` linearly. :mod:`ulab.vector` --- Element-by-element functions =================================================== .. module:: ulab.vector These functions can operate on numbers, 1-D arrays, or 2-D arrays by applying the function to every element in the array. This is typically much more efficient than expressing the same operation as a Python loop. .. method:: acos Computes the inverse cosine function .. method:: acosh Computes the inverse hyperbolic cosine function .. method:: asin Computes the inverse sine function .. method:: asinh Computes the inverse hyperbolic sine function .. method:: around(a, \*, decimals) Returns a new float array in which each element is rounded to ``decimals`` places. .. method:: atan Computes the inverse tangent function; the return values are in the range [-pi/2,pi/2]. .. method:: atan2(y,x) Computes the inverse tangent function of y/x; the return values are in the range [-pi, pi]. .. method:: atanh Computes the inverse hyperbolic tangent function .. method:: ceil Rounds numbers up to the next whole number .. method:: cos Computes the cosine function .. method:: erf Computes the error function, which has applications in statistics .. method:: erfc Computes the complementary error function, which has applications in statistics .. method:: exp Computes the exponent function. .. method:: expm1 Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the `exp` function. .. method:: floor Rounds numbers up to the next whole number .. method:: gamma Computes the gamma function .. method:: lgamma Computes the natural log of the gamma function .. method:: log Computes the natural log .. method:: log10 Computes the log base 10 .. method:: log2 Computes the log base 2 .. method:: sin Computes the sine .. method:: sinh Computes the hyperbolic sine .. method:: sqrt Computes the square root .. method:: tan Computes the tangent .. method:: tanh Computes the hyperbolic tangent :mod:`ulab.linalg` - Linear algebra functions ============================================= .. module:: ulab.linalg .. method:: cholesky(A) :param ~ulab.array A: a positive definite, symmetric square matrix :return ~ulab.array L: a square root matrix in the lower triangular form :raises ValueError: If the input does not fulfill the necessary conditions The returned matrix satisfies the equation m=LL* .. method:: det :param: m, a square matrix :return float: The determinant of the matrix Computes the eigenvalues and eigenvectors of a square matrix .. method:: dot(m1, m2) :param ~ulab.array m1: a matrix :param ~ulab.array m2: a matrix Computes the matrix product of two matrices **WARNING:** Unlike ``numpy``, this function cannot be used to compute the dot product of two vectors .. method:: eig(m) :param m: a square matrix :return tuple (eigenvectors, eigenvalues): Computes the eigenvalues and eigenvectors of a square matrix .. method:: inv(m) :param ~ulab.array m: a square matrix :return: The inverse of the matrix, if it exists :raises ValueError: if the matrix is not invertible Computes the inverse of a square matrix .. method:: size(array) Return the total number of elements in the array, as an integer. :mod:`ulab.filter` --- Filtering functions ========================================== .. module:: ulab.filter .. method:: convolve(r, c=None) :param ulab.array a: :param ulab.array v: Returns the discrete, linear convolution of two one-dimensional sequences. The result is always an array of float. Only the ``full`` mode is supported, and the ``mode`` named parameter of numpy is not accepted. Note that all other modes can be had by slicing a ``full`` result. Convolution filters can implement high pass, low pass, band pass, etc., filtering operations. Convolution filters are typically constructed ahead of time. This can be done using desktop python with scipy, or on web pages such as https://fiiir.com/ Convolution is most time-efficient when both inputs are of float type. :mod:`ulab.fft` --- Frequency-domain functions ============================================== .. module:: ulab.fft .. method:: fft(r, c=None) :param ulab.array r: A 1-dimension array of values whose size is a power of 2 :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value :return tuple (r, c): The real and complex parts of the FFT Perform a Fast Fourier Transform from the time domain into the frequency domain See also ~ulab.extras.spectrum, which computes the magnitude of the fft, rather than separately returning its real and imaginary parts. .. method:: ifft(r, c=None) :param ulab.array r: A 1-dimension array of values whose size is a power of 2 :param ulab.array c: An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value :return tuple (r, c): The real and complex parts of the inverse FFT Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain :mod:`ulab.numerical` --- Numerical and Statistical functions ============================================================= .. module:: ulab.numerical Most of these functions take an "axis" argument, which indicates whether to operate over the flattened array (None), rows (0), or columns (1). .. method:: argmax(array, \*, axis=None) Return the index of the maximum element of the 1D array, as an array with 1 element .. method:: argmin(array, \*, axis=None) Return the index of the minimum element of the 1D array, as an array with 1 element .. method:: argsort(array, \*, axis=None) Returns an array which gives indices into the input array from least to greatest. .. method:: diff(array, \*, axis=1) Return the numerical derivative of successive elements of the array, as an array. axis=None is not supported. .. method:: flip(array, \*, axis=None) Returns a new array that reverses the order of the elements along the given axis, or along all axes if axis is None. .. method:: max(array, \*, axis=None) Return the maximum element of the 1D array, as an array with 1 element .. method:: mean(array, \*, axis=None) Return the mean element of the 1D array, as a number if axis is None, otherwise as an array. .. method:: min(array, \*, axis=None) Return the minimum element of the 1D array, as an array with 1 element .. method:: roll(array, distance, \*, axis=None) Shift the content of a vector by the positions given as the second argument. If the ``axis`` keyword is supplied, the shift is applied to the given axis. The array is modified in place. .. method:: std(array, \*, axis=None) Return the standard deviation of the array, as a number if axis is None, otherwise as an array. .. method:: sum(array, \*, axis=None) Return the sum of the array, as a number if axis is None, otherwise as an array. .. method:: sort(array, \*, axis=0) Sort the array along the given axis, or along all axes if axis is None. The array is modified in place. :mod:`ulab.poly` --- Polynomial functions ========================================= .. module:: ulab.poly .. method:: polyfit([x, ] y, degree) Return a polynomial of given degree that approximates the function f(x)=y. If x is not supplied, it is the range(len(y)). .. method:: polyval(p, x) Evaluate the polynomial p at the points x. x must be an array. :mod:`ulab.extras` --- Additional functions not in numpy ======================================================== .. method:: spectrum(r): :param ulab.array 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``.