A NuPIC Directories, Elements, and Help

This appendix gives an overview of the NuPIC components and explains how to get online help.

Topics

NuPIC Directory Structure
NuPIC Python Modules
NuPIC Node Types
How to Access NuPIC Built-in Help

NuPIC Directory Structure

This section gives an overview of the NuPIC directory structure.

Top level
README.TXT	contains release notes for this version of the software.
<license file>	The license file named LICENSE-NuPIC-<xyz>.pdf differs for different situations. The file contains a copy of the actual license terms you agreed to when you downloaded the software.
/bin	The /bin directory contains NuPIC executable programs.
	numenta_runtime	The Numenta Runtime Engine. This application can act as either a Supervisor or a Node Processor.
	launcher	Numenta tool for starting up the runtime in different configurations.
	orted (UNIX only)	The Open Run Time Environment Daemon from Open MPI (www.open-mpi.org), which Numenta uses for underlying process management and interprocess communication
	orterun (UNIX only)	a program for starting Open MPI programs.
/lib	The /lib directory contains NuPIC plugins and python modules used with NuPIC.
	libLearningPlugin.so /dll /dylib	Contains the learning node types provided by Numenta, including the TemporalPoolerNode, SpatialPoolerNode, and Zeta1TopNode.
	libBasicPlugin.so /dll /dylib	Contains all non-learning node types (except for Python nodes) provided by Numenta, including VectorFileEffector, VectorFileSensor, and PassThroughNode.
	python2.5/site-packages	Contains all Python packages provided by Numenta. The nupic python module contains NuPIC-specific functionality and are described in more detail below. NuPIC also includes the Python Imaging Library (PIL), the Numerical Python Library (numpy) the matplotlib plotting package, iPython, xPython, opencv, and the Traits GUI.
/share
	doc	The /doc directory contains documentation plus licenses for 3rd party software used by NuPIC.
	projects	The /projects directory contains example HTM applications such as bitworm, waves, flu, and pictures.
	openmpi (UNIX only)	The openmpi directory is used by Open MPI and can be ignored.
	vision	Vision Framework

NuPIC Python Modules

The nupic package contains all Numenta Python support. It includes utility routines for configuring and saving HTM networks, as well as routines for launching the Numenta Runtime Engine and using the Runtime Engine for training and testing HTM networks. The most important packages in NuPIC Tools are:

nupic.network - Contains modules for configuring, saving and running HTM networks. Includes helper functions and APIs for launching and managing the Numenta Runtime Engine.
nupic.analysis - Contains modules for analyzing and visualizing HTM networks and their inputs and outputs. Also contains utilities for constructing large-scale experiments for HTM networks and problem parameterizations.

For information on each package, call help(<package>), for example:

help(nupic.network) 

NuPIC Node Types

This section gives an overview of the available nodes. Extensive online help for each node is available. See How to Access NuPIC Built-in Help.

VectorFileSensor is a sensor that reads in text or csv (comma-separated values) files containing lists of vectors and outputs these vectors in sequence. The output is updated each time the sensor's compute() method is called. If repeatCount is greater than 1, each vector is repeated that many times before moving to the next one. The sensor loops when the end of the vector list is reached.

If the file contains an incorrect number of floats, the sensor has no way of checking assignments. Currently it silently ignore the last vector of floats if there is an incorrect number.

py.ImageSensor is a custom sensor created as a Python plug-in. This sensor was originally designed for the Pictures example but has been expanded to handle grayscale images. Because this node has been implemented in Python (not C++), getting help for it differs from getting help for other nodes. Use one of the following:

   nodeHelp("py.ImageSensor") 
   nodeHelp("py.ImageSensor") 
 

See the Vision Framework Guide for more information. 

SpatialPoolerNode and TemporalPoolerNode are the learning nodes that are usually used for all levels except the top level. The learning nodes implements the algorithm described in the Numenta Node Algorithms Guide. See Affecting Learning Node Behavior With Node Parameters in Advanced NuPIC Programming for an introduction to node parameters.
py.GarborNode - Performs Garbor filtering (spatial pooling). The algorithm of this in this node is customized to work with image applications. Node input must come from an ImageSensor or from a node with identical output format. See the Images example.
Zeta1TopNode - In learning mode, Zeta1TopNode learns coincidences and the mapping of those coincidences to categories. In inference mode, Zeta1TopNode computes to which category the input vector belongs. The output of Zeta1TopNode is thus a distribution over the categories of Zeta1TopNode, representing how likely the input vector is to belong to each of those categories.

See Affecting Learning Node Behavior With Node Parameters in Advanced NuPIC Programming for a discussion of Zeta1TopNode parameters and the Numenta Node Algorithms Guide.

py.SVMClassifierNode - Implements the SVM (support vector machines) algorithm.
py.KNNClassifierNode - Implements the KNN (k-nearest neighbor) algorithm. The node can perform learning and inference simultaneously.
VectorFileEffector is an effector that writes its inputs to a text file. You can specify the target filename using the setFile execute command at runtime.
PassThroughNode copies its input to its output. Both input and output must have 4-byte elements. PassThroughNodes might be useful if a sensor needs to connect to a node that's not at phase 1.

For an in-depth discussion of the NuPIC learning algorithm, see the Numenta Node Algorithms Guide. For an exploration of HTM behavior in general, which includes the discussion of an example, see the white paper The HTM Learning Algorithms.

How to Access NuPIC Built-in Help

The NuPIC APIs contain extensive built-in help. You can use Pydoc and Python's built-in help to get a complete online reference manual for the APIs. This section explains how you can access that help:

Using Pydoc

To get Unix manpage-style help on the nupic.network API, type the following into the operating system command prompt:

   pydoc nupic.network  

To generate and view HTML help, follow these steps:

a. Type pydoc -g.

b. Select Open Browser in the window that is displayed.

c. Click nupic for help on NuPIC.

To get help from the Python interactive prompt, type

   import nupic.network 
   help(nupic.network) 

Getting Help for Nodes and Helper Functions

In NuPIC, node types are implemented as plugins, so pydoc cannot generate help on node-specific parameters and commands. NuPIC includes nodeHelp, which reads in each plugin's specification and displays help for the corresponding node. For example, the following command generates extensive online help for SpatialPoolerNode:

from nupic.network import * 
nodeHelp(`SpatialPoolerNode') 

If the node is implemented as a Python plug-in, you can choose one of the following ways to invoke node help:

nodeHelp("nupic.pynodes.ImageSensor.ImageSensor") 
nodeHelp("py.ImageSensor") 

For the helper functions, you can display help as follows:

from nupic.network.helpers import * 
help ("nupic.network.helpers") 

You can also display help for individual helpers:

from nupic.network.helpers import * 
help ("AddLevel")