Merge pull request #3187 from jepler/ulab-restructure-document

Upgrade ulab

10 files changed, 0 insertions, 568 deletions

diff --git a/shared-bindings/ulab/__init__.pyi b/shared-bindings/ulab/__init__.pyi
deleted file mode 100644
index 03bfe3610..000000000
--- a/shared-bindings/ulab/__init__.pyi
+++ /dev/null
@@ -1,169 +0,0 @@
-"""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"""
-
-
-class array:
-    """1- and 2- dimensional array"""
-    def __init__(self, values, *, dtype=float) -> None:
-        """: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."""
-        ...
-
-    shape: tuple = ...
-    """The size of the array, a tuple of length 1 or 2"""
-
-    size: int = ...
-    """The number of elements in the array"""
-
-    itemsize: int = ...
-    """The number of elements in the array"""
-
-    def flatten(self, *, 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."""
-        ...
-
-    def sort(self, *, axis=1):
-        """:param axis: Whether to sort elements within rows (0), columns (1), or elements (None)"""
-        ...
-
-    def transpose(self):
-        """Swap the rows and columns of a 2-dimensional array"""
-        ...
-
-    def  __add__(self):
-        """Adds corresponding elements of the two arrays, or adds a number to all
-           elements of the array.  If both arguments are arrays, their sizes must match."""
-        ...
-
-    def  __sub__(self):
-        """Subtracts corresponding elements of the two arrays, or adds a number to all
-           elements of the array.  If both arguments are arrays, their sizes must match."""
-        ...
-
-    def  __mul__(self):
-        """Multiplies corresponding elements of the two arrays, or multiplies
-           all elements of the array by a number.  If both arguments are arrays,
-           their sizes must match."""
-        ...
-
-    def __div__(self):
-        """Multiplies corresponding elements of the two arrays, or divides
-           all elements of the array by a number.  If both arguments are arrays,
-           their sizes must match."""
-        ...
-
-    def __pow__():
-        """Computes the power (x**y) of corresponding elements of the the two arrays,
-           or one number and one array.  If both arguments are arrays, their sizes
-           must match."""
-        ...
-
-    def __getitem__():
-        """Retrieve an element of the array."""
-        ...
-
-    def __setitem__():
-        """Set an element of the array."""
-        ...
-
-int8 = ...
-"""Type code for signed integers in the range -128 .. 127 inclusive, like the 'b' typecode of `array.array`"""
-
-int16 = ...
-"""Type code for signed integers in the range -32768 .. 32767 inclusive, like the 'h' typecode of `array.array`"""
-
-float = ...
-"""Type code for floating point values, like the 'f' typecode of `array.array`"""
-
-uint8 = ...
-"""Type code for unsigned integers in the range 0 .. 255 inclusive, like the 'H' typecode of `array.array`"""
-
-uint16 = ...
-"""Type code for unsigned integers in the range 0 .. 65535 inclusive, like the 'h' typecode of `array.array`"""
-
-def 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."""
-    ...
-
-def zeros(shape, *, dtype):
-    """
-    .. 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."""
-    ...
-
-
-def 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."""
-    ...
-
-def 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."""
-    ...
diff --git a/shared-bindings/ulab/approx/__init__.pyi b/shared-bindings/ulab/approx/__init__.pyi
deleted file mode 100644
index 7e012690f..000000000
--- a/shared-bindings/ulab/approx/__init__.pyi
+++ /dev/null
@@ -1,51 +0,0 @@
-"""Numerical approximation methods"""
-
-def bisect(fun, a, b, *, xtol=2.4e-7, maxiter=100) -> float:
-    """
-    :param callable f: The function to bisect
-    :param float a: The left side of the interval
-    :param float b: The right side of the interval
-    :param float xtol: The tolerance value
-    :param float maxiter: The maximum number of iterations to perform
-
-    Find a solution (zero) of the function ``f(x)`` on the interval
-    (``a``..``b``) using the bisection method.  The result is accurate to within
-    ``xtol`` unless more than ``maxiter`` steps are required."""
-    ...
-
-def newton(fun, x0, *, xtol=2.4e-7, rtol=0.0, maxiter=50) -> float:
-    """
-    :param callable f: The function to bisect
-    :param float x0: The initial x value
-    :param float xtol: The absolute tolerance value
-    :param float rtol: The relative tolerance value
-    :param float maxiter: The maximum number of iterations to perform
-
-    Find a solution (zero) of the function ``f(x)`` using Newton's Method.
-    The result is accurate to within ``xtol * rtol * |f(x)|`` unless more than
-    ``maxiter`` steps are requried."""
-    ...
-
-def fmin(fun, x0, *, xatol=2.4e-7, fatol=2.4e-7, maxiter=200) -> float:
-    """
-    :param callable f: The function to bisect
-    :param float x0: The initial x value
-    :param float xatol: The absolute tolerance value
-    :param float fatol: The relative tolerance value
-
-    Find a minimum of the function ``f(x)`` using the downhill simplex method.
-    The located ``x`` is within ``fxtol`` of the actual minimum, and ``f(x)``
-    is within ``fatol`` of the actual minimum unless more than ``maxiter``
-    steps are requried."""
-    ...
-
-def interp(x: ulab.array, xp:ulab.array, fp:ulab.array, *, left=None, right=None) -> ulab.array:
-    """
-    :param ulab.array x: The x-coordinates at which to evaluate the interpolated values.
-    :param ulab.array xp: The x-coordinates of the data points, must be increasing
-    :param ulab.array fp: The y-coordinates of the data points, same length as xp
-    :param left: Value to return for ``x < xp[0]``, default is ``fp[0]``.
-    :param right: Value to return for ``x > xp[-1]``, default is ``fp[-1]``.
-
-    Returns the one-dimensional piecewise linear interpolant to a function with given discrete data points (xp, fp), evaluated at x."""
-    ...
diff --git a/shared-bindings/ulab/compare/__init__.pyi b/shared-bindings/ulab/compare/__init__.pyi
deleted file mode 100644
index 1606e43c2..000000000
--- a/shared-bindings/ulab/compare/__init__.pyi
+++ /dev/null
@@ -1,38 +0,0 @@
-"""Comparison functions"""
-
-def clip(x1, x2, x3):
-    """
-    Constrain the values from ``x1`` to be between ``x2`` and ``x3``.
-    ``x2`` is assumed to be less than or equal to ``x3``.
-
-    Arguments may be ulab arrays or numbers.  All array arguments
-    must be the same size.  If the inputs are all scalars, a 1-element
-    array is returned.
-
-    Shorthand for ``ulab.maximum(x2, ulab.minimum(x1, x3))``"""
-    ...
-
-def maximum(x1, x2):
-    """
-    Compute the element by element maximum of the arguments.
-
-    Arguments may be ulab arrays or numbers.  All array arguments
-    must be the same size.  If the inputs are both scalars, a number is
-    returned"""
-    ...
-
-def minimum(x1, x2):
-    """Compute the element by element minimum of the arguments.
-
-    Arguments may be ulab arrays or numbers.  All array arguments
-    must be the same size.  If the inputs are both scalars, a number is
-    returned"""
-    ...
-
-def equal(x1, x2):
-    """Return an array of bool which is true where x1[i] == x2[i] and false elsewhere"""
-    ...
-
-def not_equal(x1, x2):
-    """Return an array of bool which is false where x1[i] == x2[i] and true elsewhere"""
-    ...
diff --git a/shared-bindings/ulab/extras/__init__.pyi b/shared-bindings/ulab/extras/__init__.pyi
deleted file mode 100644
index 4da56a582..000000000
--- a/shared-bindings/ulab/extras/__init__.pyi
+++ /dev/null
@@ -1,10 +0,0 @@
-"""Additional functions not in numpy"""
-
-def 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``."""
-    ...
diff --git a/shared-bindings/ulab/fft/__init__.pyi b/shared-bindings/ulab/fft/__init__.pyi
deleted file mode 100644
index 401ecb644..000000000
--- a/shared-bindings/ulab/fft/__init__.pyi
+++ /dev/null
@@ -1,22 +0,0 @@
-"""Frequency-domain functions"""
-
-def 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."""
-    ...
-
-def 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"""
-    ...
diff --git a/shared-bindings/ulab/filter/__init__.pyi b/shared-bindings/ulab/filter/__init__.pyi
deleted file mode 100644
index 5e7202e06..000000000
--- a/shared-bindings/ulab/filter/__init__.pyi
+++ /dev/null
@@ -1,36 +0,0 @@
-"""Filtering functions"""
-
-def 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."""
-    ...
-
-def sosfilt(sos : ulab.array, x : ulab.array, *, xi : Optional[ulab.array] = None) -> Union[ulab.array, Tuple[ulab.array, ulab.array]]:
-    """
-    :param ulab.array sos: Array of second-order filter coefficients, must have shape (n_sections, 6). Each row corresponds to a second-order section, with the first three columns providing the numerator coefficients and the last three providing the denominator coefficients.
-    :param ulab.array x: The data to be filtered
-    :param ulab.array zi: Optional initial conditions for the filter
-
-    :return: If ``xi`` is not specified, the filter result alone is returned.  If ``xi`` is specified, the return value is a 2-tuple of the filter result and the final filter conditions.
-
-    Filter data along one dimension using cascaded second-order sections.
-
-    Filter a data sequence, x, using a digital IIR filter defined by sos.
-
-    The filter function is implemented as a series of second-order filters with direct-form II transposed structure. It is designed to minimize numerical precision errors for high-order filters.
-
-    Filter coefficients can be generated by using scipy's filter generators such as ``signal.ellip(..., output='sos')``."""
-    ...
diff --git a/shared-bindings/ulab/linalg/__init__.pyi b/shared-bindings/ulab/linalg/__init__.pyi
deleted file mode 100644
index d16e61807..000000000
--- a/shared-bindings/ulab/linalg/__init__.pyi
+++ /dev/null
@@ -1,57 +0,0 @@
-"""Linear algebra functions"""
-
-
-def 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*"""
-    ...
-
-def det():
-    """
-    :param: m, a square matrix
-    :return float: The determinant of the matrix
-
-    Computes the eigenvalues and eigenvectors of a square matrix"""
-    ...
-
-def 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"""
-    ...
-
-def eig(m):
-    """
-    :param m: a square matrix
-    :return tuple (eigenvectors, eigenvalues):
-
-    Computes the eigenvalues and eigenvectors of a square matrix"""
-    ...
-
-def 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"""
-    ...
-
-def size(array):
-    """Return the total number of elements in the array, as an integer."""
-    ...
-
-def trace(m):
-    """
-    :param m: a square matrix
-
-    Compute the trace of the matrix, the sum of its diagonal elements."""
-    ...
diff --git a/shared-bindings/ulab/numerical/__init__.pyi b/shared-bindings/ulab/numerical/__init__.pyi
deleted file mode 100644
index 759678921..000000000
--- a/shared-bindings/ulab/numerical/__init__.pyi
+++ /dev/null
@@ -1,57 +0,0 @@
-"""Numerical and Statistical functions
-
-Most of these functions take an "axis" argument, which indicates whether to
-operate over the flattened array (None), rows (0), or columns (1)."""
-
-def argmax(array, *, axis=None):
-    """Return the index of the maximum element of the 1D array"""
-    ...
-
-def argmin(array, *, axis=None):
-    """Return the index of the minimum element of the 1D array"""
-    ...
-
-def argsort(array, *, axis=None):
-    """Returns an array which gives indices into the input array from least to greatest."""
-    ...
-
-def diff(array, *, axis=1):
-    """Return the numerical derivative of successive elements of the array, as
-       an array.  axis=None is not supported."""
-    ...
-
-def 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."""
-    ...
-
-def max(array, *, axis=None):
-    """Return the maximum element of the 1D array"""
-    ...
-
-def mean(array, *, axis=None):
-    """Return the mean element of the 1D array, as a number if axis is None, otherwise as an array."""
-    ...
-
-def min(array, *, axis=None):
-    """Return the minimum element of the 1D array"""
-    ...
-
-def 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."""
-    ...
-
-def std(array, *, axis=None):
-    """Return the standard deviation of the array, as a number if axis is None, otherwise as an array."""
-    ...
-
-def sum(array, *, axis=None):
-    """Return the sum of the array, as a number if axis is None, otherwise as an array."""
-    ...
-
-def 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."""
-    ...
diff --git a/shared-bindings/ulab/poly/__init__.pyi b/shared-bindings/ulab/poly/__init__.pyi
deleted file mode 100644
index d051bbded..000000000
--- a/shared-bindings/ulab/poly/__init__.pyi
+++ /dev/null
@@ -1,10 +0,0 @@
-"""Polynomial functions"""
-
-def 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))."""
-    ...
-
-def polyval(p, x):
-    """Evaluate the polynomial p at the points x.  x must be an array."""
-    ...
diff --git a/shared-bindings/ulab/vector/__init__.pyi b/shared-bindings/ulab/vector/__init__.pyi
deleted file mode 100644
index bf57e419c..000000000
--- a/shared-bindings/ulab/vector/__init__.pyi
+++ /dev/null
@@ -1,118 +0,0 @@
-"""Element-by-element functions
-
-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."""
-
-def acos():
-    """Computes the inverse cosine function"""
-    ...
-
-def acosh():
-    """Computes the inverse hyperbolic cosine function"""
-    ...
-
-def asin():
-    """Computes the inverse sine function"""
-    ...
-
-def asinh():
-    """Computes the inverse hyperbolic sine function"""
-    ...
-
-def around(a, *, decimals):
-    """Returns a new float array in which each element is rounded to
-       ``decimals`` places."""
-    ...
-
-def atan():
-    """Computes the inverse tangent function; the return values are in the
-       range [-pi/2,pi/2]."""
-    ...
-
-def atan2(y,x):
-    """Computes the inverse tangent function of y/x; the return values are in
-       the range [-pi, pi]."""
-    ...
-
-def atanh():
-    """Computes the inverse hyperbolic tangent function"""
-    ...
-
-def ceil():
-    """Rounds numbers up to the next whole number"""
-    ...
-
-def cos():
-    """Computes the cosine function"""
-    ...
-
-def erf():
-    """Computes the error function, which has applications in statistics"""
-    ...
-
-def erfc():
-    """Computes the complementary error function, which has applications in statistics"""
-    ...
-
-def exp():
-    """Computes the exponent function."""
-    ...
-
-def expm1():
-    """Computes $e^x-1$.  In certain applications, using this function preserves numeric accuracy better than the `exp` function."""
-    ...
-
-def floor():
-    """Rounds numbers up to the next whole number"""
-    ...
-
-def gamma():
-    """Computes the gamma function"""
-    ...
-
-def lgamma():
-    """Computes the natural log of the gamma function"""
-    ...
-
-def log():
-    """Computes the natural log"""
-    ...
-
-def log10():
-    """Computes the log base 10"""
-    ...
-
-def log2():
-    """Computes the log base 2"""
-    ...
-
-def sin():
-    """Computes the sine"""
-    ...
-
-def sinh():
-    """Computes the hyperbolic sine"""
-    ...
-
-def sqrt():
-    """Computes the square root"""
-    ...
-
-def tan():
-    """Computes the tangent"""
-    ...
-
-def tanh():
-    """Computes the hyperbolic tangent"""
-    ...
-
-def vectorize(f, *, otypes=None):
-    """
-    :param callable f: The function to wrap
-    :param otypes: List of array types that may be returned by the function.  None is intepreted to mean the return value is float.
-
-    Wrap a Python function ``f`` so that it can be applied to arrays.
-
-    The callable must return only values of the types specified by otypes, or the result is undefined."""
-    ...