the-aerospace-corporation / brainblocks

Practical Tool for Building ML Applications with HTM-Like Algorithms
GNU Affero General Public License v3.0
61 stars 13 forks source link

BrainBlocks

BrainBlocks Logo

Introduction

BrainBlocks is a framework developed by The Aerospace Corporation for building scalable Machine Learning (ML) applications using principles derived from computational neuroscience. It models neuron activations with binary patterns (vectors of 1s and 0s) which form a kind of "cortical language". Assemblages of computational blocks transmit these binary patterns between each other to create computational workflows that exploit these neuroscience principles.

BrainBlocks is a Python 3 library wrapped around a single-thread C++ backend. The design of BrainBlocks represents the practical experience gained from solving machine learning problems using a Hierarchical Temporal Memory (HTM) like approach.

Design

BrainBlocks is designed to be:

The current computational blocks provided are:

Theory

Further discussion on the theory of BrainBlocks can be found here.

Machine Learning

Multivariate Time-Series Anomaly Detection

Multivariate Abnormalities

Comparison with Scikit-learn Classifiers

Data Classification

Getting Started

System Requirements

BrainBlocks is known to run on the following platforms:

To install and run, you need at least the following

If you want to develop BrainBlocks on your system, you need at least the following additional dependencies:

Install

The easiest way to install BrainBlocks is using pip.

pip install brainblocks

Run

Begin by running any of the examples found in the examples directory. Here we show converting scalar values into binary patterns using the ScalarTransformer.

python examples/python/transformers/scalar_transformer.py

An abridged version of the script is shown below:

from brainblocks.blocks import ScalarTransformer

# Scalar value sequence
values = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]

# Configure ScalarTransformer
st = ScalarTransformer(
    min_val=0.0, # minimum input value
    max_val=1.0, # maximum input value
    num_s=128,  # number of statelets
    num_as=16)  # number of active statelets

# Convert scalars to distributed binary representation
for i in range(len(values)):

    # Set scalar value and compute
    st.set_value(values[i])
    st.feedforward()

    # print scalar value and its binary representation
    print(values[i], st.output.bits)

Development

Build

Alternatively, you can build BrainBlocks on your system following these steps.

Clone the repository

git clone https://github.com/the-aerospace-corporation/brainblocks

Change to the project directory

cd brainblocks

Build and install

pip install .

Build Alternatives

You can build the python packages separately and find them in dist/ if the build package is installed in your environment.

pip install build
python -m build 

We also provide a helper script to build and reinstall BrainBlocks if you are making changes to the core code and want to experiment. This will clean up previous BrainBlocks installations and install fresh from the local code.

python helper.py --install

Tests

Run Python unit tests:

pytest

Build core C++ unit tests

python helper.py --cpptests
cd build/tests/cpp
ls test_*

More Helper Script Options

Clean project directory of build artifacts:

python helper.py --clean

Python unit tests

python helper.py --test

Uninstall from Python environment

python helper.py --uninstall

Just build Python packages

python helper.py --build

Project Layout

.
├── .github                  # Workflow scripts for build, testing, and packaging
├── build                    # Temporary build workspace
├── dist                     # Temporary location of built python packages
├── docs                     # Extra Documentation
├── examples                 # Examples of BrainBlocks usage
│   └── python
│       └── classification   # PatternClassifier examples
│       └── context_learner  # ContextLearner examples
│       └── pooling          # PatternPooler example
│       └── experiments      # Experiments and visualizations
│       └── sequence_learner # SequenceLearner examples
│       └── transformers     # Transformer examples
├── src
│   ├── cpp               # Core C++ code
│   │   └── blocks        # Core C++ block algorithms
│   ├── python            # Python package code
│   │   ├── blocks        # Interface to block primitives
│   │   ├── datasets      # Dataset generation tools
│   │   ├── metrics       # Metrics for binary representations
│   │   ├── templates     # Common architecture templates
│   │   └── tools         # High-level package tools
│   └── wrappers          # Python bindings
├── tests                 # Unit tests
│   ├── cpp               # C++ core unit tests
│   └── python            # Python nit tests
├── .gitignore            # files to exclude from version control
├── CMakeLists.txt        # CMake configuration for core C++ build
├── helper.py             # Helper script
├── LICENSE               # AGPLv3 license
├── MANIFEST.in           # Manifest file for python package
├── pyproject.toml        # Modern build system configuration file
├── README.md             # README file
└── setup.cfg             # setuptools config values
└── setup.py              # setuptools build script

About Us

The Aerospace Corporation

This projected was developed internally at The Aerospace Corporation by:

License

This project is licensed under AGPLv3.

© The Aerospace Corporation 2022