jepler/circuitpython-ulab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

updated readme

Browse source
This commit is contained in:
Zoltán Vörös 2020-10-17 09:14:22 +02:00
parent 511bb5f6c9
commit e947baddd7
1 changed files with 33 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
README.md
View file

@ -1,9 +1,9 @@
# ulab # ulab
`ulab` is a `numpy`-like array manipulation library for `micropython` and `CircuitPython`. `ulab` is a `numpy`-like array manipulation library for `micropython` and `CircuitPython`.
The module is written in C, defines compact containers for numerical The module is written in C, defines compact containers for numerical data of one to four
data, and is fast. The library is a software-only standard `micropython` user module, dimensions, and is fast. The library is a software-only standard `micropython` user module,
i.e., it has no hardware dependencies, and can be compiled for any platform. i.e., it has no hardware dependencies, and can be compiled for any platform.
The `float` implementation of `micropython` (`float`, or `double`) is automatically detected. The `float` implementation of `micropython` (`float`, or `double`) is automatically detected.
# Supported functions # Supported functions
@ -11,22 +11,24 @@ The `float` implementation of `micropython` (`float`, or `double`) is automatica
## ndarray ## ndarray
`ulab` implements `numpy`'s `ndarray` with the `==`, `!=`, `<`, `<=`, `>`, `>=`, `+`, `-`, `/`, `*`, and `**` binary `ulab` implements `numpy`'s `ndarray` with the `==`, `!=`, `<`, `<=`, `>`, `>=`, `+`, `-`, `/`, `*`, `**`,
operators, and the `len`, `~`, `-`, `+`, `abs` unary operators that operate element-wise. Type-aware `ndarray`s can `+=`, `-=`, `*=`, `/=`, `**=` binary operators, and the `len`, `~`, `-`, `+`, `abs` unary operators that
be initialised from any `micropython` iterable, lists of iterables, or by means of the `arange`, `eye`, `linspace`, operate element-wise. Type-aware `ndarray`s can be initialised from any `micropython` iterable, lists of
`ones`, or `zeros` functions. iterables, or by means of the `arange`, `concatenate`, `eye`, `full`, `linspace`, `logspace`, `ones`, or
`zeros` functions.
`ndarray`s can be iterated on, and have a number of their own methods, such as `shape`, `reshape`, `transpose`, `size`, and `itemsize`. `ndarray`s can be iterated on, and have a number of their own methods, such as `flatten`, `shape`,
`reshape`, `strides`, `transpose`, `size`, `tobytes`, and `itemsize`.
## Modules ## Customising the firmware
In addition to the `ndarray`'s operators and methods, seven modules define a great number of functions that can In addition to the `ndarray`'s operators and methods, seven modules define a great number of functions that can
take `ndarray`s or `micropython` iterables as their arguments. If flash space is a concern, unnecessary sub-modules take `ndarray`s or `micropython` iterables as their arguments. If flash space is a concern, unnecessary sub-modules
can be excluded from the compiled firmware with a pre-processor switch. or even individual functions can be excluded from the compiled firmware with pre-processor switches.
### approx ### approx
The `approx` sub-module contains the implementation of the `interp`, and `trapz` functions of `numpy`, and `newton`, `bisect`, The `approx` sub-module contains the implementation of the `interp`, and `trapz` functions of `numpy`, and `newton`, `bisect`,
and `fmin` from `scipy`. and `fmin` from `scipy`.
### compare ### compare
@ -35,7 +37,7 @@ The `compare` sub-module contains the implementation of the `equal`, `not_equal`
### fft ### fft
The `fft` sub-module implements the fast Fourier transform, and its inverse for one-dimensional `ndarray`s, The `fft` sub-module implements the fast Fourier transform, and its inverse for one-dimensional `ndarray`s,
as well as the `spectrogram` function from `scipy`. as well as the `spectrogram` function from `scipy`.
### filter ### filter
@ -45,13 +47,13 @@ as well as the cascaded second-order sections filter, `sosfilt` from `scipy`.
### linalg ### linalg
The `linalg` sub-module implements functions for matrix inversion, dot product, and the calculation of the The `linalg` sub-module implements functions for matrix inversion, dot product, and the calculation of the
determinant, eigenvalues, eigenvectors, Cholesky decomposition, and trace. determinant, eigenvalues, eigenvectors, Cholesky decomposition, and trace.
### numerical ### numerical
The `numerical` sub-module defines the `roll`, `flip`, `diff`, `sort` and `argsort` functions for `ndarray`s, and, The `numerical` sub-module defines the `cross`, `diff`, `flip`, `roll`, `sort` and `argsort` functions for `ndarray`s, and,
in addition, the `min`, `max`, `argmin`, `argmax`, `sum`, `mean`, `std` functions that work with `ndarray`s, as in addition, the `min`, `max`, `argmin`, `argmax`, `sum`, `mean`, `std` functions that work with `ndarray`s, as
well as generic one-dimensional iterables. well as generic one-dimensional iterables.
### poly ### poly
@ -60,13 +62,13 @@ The `poly` sub-module defines the `polyval`, and `polyfit` functions from `numpy
### vector ### vector
The `vector` sub-module implements all functions of the `math` package (e.g., `acos`, `acosh`, ..., `tan`, `tanh`) The `vector` sub-module implements all functions of `micropython`'s `math` package (e.g., `acos`, `acosh`, ..., `tan`, `tanh`),
of `micropython` for `ndarray`s and iterables. In addition, it also provided tools for vectorising generic, and the `degrees` and `radians` for `ndarray`s and iterables. In addition, it also provided tools for vectorising generic,
user-defined `python` functions. user-defined `python` functions.
### user ### user
The `user` sub-module is meant as a user-extendable module, and contains a dummy function only. The `user` sub-module is meant as a user-extendable module, and contains a dummy function only.
# Finding help # Finding help
@ -78,25 +80,26 @@ A number of practical examples are listed in the excellent
# Firmware # Firmware
Compiled firmware for many hardware platforms can be downloaded from Roberto Colistete's Compiled firmware for many hardware platforms can be downloaded from Roberto Colistete's
gitlab repository: for the [pyboad](https://gitlab.com/rcolistete/micropython-samples/-/tree/master/Pyboard/Firmware/), and gitlab repository: for the [pyboard](https://gitlab.com/rcolistete/micropython-samples/-/tree/master/Pyboard/Firmware/), and
for [ESP8266](https://gitlab.com/rcolistete/micropython-samples/-/tree/master/ESP8266/Firmware). for [ESP8266](https://gitlab.com/rcolistete/micropython-samples/-/tree/master/ESP8266/Firmware).
Since a number of features can be set in the firmware (threading, support for SD card, LEDs, user switch etc.), and it is Since a number of features can be set in the firmware (threading, support for SD card, LEDs, user switch etc.), and it is
impossible to create something that suits everyone, these releases should only be used for impossible to create something that suits everyone, these releases should only be used for
quick testing of `ulab`. Otherwise, compilation from the source is required with quick testing of `ulab`. Otherwise, compilation from the source is required with
the appropriate settings, which are usually defined in the `mpconfigboard.h` file of the port the appropriate settings, which are usually defined in the `mpconfigboard.h` file of the port
in question. in question.
`ulab` is also included in the following compiled `micropython` variants and derivatives: `ulab` is also included in the following compiled `micropython` variants and derivatives:
1. `CircuitPython` for SAMD51 and nRF microcontrollers https://github.com/adafruit/circuitpython 1. `CircuitPython` for SAMD51 and nRF microcontrollers https://github.com/adafruit/circuitpython
1. `MicroPython for K210` https://github.com/loboris/MicroPython_K210_LoBo 1. `MicroPython for K210` https://github.com/loboris/MicroPython_K210_LoBo
1. `MaixPy` https://github.com/sipeed/MaixPy 1. `MaixPy` https://github.com/sipeed/MaixPy
1. `OpenMV` https://github.com/openmv/openmv 1. `OpenMV` https://github.com/openmv/openmv
1. `pycom` https://pycom.io/
## Compiling ## Compiling
If you want to try the latest version of `ulab` on `micropython` or one of its forks, the firmware can be compiled If you want to try the latest version of `ulab` on `micropython` or one of its forks, the firmware can be compiled
from the source by following these steps: from the source by following these steps:
First, you have to clone the `micropython` repository by running First, you have to clone the `micropython` repository by running
@ -104,7 +107,7 @@ First, you have to clone the `micropython` repository by running
``` ```
git clone https://github.com/micropython/micropython.git git clone https://github.com/micropython/micropython.git
``` ```
on the command line. This will create a new repository with the name `micropython`. Staying there, clone the `ulab` repository with on the command line. This will create a new repository with the name `micropython`. Staying there, clone the `ulab` repository with
``` ```
git clone https://github.com/v923z/micropython-ulab.git ulab git clone https://github.com/v923z/micropython-ulab.git ulab
@ -120,7 +123,7 @@ If this step was successful, you can try to run the `make` command in the port's
``` ```
make BOARD=PYBV11 USER_C_MODULES=../../../ulab all make BOARD=PYBV11 USER_C_MODULES=../../../ulab all
``` ```
which will prepare the firmware for pyboard.v.11. Similarly, which will prepare the firmware for pyboard.v.11. Similarly,
``` ```
make BOARD=PYBD_SF6 USER_C_MODULES=../../../ulab all make BOARD=PYBD_SF6 USER_C_MODULES=../../../ulab all
``` ```
@ -130,7 +133,7 @@ Provided that you managed to compile the firmware, you would upload that by runn
``` ```
dfu-util --alt 0 -D firmware.dfu dfu-util --alt 0 -D firmware.dfu
``` ```
or or
``` ```
python pydfu.py -u firmware.dfu python pydfu.py -u firmware.dfu
``` ```