nupic.core-legacy
nupic.core-legacy copied to clipboard
Implementation of core NuPIC algorithms in C++ (under construction)
NuPIC Core
![Coverage Status](https://coveralls.io/repos/numenta/nupic.core/badge.png?branch=master)
This repository contains the C++ source code for the Numenta Platform for Intelligent Computing (NuPIC). It will eventually contain all algorithms for NuPIC, but is currently in a transition period. For details on building NuPIC within the python environment, please see http://github.com/numenta/nupic.
Installing from a Release
You can install the nupic.bindings
Python package from PyPI:
pip install nupic.bindings
Optionally include --user
or other flags to determine where the package is installed.
Note: On Linux this will do a source installation and will require that the prerequisites specified below are installed.
Building from Source
Important notes:
-
$NUPIC_CORE
is the current location of the repository that you downloaded from GitHub. - Platform specific Readme.md text files exist in some
external/
subdirectories - See the main wiki for more build notes
Prerequisites
- Python - We recommend you use the system version where possibly.
- Version 2.7
-
NumPy - Can be installed through some system package managers or via pip
- Version 1.12.1
-
pycapnp
- Version 0.5.8 (Linux and OSX only)
- CMake
Note: On Windows, Python package dependencies require the following compiler package to be installed: Microsoft Visual C++ Compiler for Python 2.7
The Python dependencies (NumPy and pycapnp) can be installed with pip
:
pip install -r bindings/py/requirements.txt
Simple Source Installation (does not support incremental builds)
The easiest way to build from source is as follows. This does not support incremental builds.
python setup.py install
Optionally include --user
or other flags to determine where the package is installed.
Testing the Installation
Regardless of how you install nupic.bindings
, the nupic-bindings-check
command-line script should be installed. Make sure that you include the Python bin
installation location in your PATH
environment variable and then execute the script:
nupic-bindings-check
Developer Installation
This option is for developers that would like the ability to do incremental builds of the C++ or for those that are using the C++ libraries directly.
Note: The following sub-sections are related to Linux and OSX only. For Windows refer to the
external\windows64-gcc\README.md
file.
Configure and generate C++ build files:
mkdir -p $NUPIC_CORE/build/scripts
cd $NUPIC_CORE/build/scripts
cmake $NUPIC_CORE -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release -DPY_EXTENSIONS_DIR=$NUPIC_CORE/bindings/py/src/nupic/bindings
Notes:
- This will generate Release build files. For a debug build, change
-DCMAKE_BUILD_TYPE
toDebug
. - To build nupic.core for generating the nupic.bindings python extension, pass
-DNUPIC_BUILD_PYEXT_MODULES=ON
; it is the default at this time. - To build nupic.core as a standalone static library, pass
-DNUPIC_BUILD_PYEXT_MODULES=OFF
. - If you have dependencies precompiled but not in standard system locations then you can specify where to find them with
-DCMAKE_PREFIX_PATH
(for bin/lib) and-DCMAKE_INCLUDE_PATH
(for header files). - The
-DCMAKE_INSTALL_PREFIX=../release
option shown above is optional, and specifies the location wherenupic.core
should be installed. If omitted,nupic.core
will be installed in a system location. Using this option is useful when testing versions ofnupic.core
language bindings inbindings
. - Setting
-DPY_EXTENSIONS_DIR
copies the Python exension files to the specified directory. If the extensions aren't present when the Python build/installation is invoked then the setup.py file will run the cmake/make process to generate them. Make sure to include this flag if you want to do incremental builds of the Python extensions. - On OSX with multiple Python installs (e.g. via brew) cmake might erroneously pick various pieces from different installs which will likely produce abort trap at runtime. Remove cmake cache and re-run cmake with
-DPYTHON_LIBRARY=/path/to/lib/libpython2.7.dylib
and-DPYTHON_INCLUDE_DIR=/path/to/include/python2.7
options to override with desired Python install path. - To use Include What You Use during compilation, pass
-DNUPIC-IWYU=ON
. This requires that IWYU is installed and findable by CMake, with a minimum CMake version of 3.3. IWYU can be installed from https://include-what-you-use.org/ for Windows and Linux, and on OS X using https://github.com/jasonmp85/homebrew-iwyu. - If you would like to install all headers, libraries, and executables to the install location for C++ clients when building the nupic.binding python extensions, pass
-NUPIC_TOGGLE_INSTALL=ON
.
Build:
# While still in $NUPIC_CORE/build/scripts
make -j3
Note: The
-j3
option specifies '3' as the maximum number of parallel jobs/threads that Make will use during the build in order to gain speed. However, you can increase this number depending your CPU.
Install:
# While still in $NUPIC_CORE/build/scripts
make install
Run the tests:
cd $NUPIC_CORE/build/release/bin
./cpp_region_test
./unit_tests
...
Install nupic.bindings Python library:
cd $NUPIC_CORE
python setup.py develop
Note: If the extensions haven't been built already then this will call the cmake/make process to generate them.
If you get a gcc exit code 1, you may consider running this instead:
python setup.py develop --user
If you are installing on Mac OS X, you must add the instruction ARCHFLAGS="-arch x86_64"
before the python call:
ARCHFLAGS="-arch x86_64" python setup.py develop
Alternatively, you can use the install
command (as opposed to develop
) to copy the installation files rather than link to the source location.
python setup.py install
Note: If you get a "permission denied" error when using the setup commands above, you may add the
--user
flag to install to a location in your home directory, which should resolve any permissions issues. Doing this, you may need to add this location to your PATH and PYTHONPATH.
Once it is installed, you can import NuPIC bindings library to your python script using:
import nupic.bindings
You can run the nupic.bindings tests via setup.py
:
python setup.py test
Using graphical interface
Generate the IDE solution:
- Open CMake executable.
- Specify the source folder (
$NUPIC_CORE/src
). - Specify the build system folder (
$NUPIC_CORE/build/scripts
), i.e. where IDE solution will be created. - Click
Generate
. - Choose the IDE that interest you (remember that IDE choice is limited to your OS, i.e. Visual Studio is available only on CMake for Windows).
Build:
- Open
nupic_core.*proj
solution file generated on$NUPIC_CORE/build/scripts
. - Run
ALL_BUILD
project from your IDE.
Run the tests:
- Run any
tests_*
project from your IDE (checkoutput
panel to see the results).
Build Documentation
Run doxygen, optionally specifying the version as an environment variable:
PROJECT_VERSION=`cat VERSION` doxygen
The results will be written out to the html
directory.