ulab: Incorporate it

1 files changed, 459 insertions, 0 deletions

diff --git a/shared-bindings/ulab/__init__.rst b/shared-bindings/ulab/__init__.rst
new file mode 100644
index 000000000..329d28ca2
--- /dev/null
+++ b/shared-bindings/ulab/__init__.rst
@@ -0,0 +1,459 @@
+
+: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 a 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).
+
+  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
+------------------------------
+See also `ulab.linalg.eye` and `ulab.numerical.linspace` for other useful
+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.
+
+
+: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:: atan
+
+   Computes the inverse tangent function
+
+.. 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:: 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, eigenvaues):
+
+   Computes the eigenvalues and eigenvectors of a square matrix
+
+
+.. method:: eye(size, \*, dtype=float)
+
+   :param int: size - The number of rows and colums in the matrix
+
+   Returns a square matrix with all the diagonal elements set to 1 and all
+   other elements set to 0
+
+.. 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
+
+.. 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
+
+.. 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.
+
+: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:: 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.
+
+.. 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.