# ulab — 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

ulab.__version__

The closest corresponding version of micropython-ulab

## ulab.array – 1- and 2- dimensional array¶

class ulab.array(values, *, dtype=float)
Parameters: values (sequence) – Sequence giving the initial content of the array. 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

The size of the array, a tuple of length 1 or 2

size

The number of elements in the array

itemsize

The number of elements in the array

flatten(*, order='C')
Parameters: 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.

sort(*, axis=1)
Parameters: axis – Whether to sort elements within rows (0), columns (1), or elements (None)
transpose()

Swap the rows and columns of a 2-dimensional array

__add__()

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.

__sub__()

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.

__mul__()

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.

__div__()

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.

__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.

__getitem__()

Retrieve an element of the array.

__setitem__()

Set an element of the array.

## Array type codes¶

ulab.int8

Type code for signed integers in the range -128 .. 127 inclusive, like the ‘b’ typecode of array.array

ulab.int16

Type code for signed integers in the range -32768 .. 32767 inclusive, like the ‘h’ typecode of array.array

ulab.float

Type code for floating point values, like the ‘f’ typecode of array.array

ulab.uint8

Type code for unsigned integers in the range 0 .. 255 inclusive, like the ‘H’ typecode of array.array

ulab.uint16

Type code for unsigned integers in the range 0 .. 65535 inclusive, like the ‘h’ typecode of array.array

## Basic Array defining functions¶

ulab.ones(shape, *, dtype=float)

Return a new array of the given shape with all elements set to 1.

ulab.zeros()

Return a new array of the given shape with all elements set to 0.

ulab.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.

ulab.linspace(start, stop, *, dtype=float, num=50, endpoint=True)

Return a new 1-D array with num elements ranging from start to stop linearly.

# ulab.vector — 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.

ulab.vector.acos()

Computes the inverse cosine function

ulab.vector.acosh()

Computes the inverse hyperbolic cosine function

ulab.vector.asin()

Computes the inverse sine function

ulab.vector.asinh()

Computes the inverse hyperbolic sine function

ulab.vector.around(a, *, decimals)

Returns a new float array in which each element is rounded to decimals places.

ulab.vector.atan()

Computes the inverse tangent function; the return values are in the range [-pi/2,pi/2].

ulab.vector.atan2(y, x)

Computes the inverse tangent function of y/x; the return values are in the range [-pi, pi].

ulab.vector.atanh()

Computes the inverse hyperbolic tangent function

ulab.vector.ceil()

Rounds numbers up to the next whole number

ulab.vector.cos()

Computes the cosine function

ulab.vector.erf()

Computes the error function, which has applications in statistics

ulab.vector.erfc()

Computes the complementary error function, which has applications in statistics

ulab.vector.exp()

Computes the exponent function.

ulab.vector.expm1()

Computes $e^x-1$. In certain applications, using this function preserves numeric accuracy better than the exp function.

ulab.vector.floor()

Rounds numbers up to the next whole number

ulab.vector.gamma()

Computes the gamma function

ulab.vector.lgamma()

Computes the natural log of the gamma function

ulab.vector.log()

Computes the natural log

ulab.vector.log10()

Computes the log base 10

ulab.vector.log2()

Computes the log base 2

ulab.vector.sin()

Computes the sine

ulab.vector.sinh()

Computes the hyperbolic sine

ulab.vector.sqrt()

Computes the square root

ulab.vector.tan()

Computes the tangent

ulab.vector.tanh()

Computes the hyperbolic tangent

# ulab.linalg - Linear algebra functions¶

ulab.linalg.cholesky(A)
Parameters: Return ~ulab.array L: A (array) – a positive definite, symmetric square matrix a square root matrix in the lower triangular form ValueError – If the input does not fulfill the necessary conditions

The returned matrix satisfies the equation m=LL*

ulab.linalg.det()
Param: m, a square matrix The determinant of the matrix

Computes the eigenvalues and eigenvectors of a square matrix

ulab.linalg.dot(m1, m2)
Parameters: m1 (array) – a matrix m2 (array) – 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

ulab.linalg.eig(m)
Parameters: m – a square matrix

Computes the eigenvalues and eigenvectors of a square matrix

ulab.linalg.inv(m)
Parameters: m (array) – a square matrix The inverse of the matrix, if it exists ValueError – if the matrix is not invertible

Computes the inverse of a square matrix

ulab.linalg.size(array)

Return the total number of elements in the array, as an integer.

ulab.linalg.trace(m)
Parameters: m – a square matrix

Compute the trace of the matrix, the sum of its diagonal elements.

# ulab.filter — Filtering functions¶

ulab.filter.convolve(r, c=None)
Parameters: a (ulab.array) – v (ulab.array) –

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.

# ulab.fft — Frequency-domain functions¶

ulab.fft.fft(r, c=None)
Parameters: Return tuple (r, c): r (ulab.array) – A 1-dimension array of values whose size is a power of 2 c (ulab.array) – An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value 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.
ulab.fft.ifft(r, c=None)
Parameters: Return tuple (r, c): r (ulab.array) – A 1-dimension array of values whose size is a power of 2 c (ulab.array) – An optional 1-dimension array of values whose size is a power of 2, giving the complex part of the value The real and complex parts of the inverse FFT

Perform an Inverse Fast Fourier Transform from the frequeny domain into the time domain

# ulab.numerical — 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).

ulab.numerical.argmax(array, *, axis=None)

Return the index of the maximum element of the 1D array

ulab.numerical.argmin(array, *, axis=None)

Return the index of the minimum element of the 1D array

ulab.numerical.argsort(array, *, axis=None)

Returns an array which gives indices into the input array from least to greatest.

ulab.numerical.diff(array, *, axis=1)

Return the numerical derivative of successive elements of the array, as an array. axis=None is not supported.

ulab.numerical.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.

ulab.numerical.max(array, *, axis=None)

Return the maximum element of the 1D array

ulab.numerical.mean(array, *, axis=None)

Return the mean element of the 1D array, as a number if axis is None, otherwise as an array.

ulab.numerical.min(array, *, axis=None)

Return the minimum element of the 1D array

ulab.numerical.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.

ulab.numerical.std(array, *, axis=None)

Return the standard deviation of the array, as a number if axis is None, otherwise as an array.

ulab.numerical.sum(array, *, axis=None)

Return the sum of the array, as a number if axis is None, otherwise as an array.

ulab.numerical.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.

# ulab.poly — Polynomial functions¶

ulab.poly.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)).

ulab.poly.polyval(p, x)

Evaluate the polynomial p at the points x. x must be an array.

# ulab.extras — Additional functions not in numpy¶

spectrum(r):
Parameters: r (ulab.array) – 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.