# ML on MCU
[](https://pypi.org/project/mlonmcu)
[](https://mlonmcu.readthedocs.io/en/latest/?version=latest)
[](https://github.com/tum-ei-eda/mlonmcu/blob/main/LICENSE)
[](https://github.com/tum-ei-eda/mlonmcu/actions/workflows/cicd.yml)
[](https://github.com/tum-ei-eda/mlonmcu/actions/workflows/style.yml)
[](https://github.com/tum-ei-eda/mlonmcu/actions/workflows/demo.yml)
[](https://github.com/tum-ei-eda/mlonmcu/actions/workflows/bench.yml)
This project contains research code related to the deployment of inference or learning applications on tiny micro-controllers.
* Free software: Apache License, Version 2.0
* Python Package: [https://pypi.org/project/mlonmcu/](https://pypi.org/project/mlonmcu/)
* Documentation: [https://mlonmcu.readthedocs.io](https://mlonmcu.readthedocs.io) or [https://tum-ei-eda.github.io/mlonmcu/](https://tum-ei-eda.github.io/mlonmcu/)
## Features
- Highly configurable python package
- Automatic resolution and installation of dependencies
- Supporting a large combination of frameworks/backends/targets/features
- Build-in parallel processing of large number of benchmarks
- Isolated enironments (not interfering with other installations)
- Command Line and Python Development Interfaces
- Docker images to get started quickly
- Extensive documentation on usage and code details
- CI/CD integration and high PyTest coverage
## Getting started
### Prerequisites
#### Ubuntu/Debian
First, a set of APT packages needs to be installed:
```
# Python related
sudo apt install python3-pip python3-venv
# MLonMCU related
sudo apt install libboost-all-dev graphviz doxygen libtinfo-dev zlib1g-dev texinfo unzip device-tree-compiler tree g++
# Optional (depending on configuration)
sudo apt install ninja-build flex lsb-release libelf-dev
```
Also make sure that your default Python is at least v3.7. If the `python` command is not available in your shell or points Python v2.7 check out `python-is-python3`.
**Warning:** It seems like the ETISS tool fails to compile if if find a version of LLVM 11 on your system which does not include Clang 11. The best workaround for now is to (if possible) remove those tools from your system: `sudo apt remove llvm-11* clang-11*` (See issue #1)
Make sure to use a fresh virtual Python environment in the following steps.
##### Install Release from PyPI
**Warning:** As the PyPI package is not always up to date, it is currently recommented to use a self-build version of the package (as explained in the next section)
To use the PIP package, run the following: `pip install mlonmcu` (Add `--user` if you are not using a virtual environment)
#### Build Package manually
First, install all relevant dependencies:
```
python -m venv .venv # Feel free to choose a different directory or use a conda environment
# Run this whenever your have updated the repository
source .venv/bin/activate
# Environment-specific dependencies are installed later
**Warning:** It is recommended to have at least version 3.20 of CMake installed for full compatibility!
# Install ptional dependecies (only for development)
pip install -r requirements_dev.txt
pip install -r docs/requirements.txt
# Only if you want to use the provided python notebooks, as explained in ./ipynb/README.md
pip install -r ipynb/requirements.txt
```
Then you should be able to install the `mlonmcu` python package like this
```
# Optionally remove an older version first: pip uninstall mlonmcu
make install # Alternative: python setup.py install
```
#### Docker (Any other OS)
See [`./docker/README.md`](https://github.com/tum-ei-eda/mlonmcu/blob/main/docker/README.md) for more details.
This repository ships three different types of docker images based on Debian:
- A minimal one with preinstalled software dependencies and python packages
Feel free to use this one if you do not want to install anything (except Docker) on your main sytem to work with mlonmcu
- A medium one which already has the `mlonmcu` python package installed
Recommended and the easiest to use. (Especially when using `docker-compose` to mount shared directories etc.)
- A very large one with an already initialized and installed
Mainly used for triggering automated benchmarks without spending too much time on downloading/compiling heavy dependencies over and over again.
### Usage
Is is recommended to checkout the provided [Demo Jupyter Notebook](https://github.com/tum-ei-eda/mlonmcu/blob/main/ipynb/Demo.ipynb) as it contains a end-to-end example which should help to understand the main concepts and methodology of the tool. The following paragraphs can be seen as a TL;DL version of the information in that Demo notebook.
While some tools and features of this project work out of the box, some of them require setting up an environment where additional dependencies are installed. This can be achived by creating a MLonMCU environment as follows:
```bash
mlonmcu init
```
Make sure to point the `MLONMCU_HOME` environment variable to the location of the previously initialied environment. (Alternative: use the `default` environment or `--home` argument on the command line)
Next, generate a `requirements_addition.txt` file inside the environment directory using `mlonmcu setup -g` which now be installed by running `pip install -r $MLONMCU_HOME/requirements_addition.txt` inside the virtual Python environment.
To use the created environment in a python program, a `MlonMcuContext` needs to be created as follows:
```
import mlonmcu.context
with mlonmcu.context.MlonMcuContext() as context:
pass
```
## List of interesting MLonMCU forks
- MINRES TGC support: https://github.com/Minres/mlonmcu/tree/develop
## List of existing MLonMCU extensions/plugins
- ABC Example Plugin: coming soon!
- MINRES TGC Support: coming soon!
## Development
Make sure to first install the additonal set of development Python packages into your virtual environment:
```
pip install -r requirements_all.txt # Install packages for every component (instead of using mlonmcu setup -g)
pip install -r requirements_dev.txt # Building distributions and running tests
pip install -r docs/requirements.txt # For working with the documentation
```
Unit test and integration test are defined in the `tests/` directory and can be triggered using `make test` or `pytest tests/`
Coverage can be determined by running `make coverage`. The latest coverage report (HTML) for the default branch can also be found as an artifact of the CI/CD workflow.
Documentation is mainly generated automatically from doctrings (triggered via `make html`). It is also possible to include markdown files from the repo into the `.rst` files found in the [`docs/`](./docs/) directory. There is a GitHub workflow which publishes the documentation for the default branch to our [GitHub Pages](https://tum-ei-eda.github.io/mlonmcu).
Regarding coding style, it is recommended to run `black` before every commit. The default line length should be given in the `setup.cfg` file.
### Developers
- Rafael Stahl (TUM) [@rafzi]
- Wrote initial version of the MLonMCU project
- Philipp van Kempen (TUM) [@PhilippvK]
- Came up with MLonMCU Python package
## Publications
- **MLonMCU: TinyML Benchmarking with Fast Retargeting** ([https://dl.acm.org/doi/10.1145/3637543.3652878](https://dl.acm.org/doi/abs/10.1145/3615338.3618128))
*CODAI '23: Proceedings of the 2023 Workshop on Compilers, Deployment, and Tooling for Edge AI*
BibTeX
```bibtex
@inproceedings{10.1145/3615338.3618128,
author = {van Kempen, Philipp and Stahl, Rafael and Mueller-Gritschneder, Daniel and Schlichtmann, Ulf},
title = {MLonMCU: TinyML Benchmarking with Fast Retargeting},
year = {2024},
isbn = {9798400703379},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3615338.3618128},
doi = {10.1145/3615338.3618128},
abstract = {While there exist many ways to deploy machine learning models on microcontrollers, it is non-trivial to choose the optimal combination of frameworks and targets for a given application. Thus, automating the end-to-end benchmarking flow is of high relevance nowadays. A tool called MLonMCU is proposed in this paper and demonstrated by benchmarking the state-of-the-art TinyML frameworks TFLite for Microcontrollers and TVM effortlessly with a large number of configurations in a low amount of time.},
booktitle = {Proceedings of the 2023 Workshop on Compilers, Deployment, and Tooling for Edge AI},
pages = {32–36},
numpages = {5},
keywords = {TinyML, neural networks, microcontrollers},
location = {Hamburg, Germany},
series = {CODAI '23}
}
```
### Other
This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. However most of the templates was manually changed to be in Markdown instead of reStructuredText.
- **Cookiecutter:** https://github.com/audreyr/cookiecutter
- **`audreyr/cookiecutter-pypackage`:** https://github.com/audreyr/cookiecutter-pypackage
## Acknowledgment
<img src="./BMBF_gefoerdert_2017_en.jpg" alt="drawing" height="75" align="left" >
This research is partially funded by the German Federal Ministry of Education and Research (BMBF) within
the projects [Scale4Edge](https://www.edacentrum.de/scale4edge/) (grant number 16ME0127) and [MANNHEIM-FlexKI](https://www.edacentrum.de/projekte/MANNHEIM-FlexKI) (grant number 01IS22086L).
# History
## 0.1.0 (2021-11-12)
* First closed-source release.
Raw data
{
"_id": null,
"home_page": "https://github.com/tum-ei-eda/mlonmcu",
"name": "mlonmcu",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mlonmcu",
"author": "TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation",
"author_email": "philipp.van-kempen@tum.de",
"download_url": "https://files.pythonhosted.org/packages/ae/f7/a2c00dc9c61af3edefa597fb5faeb0c70dd894294009a0fec6da30549fca/mlonmcu-0.5.0.tar.gz",
"platform": null,
"description": "# ML on MCU\n\n[](https://pypi.org/project/mlonmcu)\n[](https://mlonmcu.readthedocs.io/en/latest/?version=latest)\n\n[](https://github.com/tum-ei-eda/mlonmcu/blob/main/LICENSE)\n\n[](https://github.com/tum-ei-eda/mlonmcu/actions/workflows/cicd.yml)\n[](https://github.com/tum-ei-eda/mlonmcu/actions/workflows/style.yml)\n[](https://github.com/tum-ei-eda/mlonmcu/actions/workflows/demo.yml)\n[](https://github.com/tum-ei-eda/mlonmcu/actions/workflows/bench.yml)\n\n\nThis project contains research code related to the deployment of inference or learning applications on tiny micro-controllers.\n\n\n* Free software: Apache License, Version 2.0\n* Python Package: [https://pypi.org/project/mlonmcu/](https://pypi.org/project/mlonmcu/)\n* Documentation: [https://mlonmcu.readthedocs.io](https://mlonmcu.readthedocs.io) or [https://tum-ei-eda.github.io/mlonmcu/](https://tum-ei-eda.github.io/mlonmcu/)\n\n\n## Features\n\n- Highly configurable python package\n- Automatic resolution and installation of dependencies\n- Supporting a large combination of frameworks/backends/targets/features\n- Build-in parallel processing of large number of benchmarks\n- Isolated enironments (not interfering with other installations)\n- Command Line and Python Development Interfaces\n- Docker images to get started quickly\n- Extensive documentation on usage and code details\n- CI/CD integration and high PyTest coverage\n\n## Getting started\n\n### Prerequisites\n\n#### Ubuntu/Debian\n\nFirst, a set of APT packages needs to be installed:\n\n```\n# Python related\nsudo apt install python3-pip python3-venv\n\n# MLonMCU related\nsudo apt install libboost-all-dev graphviz doxygen libtinfo-dev zlib1g-dev texinfo unzip device-tree-compiler tree g++\n\n# Optional (depending on configuration)\nsudo apt install ninja-build flex lsb-release libelf-dev\n```\n\nAlso make sure that your default Python is at least v3.7. If the `python` command is not available in your shell or points Python v2.7 check out `python-is-python3`.\n\n**Warning:** It seems like the ETISS tool fails to compile if if find a version of LLVM 11 on your system which does not include Clang 11. The best workaround for now is to (if possible) remove those tools from your system: `sudo apt remove llvm-11* clang-11*` (See issue #1)\n\nMake sure to use a fresh virtual Python environment in the following steps.\n\n##### Install Release from PyPI\n\n**Warning:** As the PyPI package is not always up to date, it is currently recommented to use a self-build version of the package (as explained in the next section)\n\nTo use the PIP package, run the following: `pip install mlonmcu` (Add `--user` if you are not using a virtual environment)\n\n\n#### Build Package manually\n\nFirst, install all relevant dependencies:\n\n```\npython -m venv .venv # Feel free to choose a different directory or use a conda environment\n\n# Run this whenever your have updated the repository\nsource .venv/bin/activate\n\n# Environment-specific dependencies are installed later\n\n**Warning:** It is recommended to have at least version 3.20 of CMake installed for full compatibility!\n\n# Install ptional dependecies (only for development)\npip install -r requirements_dev.txt\npip install -r docs/requirements.txt\n\n# Only if you want to use the provided python notebooks, as explained in ./ipynb/README.md\npip install -r ipynb/requirements.txt\n```\n\nThen you should be able to install the `mlonmcu` python package like this\n\n```\n# Optionally remove an older version first: pip uninstall mlonmcu\n\nmake install # Alternative: python setup.py install\n```\n\n#### Docker (Any other OS)\n\nSee [`./docker/README.md`](https://github.com/tum-ei-eda/mlonmcu/blob/main/docker/README.md) for more details.\n\nThis repository ships three different types of docker images based on Debian:\n\n- A minimal one with preinstalled software dependencies and python packages\n\n Feel free to use this one if you do not want to install anything (except Docker) on your main sytem to work with mlonmcu\n- A medium one which already has the `mlonmcu` python package installed\n\n Recommended and the easiest to use. (Especially when using `docker-compose` to mount shared directories etc.)\n\n- A very large one with an already initialized and installed\n\n Mainly used for triggering automated benchmarks without spending too much time on downloading/compiling heavy dependencies over and over again.\n\n### Usage\n\nIs is recommended to checkout the provided [Demo Jupyter Notebook](https://github.com/tum-ei-eda/mlonmcu/blob/main/ipynb/Demo.ipynb) as it contains a end-to-end example which should help to understand the main concepts and methodology of the tool. The following paragraphs can be seen as a TL;DL version of the information in that Demo notebook.\n\nWhile some tools and features of this project work out of the box, some of them require setting up an environment where additional dependencies are installed. This can be achived by creating a MLonMCU environment as follows:\n\n```bash\nmlonmcu init\n```\n\nMake sure to point the `MLONMCU_HOME` environment variable to the location of the previously initialied environment. (Alternative: use the `default` environment or `--home` argument on the command line)\n\nNext, generate a `requirements_addition.txt` file inside the environment directory using `mlonmcu setup -g` which now be installed by running `pip install -r $MLONMCU_HOME/requirements_addition.txt` inside the virtual Python environment.\n\n\nTo use the created environment in a python program, a `MlonMcuContext` needs to be created as follows:\n\n```\nimport mlonmcu.context\n\nwith mlonmcu.context.MlonMcuContext() as context:\n pass\n```\n\n## List of interesting MLonMCU forks\n\n- MINRES TGC support: https://github.com/Minres/mlonmcu/tree/develop\n\n## List of existing MLonMCU extensions/plugins\n\n- ABC Example Plugin: coming soon!\n- MINRES TGC Support: coming soon!\n\n## Development\n\nMake sure to first install the additonal set of development Python packages into your virtual environment:\n\n```\npip install -r requirements_all.txt # Install packages for every component (instead of using mlonmcu setup -g)\npip install -r requirements_dev.txt # Building distributions and running tests\npip install -r docs/requirements.txt # For working with the documentation\n```\n\nUnit test and integration test are defined in the `tests/` directory and can be triggered using `make test` or `pytest tests/`\n\nCoverage can be determined by running `make coverage`. The latest coverage report (HTML) for the default branch can also be found as an artifact of the CI/CD workflow.\n\nDocumentation is mainly generated automatically from doctrings (triggered via `make html`). It is also possible to include markdown files from the repo into the `.rst` files found in the [`docs/`](./docs/) directory. There is a GitHub workflow which publishes the documentation for the default branch to our [GitHub Pages](https://tum-ei-eda.github.io/mlonmcu).\n\nRegarding coding style, it is recommended to run `black` before every commit. The default line length should be given in the `setup.cfg` file.\n\n### Developers\n\n- Rafael Stahl (TUM) [@rafzi]\n\n - Wrote initial version of the MLonMCU project\n\n- Philipp van Kempen (TUM) [@PhilippvK]\n\n - Came up with MLonMCU Python package\n\n## Publications\n\n- **MLonMCU: TinyML Benchmarking with Fast Retargeting** ([https://dl.acm.org/doi/10.1145/3637543.3652878](https://dl.acm.org/doi/abs/10.1145/3615338.3618128))\n\n *CODAI '23: Proceedings of the 2023 Workshop on Compilers, Deployment, and Tooling for Edge AI*\n\n BibTeX\n\n ```bibtex\n @inproceedings{10.1145/3615338.3618128,\n author = {van Kempen, Philipp and Stahl, Rafael and Mueller-Gritschneder, Daniel and Schlichtmann, Ulf},\n title = {MLonMCU: TinyML Benchmarking with Fast Retargeting},\n year = {2024},\n isbn = {9798400703379},\n publisher = {Association for Computing Machinery},\n address = {New York, NY, USA},\n url = {https://doi.org/10.1145/3615338.3618128},\n doi = {10.1145/3615338.3618128},\n abstract = {While there exist many ways to deploy machine learning models on microcontrollers, it is non-trivial to choose the optimal combination of frameworks and targets for a given application. Thus, automating the end-to-end benchmarking flow is of high relevance nowadays. A tool called MLonMCU is proposed in this paper and demonstrated by benchmarking the state-of-the-art TinyML frameworks TFLite for Microcontrollers and TVM effortlessly with a large number of configurations in a low amount of time.},\n booktitle = {Proceedings of the 2023 Workshop on Compilers, Deployment, and Tooling for Edge AI},\n pages = {32\u201336},\n numpages = {5},\n keywords = {TinyML, neural networks, microcontrollers},\n location = {Hamburg, Germany},\n series = {CODAI '23}\n }\n ```\n\n### Other\nThis package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. However most of the templates was manually changed to be in Markdown instead of reStructuredText.\n\n- **Cookiecutter:** https://github.com/audreyr/cookiecutter\n- **`audreyr/cookiecutter-pypackage`:** https://github.com/audreyr/cookiecutter-pypackage\n\n\n## Acknowledgment\n\n<img src=\"./BMBF_gefoerdert_2017_en.jpg\" alt=\"drawing\" height=\"75\" align=\"left\" >\n\nThis research is partially funded by the German Federal Ministry of Education and Research (BMBF) within\nthe projects [Scale4Edge](https://www.edacentrum.de/scale4edge/) (grant number 16ME0127) and [MANNHEIM-FlexKI](https://www.edacentrum.de/projekte/MANNHEIM-FlexKI) (grant number 01IS22086L).\n\n\n# History\n\n## 0.1.0 (2021-11-12)\n\n* First closed-source release.\n\n\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "This project contains research code related to the deployment of inferenceor learning applications on tiny micro-controllers.",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/tum-ei-eda/mlonmcu"
},
"split_keywords": [
"mlonmcu"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1f6954e816cd6e924e708ec9df538975bf7ca74cef963712896582188c7462c5",
"md5": "17be03128b19aa93827f7bbadcec82dc",
"sha256": "2e8ec9f06c23a801ff9e4e4817e409fd43552402b8af68516549be0c68f09dd1"
},
"downloads": -1,
"filename": "mlonmcu-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "17be03128b19aa93827f7bbadcec82dc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 646649,
"upload_time": "2024-08-20T06:54:42",
"upload_time_iso_8601": "2024-08-20T06:54:42.623771Z",
"url": "https://files.pythonhosted.org/packages/1f/69/54e816cd6e924e708ec9df538975bf7ca74cef963712896582188c7462c5/mlonmcu-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aef7a2c00dc9c61af3edefa597fb5faeb0c70dd894294009a0fec6da30549fca",
"md5": "36b59d19d433b9ec17bfef9c1c850923",
"sha256": "5bbb913b19991a4500823950ea43944b588e590e0b22796cda59a1620e52593e"
},
"downloads": -1,
"filename": "mlonmcu-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "36b59d19d433b9ec17bfef9c1c850923",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 380852,
"upload_time": "2024-08-20T06:54:44",
"upload_time_iso_8601": "2024-08-20T06:54:44.404965Z",
"url": "https://files.pythonhosted.org/packages/ae/f7/a2c00dc9c61af3edefa597fb5faeb0c70dd894294009a0fec6da30549fca/mlonmcu-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-20 06:54:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tum-ei-eda",
"github_project": "mlonmcu",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "jinja2",
"specs": [
[
">=",
"3.1.3"
]
]
},
{
"name": "xdg",
"specs": []
},
{
"name": "GitPython",
"specs": []
},
{
"name": "networkx",
"specs": []
},
{
"name": "humanize",
"specs": []
},
{
"name": "pyelftools",
"specs": []
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "numpy",
"specs": [
[
"<",
"2.0"
]
]
},
{
"name": "psutil",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "filelock",
"specs": []
},
{
"name": "paramiko",
"specs": []
}
],
"tox": true,
"lcname": "mlonmcu"
}
JSON
