A lightweight C++ machine-learning and statistics library for embedded, edge and real-time workloads.
tinyML is a library (a collection of code other programs can use) for building neural networks in C++. A neural network is a set of connected artificial neurons that learns to turn inputs into outputs. "Embedded" and "edge" mean small computers built into devices, such as a microcontroller in a sensor, where there is no room for a large framework like PyTorch.
The library has two parts:
- Core (
TinyML::Core): a small, stable neural network with no other dependencies. It is MIT licensed, so anyone can use it. - Extended (
TinyML::Extended): research modules built on top, including attention and transformers, graph neural networks, physics-informed networks, Bayesian networks, reinforcement learning, time-series forecasting, generative models, quantisation and SIMD maths. Some of these files are under a separate commercial licence (see Licence).
The library has no window of its own. You write a small program that uses it, and that program prints results. There is also a playground, a small web page for trying the extended models (see Technical details).
- Computer Science: what a neuron, a weight and a layer are, in readable C++.
- Computer Science: how backpropagation trains a network, shown on the XOR problem below.
- Computer Science: how a C++ library is built, tested, installed and used by another project with CMake.
- Computer Science: SIMD (single instruction, multiple data), where the processor does the same sum on several numbers at once, and quantisation, where numbers are stored with fewer bits to save memory.
- Software engineering: semantic versioning, automated tests and the difference between a stable and a preview API.
You will need:
- A C++17 compiler: Xcode Command Line Tools on macOS,
build-essentialon Ubuntu, or Visual Studio with the C++ workload on Windows. - CMake 3.20 or newer.
- Git.
The project's automatic checks build and test it on Ubuntu with GCC and Clang. The core build, its test and the XOR example below were run on macOS for this guide.
-
Download the code:
git clone https://github.com/godofecht/tinyML.git cd tinyML -
Build the core and run its test:
cmake -S . -B build -DTINYML_BUILD_EXTENDED=OFF cmake --build build --parallel ctest --test-dir build --output-on-failureYou should see
TinyMLCoreSmokepass and a line that starts100% tests passed. -
Write your first program. Save this as
xor.cppin thetinyMLfolder. It teaches a network XOR: output 1 when exactly one of the two inputs is 1, and 0 otherwise.#include <tinyml/core.hpp> #include <iostream> int main() { ML::Model model({2, 4, 1}); // 2 inputs, 4 hidden neurons, 1 output const double in[4][2] = {{0,0},{0,1},{1,0},{1,1}}; const double out[4] = {0,1,1,0}; for (int pass = 0; pass < 5000; ++pass) for (int i = 0; i < 4; ++i) { model.feedForward({in[i][0], in[i][1]}); model.backPropagate({out[i]}); } for (int i = 0; i < 4; ++i) { model.feedForward({in[i][0], in[i][1]}); std::cout << in[i][0] << " XOR " << in[i][1] << " -> " << model.getResult()[0] << "\n"; } }
-
Compile and run it:
c++ -std=c++17 -Iinclude -Ibuild/generated src/NN.cpp src/Network.cpp xor.cpp -o xor ./xor
You should see four lines. The answers for 0 XOR 1 and 1 XOR 0 should be close to 1 (around 0.99), and the other two close to 0. The exact numbers change from run to run because the starting weights are random.
To build everything, including the extended modules and their tests, leave out -DTINYML_BUILD_EXTENDED=OFF in step 2. CMake then downloads xsimd and GoogleTest, so it needs an internet connection and takes longer.
A neuron adds up the outputs of the neurons in the layer before it, each multiplied by a weight (a number that sets how much that input matters). It passes the total through tanh, which squashes any number into the range -1 to 1. Each layer also has a bias neuron whose output is always 1, which lets a neuron shift its total up or down.
The network learns by backpropagation. After feedForward works out the outputs, backPropagate compares them with the targets, works out how much each weight added to the error, and moves each weight a small step to reduce it. The step size is the learning rate (eta, 0.15). Momentum (alpha, 0.5) adds half of the previous step, which keeps the weights moving in a steady direction.
ML::Model wraps a network and adds saving and loading of weights to a text file.
| File or folder | What is in it |
|---|---|
include/NN.h, src/NN.cpp |
the neuron: weights, tanh, gradients, weight updates |
include/Network.h, src/Network.cpp |
layers of neurons, feed-forward and backpropagation |
include/Model.h |
the ML::Model wrapper, with saveWeightsToFile and loadWeightsFromFile |
include/tinyml/core.hpp |
the one header to include for the core |
include/, src/ (other files) |
the extended modules |
tests/ |
the core smoke test, GoogleTest suites and the install test |
benchmarks/ |
speed measurements, built only on request |
examples/ |
example programs, built only on request |
playground/ |
a small web server and page for trying models in a browser |
blog/ |
write-ups of each development phase |
docs/ |
the API stability policy, production API notes and a wiki page |
CMakeLists.txt |
the build |
- In
xor.cpp, change the hidden layer from 4 neurons to 2, then to 1. How many does XOR need? - In
include/NN.h, changeetaandalphaand rebuildxor.cpp. How many passes does XOR need now? - In
src/NN.cpp,transferFunctionuses tanh. Try the sigmoid function, 1 / (1 + e^-x), instead. Remember to changetransferFunctionDerivativeto match. - Use
saveWeightsToFileandloadWeightsFromFilefrominclude/Model.hto save a trained XOR network and load it into a new model without training. - Add a check to
tests/core_smoke.cppthat a model learns XOR, so the test suite fails if training ever breaks. - Read
blog/phase-2-attention-mechanism-core.md, then find the matching code insrc/LightweightAttention.cpp.
The repository contains two intentionally different surfaces. TinyML::Core is the supported, dependency-free library surface with an install/export contract and semantic-versioning guarantees. TinyML::Extended contains the xsimd-backed model stack and research modules. The extended target is built by default for source compatibility, but its individual modules have their own stability status documented in docs/STABILITY.md.
The core requires a C++17 compiler and CMake 3.20 or newer. It has no third-party runtime or build dependency.
The extended target additionally requires xsimd 12.1 or newer. Top-level source builds can fetch xsimd automatically; package consumers are expected to provide it through their normal dependency manager.
Core only:
cmake -S . -B build -DTINYML_BUILD_EXTENDED=OFF
cmake --build build --parallel
ctest --test-dir build --output-on-failureFull source build:
cmake -S . -B build
cmake --build build --parallel
ctest --test-dir build --output-on-failureBenchmarks, examples and the playground are excluded from ordinary library builds on purpose. Enable them explicitly with TINYML_BUILD_BENCHMARKS, TINYML_BUILD_EXAMPLES or TINYML_BUILD_PLAYGROUND. All three need the extended build.
cmake -S . -B build -DTINYML_BUILD_EXTENDED=OFF -DTINYML_BUILD_TESTS=OFF
cmake --build build --parallel
cmake --install build --prefix ./installA downstream CMake project can then use the installed core without xsimd:
find_package(TinyML 1.0 CONFIG REQUIRED COMPONENTS Core)
target_link_libraries(my_target PRIVATE TinyML::Core)#include <tinyml/core.hpp>
ML::Model model ({ 2, 4, 1 });
model.feedForward ({ 0.25, -0.5 });
auto output = model.getResult();For the extended package:
find_package(TinyML 1.0 CONFIG REQUIRED COMPONENTS Extended)
target_link_libraries(my_target PRIVATE TinyML::Extended)The installed package includes a generated <tinyml/version.hpp> with TINYML_VERSION_MAJOR, TINYML_VERSION_MINOR, TINYML_VERSION_PATCH and TINYML_VERSION_STRING.
| Option | Default | Purpose |
|---|---|---|
TINYML_BUILD_EXTENDED |
ON |
Build the xsimd-backed extended library |
TINYML_BUILD_TESTS |
top-level only | Build the test suite |
TINYML_BUILD_BENCHMARKS |
OFF |
Build local benchmark executables |
TINYML_BUILD_EXAMPLES |
OFF |
Build examples |
TINYML_BUILD_PLAYGROUND |
OFF |
Build the playground server |
TINYML_FETCH_DEPENDENCIES |
top-level only | Fetch missing xsimd/GoogleTest dependencies |
TINYML_ENABLE_WARNINGS |
top-level only | Enable compiler warning flags on TinyML targets |
TINYML_ENABLE_LTO |
OFF |
Enable IPO/LTO when supported |
The playground is a small web server (playground/server.cpp, using cpp-httplib and nlohmann/json) with a browser page that runs and trains models through /run/<model> and /train/<model>. It listens on port 8080. These steps follow the build file and have not been tested:
cmake -S . -B build -DTINYML_BUILD_PLAYGROUND=ON
cmake --build build --target PlaygroundServer
./build/PlaygroundServerThen open http://localhost:8080/playground/index.html. The server shares the whole repository folder on every network interface, so only run it on a network you trust.
CI builds the zero-dependency core separately from the full library with GCC and Clang. Every configuration is installed into a staging prefix and then consumed by a fresh downstream CMake project through find_package, so packaging regressions fail before release.
Timing assertions are opt-in because shared CI hardware is unsuitable for performance gates. Benchmark executables are local-only. See TESTING.md.
Versioned releases are assembled from cmake --install instead of by manually copying build artifacts. Core and extended archives are published separately, with SHA-256 checksums.
The compatibility contract is written down in docs/STABILITY.md, which lists the stable, preview and source-only surfaces. The presence of a header in the repository does not by itself make it part of the contract.
Changes to the stable core follow semantic versioning. Preview and source-only modules may change before they graduate into the stable surface.
Security reports should follow SECURITY.md. Contributions should follow CONTRIBUTING.md. Release history is tracked in CHANGELOG.md. Planned work is in ROADMAP.md and docs/DEMO_ROADMAP.md.
Version 1.0.0. The core is stable. The extended modules are previews and may change.
Known problems:
- Three tests are compiled but turned off:
Phase8PhysicsInformedTest(long-running),Phase8PhysicsComprehensiveTest(results vary between runs) andPhase12ReinforcementTest(known failure on Linux). - The GitHub Pages workflow, which publishes
site/, has failed on its recent runs, so there is no live project page. scripts/run_playground.shdoes not work as written. It does not turn onTINYML_BUILD_PLAYGROUND, and it looks for the server inbuild/bin/, where the build does not put it. Use the playground steps above instead.- The v1.0.0 release on GitHub has no downloadable archives. The packaging described above is listed under "Unreleased" in
CHANGELOG.md.
tinyML uses two licences. Which one applies depends on the file. LICENSING.md lists every file.
- The core and some support files are MIT licensed. You can use, copy, change, share and sell them, as long as you keep the copyright notice. This covers
NN.h,Network.h,Model.hand their source files, and others listed in LICENSING.md. See LICENSE (MIT). - The commercial tier is proprietary. This covers the attention, transformer, dynamic network, generative, graph, physics-informed, reinforcement learning, time-series, production API and xsimd modules. You may use them for free, for non-commercial research, education or personal projects. You may also evaluate them internally, for non-commercial purposes, for up to 30 days. Any use must credit "Powered by tinyML (c) Abhishek Shivakumar". Commercial use needs a paid licence (USD 199 per developer per year). You may not share these files, or changed versions of them, without written permission. See LICENSE-COMMERCIAL.md.
For a school project this means you can use any part of tinyML, as long as you add the credit line. If you publish your work, publish only your own code and the MIT files, and link to this repo for the rest.
- Written by Abhishek Shivakumar.
- xsimd (BSD 3-Clause) for SIMD in the extended build.
- GoogleTest for the test suites.
- cpp-httplib by Yuji Hirose and JSON for Modern C++ by Niels Lohmann, both MIT, for the playground server.