This is a Community Fork of the nupic.core C++ repository, with Python bindings. This implements the theory as described in Numenta's BAMI.
- Actively developed C++ core library (Numenta's NuPIC repos are in archive mode)
- Clean, lean, optimized, and modern codebase
- Stable and well tested code
- Open and easier involvement of new ideas across HTM community (it's fun to contribute, we make the master run stable, but we are open to experiments and revamps of the code if it proves useful).
- Interfaces to C++ and Python
- Implemented in C++17 and above. both Static lib and shared lib .so for use with C++ applications.
- C++ Extensions for Python3 using pybind11 which exposes all htm.core library functions.
- Cross Platform Support for Windows, Linux, OSX.
- Easy installation. Few dependencies and most are obtained automatically by CMake during the build.
- Sparse Distributed Representation class, integration, and tools for working with them.
- API-compatibility with Numenta's original Python 2.0 code.
An objective is to stay close to the Nupic API Docs.
This is a priority for the
NetworkAPI. The algorithms APIs on the other hand have deviated from their original API (but their basic logic is the same as Numenta's). If you are porting your code to this codebase, please follow the API Differences and consult the API Changelog. - The 'NetworkAPI', as originally defined by the NuPIC library, includes a set of build-in Regions. These are described in NetworkAPI docs
- REST interface for
NetworkAPIwith a REST server.
For running C++ apps/examples/tests from binary release: none. If you want to use python, then obviously:
-
- Standard Python 3.9+ (Recommend using the latest) [Tested with 3.11.1, 3.12.4, 3.13]
- Must be running in a virtual environment such as venv.
- Anaconda Python 3.9+
- On windows you must run from within 'Anaconda Prompt' not 'Command Prompt'.
- Anaconda Python is not tested in our CI.
Only the standard python from python.org have been tested. On Linux you will need both the Python install and the Python-dev install '$ sudo apt install python3.13' '$ sudo apt install python3.13-dev'
- You will also want to setup a [https://docs.python.org/3/library/venv.html(venv environment).
- Standard Python 3.9+ (Recommend using the latest) [Tested with 3.11.1, 3.12.4, 3.13]
-
C++ compiler: c++17 compatible (ie. g++, clang++). On Windows, tested with MSVC 2019, 2022
- CMake 3.21+.
Install the latest CMake using https://cmake.org/download/
- CMake 3.21+.
Note: Windows MSVC 2019 and up runs as C++17 by default. On linux use -std=c++17 if not default.
An advantage of HTM.core is its well tested self-sustained dependency install, so you can install
HTM on almost any platform/system if installing from source.
Fork or download the HTM-Community htm.core repository from https://github.com/htm-community/htm.core.
To fork the repo with git:
git clone https://github.com/htm-community/htm.core
-
Prerequisites: Must create a Python virtual environment. Create a virtual environment:
python3 -m venv .venvActivate the virtual environment:
.venv/bin/activate(or .venv\Scripts\activate on Windows) -
Build and install:
cd <project directory> python htm_install.pyThis will obtain all prerequisites build a release version of htm.core, then it will install the htm package into the Python environment that was used for the build. The C++ library (htm_core.lib), include files and executables can be found in build/Release.
The C++ portion of the build leaves cmake cache and build artifacts in the folder build. If the build needs to be restarted, delete the build folder.
The Python portion of the build is performed in an isolated environment in a temp folder. When the build completes, the build artifacts and cache are deleted.
-
After the build completes you are ready to import the library:
python.exe >>> import htm # Python Library >>> import htm.bindings # C++ Extensions >>> help( htm ) # Documentation
You can run the unit tests with
python htm_test.py
The following C++ build artifacts can be found in build/Release
| Build Artifact | File Location |
|---|---|
| Static Library | build/Release/lib/libhtm-core.a |
| `build/Release/lib/htm_core.lib | |
| Shared Library | build/Release/lib/libhtm-core.so |
| (Linux only) | |
| Header Files | build/Release/include/ |
| Unit Tests | build/Release/bin/unit_tests |
| Hotgym Dataset Example | build/Release/bin/benchmark_hotgym |
| MNIST Dataset Example | build/Release/bin/mnist_sp |
| REST Server Example | build/Release/bin/rest_server |
| REST Client Example | build/Release/bin/rest_client |
g++ -o myapp -std=c++17 -I <path-to-repo>/build/Release/include myapp.cpp -L <path-to-repo>/build/Release/lib -lhtm_core -lpthread -ldl
export LD_LIBRARY_PATH=<path-to-repo>/build/Release/lib:$LD_LIBRARY_PATH
./myapp
Refer to instructions for AirGap installs.
Our Dockerfile allows easy (cross) compilation from/to many HW platforms. This docker file does the full build, test & package build. It takes quite a while to complete.
If you are on amd64 (x86_64) and would like to build a Docker image:
docker build --build-arg arch=amd64 .If you are on ARM64 and would like to build a Docker image, run the command
below. The CI automated ARM64 build (detailed below) uses this
specifically.
docker build --build-arg arch=arm64 .Note:
- If you're directly on ARM64/aarch64 (running on real HW) you don't need the docker image, and can use the standard binary/source installation procedure.
A bit tricky part is providing cross-compilation builds if you need to build for a different platform (aarch64) then your system is running (x86_64). A typical case is CI where all the standard(free) solutions offer only x86_64 systems, but we want to build for ARM.
See our ARM release workflow.
When running locally, run:
docker run --privileged --rm multiarch/qemu-user-static:register
docker build -t htm-arm64-docker --build-arg arch=arm64 -f Dockerfile-pypi .
docker run htm-arm64-docker uname -a
docker run htm-arm64-docker python htm_test.pyNote:
- the 1st line allows you to emulate another platform on your HW.
- 2nd line builds the docker image. The Dockerfile is a lightweight Alpine_arm64 image, which does full build,test&package build. It can take quite a long time. The Dockerfile-pypi "just" switches you to ARM64/aarch64 env, and then you can build & test yourself.
For Doxygen see docs README. For NetworkAPI see NetworkAPI docs.
The library entry point documentation can be obtained using the help call.
shell python >>> import htm # Python Library >>> import htm.bindings # C++ Extensions >>> help( htm ) # Documentation
The installation script (python htm_install.py) will automatically download and build the dependencies it needs.
- LibYaml
- Eigen
- gtest
- cereal
- mnist
- sqlite3
- digestpp (for SimHash encoders)
- It also downloads and installs all python packages needed for the build and execution.
If you are installing on an air-gap computer (one without Internet) then you can
manually download the dependencies. On another computer, download the
distribution packages as listed. Copy these to
${REPOSITORY_DIR}/build/ThirdParty/ on the target machine.
Unzip the archive and rename the folder as in the left column.
- note1: Used for examples. Not required to run but the build expects it.
We support test-driven development with reproducible builds. You should run tests locally.
There are two sets (somewhat duplicit) tests for c++ and python.
- C++ Unit tests -- to run:
./build/Release/bin/unit_tests - Python Unit tests -- to run:
python -m pytestRun both by runningpython htm_test.py
There are a number of python examples, which are runnable from the command line.
They are located in the module htm.examples.
Example Command Line Invocation: $ python -m htm.examples.sp.hello_sp
Look in:
py/htm/examples/py/htm/advanced/examples/
This is a simple example application that calls the SpatialPooler and
TemporalMemory algorithms directly. This attempts to predict the electrical
power consumption for a gymnasium over the course of several months.
To run python version:
python -m htm.examples.hotgym
To run C++ version: (assuming current directory is root of the repository)
./build/Release/bin/benchmark_hotgymThere is also a dynamically linked version of Hot Gym (not available on MSVC).
You will need specify the location of the shared library with LD_LIBRARY_PATH.
To run: (assuming current directory is root of the repository)
LD_LIBRARY_PATH=build/Release/lib ./build/Release/bin/dynamic_hotgymThe task is to recognize images of hand written numbers 0-9. This is often used as a benchmark. This should score at least 95%.
To run: (assuming current directory is top of repository)
./build/Release/bin/mnist_sp
In Python:
python py/htm/examples/mnist.py
The REST interface for NetworkAPI provides a way to access the underlining htm.core library using a REST client. The examples provide both a full REST web server that can process the web requests that allow the user to create a Network object resource and perform htm operations on it. Message layout details can be found in NetworkAPI REST docs. To run:
./build/Release/bin/server [port [network_interface]]
A REST client, implemented in C++ is also provided as an example of how to use the REST web server. To run: first start the server.
./build/Release/bin/client [host [port]]
The default host is 127.0.0.1 (the local host) and the port is 8050.
The htm.core library is distributed under GNU Affero Public License version 3 (AGPLv3). The full text of the license can be found at http://www.gnu.org/licenses.
Libraries that are incorporated into htm.core have the following licenses:
| Library | Source Location | License |
|---|---|---|
| libyaml | https://github.com/yaml/libyaml | https://github.com/yaml/libyaml/blob/master/LICENSE |
| eigen | http://eigen.tuxfamily.org/ | https://www.mozilla.org/en-US/MPL/2.0/ |
| pybind11 | https://github.com/pybind/pybind11 | https://github.com/pybind/pybind11/blob/master/LICENSE |
| cereal | https://uscilab.github.io/cereal/ | https://opensource.org/licenses/BSD-3-Clause |
| digestpp | https://github.com/kerukuro/digestpp | released into public domain |
| cpp-httplib | https://github.com/yhirose/cpp-httplib | https://github.com/yhirose/cpp-httplib/blob/master/LICENSE |
We're happy that you can use the community work in this repository or even join the development! Please give us attribution by linking to us as htm.core at https://github.com/htm-community/htm.core/ , and for papers we suggest to use the following BibTex citation:
@misc{htmcore2019,
abstract = "Implementation of cortical algorithms based on HTM theory in C++ \& Python. Research \& development library.",
author = "M. Otahal and D. Keeney and D. McDougall and others",
commit = bf6a2b2b0e04a1d439bb0492ea115b6bc254ce18,
howpublished = "\url{https://github.com/htm-community/htm.core/}",
journal = "Github repository",
keywords = "HTM; Hierarchical Temporal Memory; NuPIC; Numenta; cortical algorithm; sparse distributed representation; anomaly; prediction; bioinspired; neuromorphic",
publisher = "Github",
series = "{Community edition}",
title = "{HTM.core implementation of Hierarchical Temporal Memory}",
year = "2019"
}
Note: you can update the commit to reflect the latest version you have been working with to help making the research reproducible.
Numenta's BAMI The formal theory behind it all. Also consider Numenta's Papters.
HTM School is a set of videos that explains the concepts.
Indy's Blog
For questions regarding the theory can be posted to the HTM Forum.
Questions and bug reports regarding the library code can be posted in htm.core Issues blog.
Community projects for working with HTM.
This project aspires to create tool that helps visualize HTM systems in 3D by using opensource framework for 3D rendering https://www.panda3d.org/
NetworkAPI has a region called "DatabaseRegion". This region can be used for generating SQLite file and later on read by PandaVis - DashVis feature, to show interactive plots in web browser on localhost. See napi_hello_database for basic usage.
For more info, visit repository of the project
