Engine

class nupic::NuPIC

Initialization and shutdown operations for NuPIC engine.

Public Static Functions

static void init()

Initialize NuPIC.

Note
It’s safe to reinitialize an initialized NuPIC.
Note
Creating a Network will auto-initialize NuPIC.

static void shutdown()

Shutdown NuPIC.

Note
As a safety measure, NuPIC with any Network still registered to it is not allowed to be shut down.

static bool isInitialized()

Return
Whether NuPIC is initialized successfully.

class nupic::Network

Represents an HTM network.

A network is a collection of regions.

Inherits from nupic::Serializable< NetworkProto >

Construction and destruction

Network()

Create an new Network and register it to NuPIC.

Note
Creating a Network will auto-initialize NuPIC.

Network(const std::string &path)

Create a Network by loading previously saved bundle, and register it to NuPIC.

Note
Creating a Network will auto-initialize NuPIC.
Parameters
  • path: The path to the previously saved bundle file, currently only support files with .nta extension.

~Network()

Destructor.

Destruct the network and unregister it from NuPIC:

  • Uninitialize all regions
  • Remove all links
  • Delete the regions themselves

void initialize()

Initialize all elements of a network so that it can run.

Note
This can be called after the Network structure has been set and before Network.run(). However, if you don’t call it, Network.run() will call it for you. Also sets up various memory buffers etc. once the Network structure has been finalized.

Serialization

void save(const std::string &name)

Save the network to a network bundle (extension .nta).

Parameters
  • name: Name of the bundle

Region and Link operations

Region *addRegion(const std::string &name, const std::string &nodeType, const std::string &nodeParams)

Create a new region in a network.

Return
A pointer to the newly created Region
Parameters
  • name: Name of the region, Must be unique in the network
  • nodeType: Type of node in the region, e.g. “FDRNode”
  • nodeParams: A JSON-encoded string specifying writable params

Region *addRegionFromBundle(const std::string &name, const std::string &nodeType, const Dimensions &dimensions, const std::string &bundlePath, const std::string &label)

Create a new region from saved state.

Parameters
  • name: Name of the region, Must be unique in the network
  • nodeType: Type of node in the region, e.g. “FDRNode”
  • dimensions: Dimensions of the region
  • bundlePath: The path to the bundle
  • label: The label of the bundle

Return
A pointer to the newly created Region

Region *addRegionFromProto(const std::string &name, RegionProto::Reader &proto)

Create a new region from saved Cap’n Proto state.

Return
A pointer to the newly created Region
Parameters
  • name: Name of the region, Must be unique in the network
  • proto: The capnp proto reader

void removeRegion(const std::string &name)

Removes an existing region from the network.

Parameters

void link(const std::string &srcName, const std::string &destName, const std::string &linkType, const std::string &linkParams, const std::string &srcOutput = "", const std::string &destInput = "", const size_t propagationDelay = 0)

Create a link and add it to the network.

Parameters
  • srcName: Name of the source region
  • destName: Name of the destination region
  • linkType: Type of the link
  • linkParams: Parameters of the link
  • srcOutput: Name of the source output
  • destInput: Name of the destination input
  • propagationDelay: Propagation delay of the link as number of network run iterations involving the link as input; the delay vectors, if any, are initially populated with 0’s. Defaults to 0=no delay

void removeLink(const std::string &srcName, const std::string &destName, const std::string &srcOutputName = "", const std::string &destInputName = "")

Removes a link.

Parameters
  • srcName: Name of the source region
  • destName: Name of the destination region
  • srcOutputName: Name of the source output
  • destInputName: Name of the destination input

Access to components

const Collection<Region *> &getRegions() const

Get all regions.

Return
A Collection of Region objects in the network

Collection<Link *> getLinks()

Get all links between regions.

Return
A Collection of Link objects in the network

void setPhases(const std::string &name, std::set<UInt32> &phases)

Set phases for a region.

Parameters
  • name: Name of the region
  • phases: A tuple of phases (must be positive integers)

std::set<UInt32> getPhases(const std::string &name) const

Get phases for a region.

Return
Set of phases for the region
Parameters
  • name: Name of the region

UInt32 getMinPhase() const

Get minimum phase for regions in this network.

If no regions, then min = 0.

Return
Minimum phase

UInt32 getMaxPhase() const

Get maximum phase for regions in this network.

If no regions, then max = 0.

Return
Maximum phase

void setMinEnabledPhase(UInt32 minPhase)

Set the minimum enabled phase for this network.

Parameters
  • minPhase: Minimum enabled phase

void setMaxEnabledPhase(UInt32 minPhase)

Set the maximum enabled phase for this network.

Parameters
  • minPhase: Maximum enabled phase

UInt32 getMinEnabledPhase() const

Get the minimum enabled phase for this network.

Return
Minimum enabled phase for this network

UInt32 getMaxEnabledPhase() const

Get the maximum enabled phase for this network.

Return
Maximum enabled phase for this network

Running

typedef void (*runCallbackFunction)(Network *, UInt64 iteration, void *)

The type of run callback function.

You can attach a callback function to a network, and the callback function is called after every iteration of run().

To attach a callback, just get a reference to the callback collection with getCallbacks() , and add a callback.

typedef std::pair<runCallbackFunction, void *> callbackItem

Type definition for a callback item, combines a runCallbackFunction and a void* pointer to the associated data.

void run(int n)

Run the network for the given number of iterations of compute for each Region in the correct order.

For each iteration, Region.compute() is called.

Parameters
  • n: Number of iterations

Collection<callbackItem> &getCallbacks()

Get reference to callback Collection.

Return
Reference to callback Collection

Profiling

void enableProfiling()

Start profiling for all regions of this network.

void disableProfiling()

Stop profiling for all regions of this network.

void resetProfiling()

Reset profiling timers for all regions of this network.

class nupic::Region

Represents a set of one or more “identical” nodes in a Network.

Constructors

Note
Region constructors are not available in the public API. Internally regions are created and owned by Network.

Inherits from nupic::Serializable< RegionProto >

Region information

Network *getNetwork()

Get the network containing this region.

Return
The network containing this region

const std::string &getName() const

Get the name of the region.

Return
The region’s name

const Dimensions &getDimensions() const

Get the dimensions of the region.

Return
The region’s dimensions

void setDimensions(Dimensions &dimensions)

Assign width and height to the region.

Parameters
  • dimensions: A Dimensions object that describes the width and height

Element interface methods

const std::string &getType() const

Get the type of the region.

Return
The node type as a string

const Spec *getSpec() const

Get the spec of the region.

Return
The spec that describes this region

static const Spec *getSpecFromType(const std::string &nodeType)

Get the Spec of a region type without an instance.

Return
The Spec that describes this region type
Parameters
  • nodeType: A region type as a string

Parameter getters and setters

Int32 getParameterInt32(const std::string &name) const

Get the parameter as an Int32 value.

Return
The value of the parameter
Parameters
  • name: The name of the parameter

UInt32 getParameterUInt32(const std::string &name) const

Get the parameter as an UInt32 value.

Return
The value of the parameter
Parameters
  • name: The name of the parameter

Int64 getParameterInt64(const std::string &name) const

Get the parameter as an Int64 value.

Return
The value of the parameter
Parameters
  • name: The name of the parameter

UInt64 getParameterUInt64(const std::string &name) const

Get the parameter as an UInt64 value.

Return
The value of the parameter
Parameters
  • name: The name of the parameter

Real32 getParameterReal32(const std::string &name) const

Get the parameter as an Real32 value.

Return
The value of the parameter
Parameters
  • name: The name of the parameter

Real64 getParameterReal64(const std::string &name) const

Get the parameter as an Real64 value.

Return
The value of the parameter
Parameters
  • name: The name of the parameter

Handle getParameterHandle(const std::string &name) const

Get the parameter as an Handle value.

Return
The value of the parameter
Parameters
  • name: The name of the parameter

bool getParameterBool(const std::string &name) const

Get a bool parameter.

Return
The value of the parameter
Parameters
  • name: The name of the parameter

void setParameterInt32(const std::string &name, Int32 value)

Set the parameter to an Int32 value.

Parameters
  • name: The name of the parameter
  • value: The value of the parameter

void setParameterUInt32(const std::string &name, UInt32 value)

Set the parameter to an UInt32 value.

Parameters
  • name: The name of the parameter
  • value: The value of the parameter

void setParameterInt64(const std::string &name, Int64 value)

Set the parameter to an Int64 value.

Parameters
  • name: The name of the parameter
  • value: The value of the parameter

void setParameterUInt64(const std::string &name, UInt64 value)

Set the parameter to an UInt64 value.

Parameters
  • name: The name of the parameter
  • value: The value of the parameter

void setParameterReal32(const std::string &name, Real32 value)

Set the parameter to a Real32 value.

Parameters
  • name: The name of the parameter
  • value: The value of the parameter

void setParameterReal64(const std::string &name, Real64 value)

Set the parameter to a Real64 value.

Parameters
  • name: The name of the parameter
  • value: The value of the parameter

void setParameterHandle(const std::string &name, Handle value)

Set the parameter to a Handle value.

Parameters
  • name: The name of the parameter
  • value: The value of the parameter

void setParameterBool(const std::string &name, bool value)

Set the parameter to a bool value.

Parameters
  • name: The name of the parameter
  • value: The value of the parameter

void getParameterArray(const std::string &name, Array &array) const

Get the parameter as an Array value.

array is a memory buffer. If the buffer is allocated, the value is copied into the supplied buffer; otherwise array would be asked to allocate the buffer and copy into it.

Parameters
  • name: The name of the parameter
  • array: The value of the parameter

A typical use might be that the caller would supply an unallocated buffer on the first call and then reuse the memory buffer on subsequent calls, i.e.

{
  // no buffer allocated
  Array buffer(NTA_BasicTypeInt64);

  // buffer is allocated, and owned by Array object
  getParameterArray("foo", buffer);

  // uses already-allocated buffer
  getParameterArray("foo", buffer);

} // Array destructor called -- frees the buffer

Throws an exception if the supplied array is not big enough.

void setParameterArray(const std::string &name, const Array &array)

Set the parameter to an Array value.

Note
array must be initialized before calling setParameterArray().
Parameters
  • name: The name of the parameter
  • array: The value of the parameter

void setParameterString(const std::string &name, const std::string &s)

Set the parameter to a std::string value.

Strings are handled internally as Byte Arrays, but this interface is clumsy. setParameterString() and getParameterString() internally use byte arrays but converts to/from strings.

Parameters
  • name: The name of the parameter
  • s: The value of the parameter

setParameterString() is implemented with one copy (from the string into the node) but getParameterString() requires a second copy so that there are temporarily three copies of the data in memory (in the node, in an internal Array object, and in the string returned to the user)

std::string getParameterString(const std::string &name)

Get the parameter as a std::string value.

Return
The value of the parameter
See
setParameterString()
Parameters
  • name: The name of the parameter

bool isParameterShared(const std::string &name) const

Tells whether the parameter is shared.

Return
Whether the parameter is shared
Parameters
  • name: The name of the parameter

Throws an exception if it’s not overridden

Note
This method must be overridden by subclasses.

Inputs and outputs

void prepareInputs()

Copies data into the inputs of this region, using the links that are attached to each input.

virtual ArrayRef getInputData(const std::string &inputName) const

Get the input data.

Return
An ArrayRef that contains the input data.
Parameters
  • inputName: The name of the target input

virtual ArrayRef getOutputData(const std::string &outputName) const

Get the output data.

Return
An ArrayRef that contains the output data.
Parameters
  • outputName: The name of the target output

virtual size_t getInputCount(const std::string &inputName) const

Get the count of input data.

Return
The count of input data
Parameters
  • inputName: The name of the target input

virtual size_t getOutputCount(const std::string &outputName) const

Get the count of output data.

Return
The count of output data
Parameters
  • outputName: The name of the target output

Operations

virtual void enable()

virtual void disable()

virtual std::string executeCommand(const std::vector<std::string> &args)

Request the underlying region to execute a command.

Return
The result value of command execution is a string determined by the underlying region.
Parameters
  • args: A list of strings that the actual region will interpret. The first string is the command name. The other arguments are optional.

void compute()

Perform one step of the region computation.

Profiling

void enableProfiling()

Enable profiling of the compute and execute operations.

void disableProfiling()

Disable profiling of the compute and execute operations.

void resetProfiling()

Reset the compute and execute timers.

const Timer &getComputeTimer() const

Get the timer used to profile the compute operation.

Return
The Timer object used to profile the compute operation

const Timer &getExecuteTimer() const

Get the timer used to profile the execute operation.

Return
The Timer object used to profile the execute operation

class nupic::Link

Represents a link between regions in a Network.

Inherits from nupic::Serializable< LinkProto >

Initialization

Links have four-phase initialization.

  1. construct with link type, params, names of regions and inputs/outputs
  2. wire in to network (setting src and dest Output/Input pointers)
  3. set source and destination dimensions
  4. initialize sets the offset in the destination Input (not known earlier)

De-serializing is the same as phase 1.

In phase 3, NuPIC will set and/or get source and/or destination dimensions until both are set. Normally we will only set the src dimensions, and the dest dimensions will be induced. It is possible to go the other way, though.

The linkType and linkParams parameters are given to the LinkPolicyFactory to create a link policy

Link(const std::string &linkType, const std::string &linkParams, const std::string &srcRegionName, const std::string &destRegionName, const std::string &srcOutputName = "", const std::string &destInputName = "", const size_t propagationDelay = 0)

Initialization Phase 1: setting parameters of the link.

Parameters
  • linkType: The type of the link
  • linkParams: The parameters of the link
  • srcRegionName: The name of the source Region
  • destRegionName: The name of the destination Region
  • srcOutputName: The name of the source Output
  • destInputName: The name of the destination Input
  • propagationDelay: Propagation delay of the link as number of network run iterations involving the link as input; the delay vectors, if any, are initially populated with 0’s. Defaults to 0=no delay. Per design, data on no-delay links is to become available to destination inputs within the same time step, while data on delayed links (propagationDelay > 0) is to be updated “atomically” between time steps.

Link()

De-serialization use case.

Creates a “blank” link. The caller must follow up with Link::read and Link::connectToNetwork

Parameters
  • proto: LinkProto::Reader

void connectToNetwork(Output *src, Input *dest)

Initialization Phase 2: connecting inputs/outputs to the Network.

Parameters
  • src: The source Output of the link
  • dest: The destination Input of the link

void setSrcDimensions(Dimensions &dims)

Initialization Phase 3: set the Dimensions for the source Output, and induce the Dimensions for the destination Input .

Parameters

void setDestDimensions(Dimensions &dims)

Initialization Phase 3: Set the Dimensions for the destination Input, and induce the Dimensions for the source Output .

Parameters

void initialize(size_t destinationOffset)

Initialization Phase 4: sets the offset in the destination Input .

Parameters
  • destinationOffset: The offset in the destination Input, i.e. TODO

~Link()

Destructor.

Parameter getters of the link

const Dimensions &getSrcDimensions() const

Get the Dimensions for the source Output .

Return
The Dimensions for the source Output

const Dimensions &getDestDimensions() const

Get the Dimensions for the destination Input .

Return
The Dimensions for the destination Input

const std::string &getLinkType() const

Get the type of the link.

Return
The type of the link

const std::string &getLinkParams() const

Get the parameters of the link.

Return
The parameters of the link

const std::string &getSrcRegionName() const

Get the name of the source Region.

Return
The name of the source Region

const std::string &getSrcOutputName() const

Get the name of the source Output.

Return
The name of the source Output

const std::string &getDestRegionName() const

Get the name of the destination Region.

Return
The name of the destination Region

const std::string &getDestInputName() const

Get the name of the destination Input.

Return
The name of the destination Input

Misc

std::string getMoniker() const

Get a generated name of the link in the form RegName.outName > RegName.inName for debug logging purposes only.

Output &getSrc() const

Get the source Output of the link.

Return
The source Output of the link

Input &getDest() const

Get the destination Input of the link.

Return
The destination Input of the link

void compute()

Copy data from source to destination.

Nodes request input data from their input objects. The input objects, in turn, request links to copy data into the inputs.

Note
This method must be called on a fully initialized link(all 4 phases).

void buildSplitterMap(Input::SplitterMap &splitter)

Build a splitter map from the link.

A splitter map is a matrix that maps the full input of a region to the inputs of individual nodes within the region. A splitter map “sm” is declared as:

vector< vector<size_t> > sm;

sm.length() == number of nodes
Parameters
  • splitter: The built SplitterMap

sm[i] is a “sparse vector” used to gather the input for node i. sm[i].size() is the size (in elements) of the input for node i.

sm[i] gathers the inputs as follows:

T *regionInput; // input buffer for the whole region
T *nodeInput; // pre-allocated
for (size_t elem = 0; elem < sm[i].size; elem++)
   nodeInput[elem] = regionInput[sm[i][elem]];

The offset specified by sm[i][j] is in units of elements. To get byte offsets, you’d multiply by the size of an input/output element.

An input to a region may come from several links. Each link contributes a contiguous block of the region input starting from a certain offset. The splitter map indices are with respect to the full region input, not the partial region input contributed by this link, so the destinationOffset for this link is included in each of the splitter map entries.

Finally, the API is designed so that each link associated with an input can contribute its portion to a full splitter map. Thus the splitter map is an input-output parameter. This method appends data to each row of the splitter map, assuming that existing data in the splitter map comes from other links.

For region-level inputs, a splitter map has just a single row.

Splitter map ownership

The splitter map is owned by the containing Input. Each Link in the input contributes a portion to the splitter map, through the buildSplitterMap method.

const std::string toString() const

Convert the Link to a human-readable string.

Return
The human-readable string describing the Link

Serialize the link.

Parameters
  • f: The output stream being serialized to
  • link: The Link being serialized

class nupic::Input

Represents a named input to a Region.

(e.g. bottomUpIn)

Note
Input is not available in the public API, but is visible by the RegionImpl.

Public Types

typedef std::vector<std::vector<size_t>> SplitterMap

See
Link.buildSplitterMap()

Public Functions

Input(Region &region, NTA_BasicType type, bool isRegionLevel)

Constructor.

Parameters
  • region: The region that the input belongs to.
  • type: The type of the input, i.e. TODO
  • isRegionLevel: Whether the input is region level, i.e. TODO

~Input()

Destructor.

void setName(const std::string &name)

Set the name for the input.

Inputs need to know their own name for error messages.

Parameters
  • name: The name of the input

const std::string &getName() const

Get the name of the input.

Return
The name of the input

void addLink(Link *link, Output *srcOutput)

Add the given link to this input and to the list of links on the output.

Parameters
  • link: The link to add.
  • srcOutput: The output of previous Region, which is also the source of the input

Link *findLink(const std::string &srcRegionName, const std::string &srcOutputName)

Locate an existing Link to the input.

It’s called by Network.removeLink() and internally when adding a link

Return
The link if found or NULL if no such link exists
Parameters
  • srcRegionName: The name of the source Region
  • srcOutputName: The name of the source Output

Removing an existing link from the input.

It’s called in four cases:

  1. Network.removeLink()
  2. Network.removeRegion() when given srcRegion
  3. Network.removeRegion() when given destRegion
  4. Network.~Network()

It is an error to call this if our containing region is uninitialized.

Note
This method will set the Link pointer to NULL on return (to avoid a dangling reference)
Parameters
  • link: The Link to remove, possibly retrieved by findLink(), note that it is a reference to the pointer, not the pointer itself.

void prepare()

Make input data available.

Called by Region.prepareInputs()

const Array &getData() const

Get the data of the input.

Return
A mutable reference to the data of the input as an Array

Region &getRegion()

Get the Region that the input belongs to.

Return
The mutable reference to the Region that the input belongs to

const std::vector<Link *> &getLinks()

Get all the Link objects added to the input.

Return
All the Link objects added to the input

bool isRegionLevel()

Tells whether the input is region level.

Return
Whether the input is region level, i.e. TODO

size_t evaluateLinks()

Called by Region.evaluateLinks() as part of network initialization.

  1. Tries to make sure that dimensions at both ends of a link are specified by calling setSourceDimensions() if possible, and then calling getDestDimensions()
  2. Ensures that region dimensions are consistent with either by setting destination region dimensions (this is where links “induce” dimensions) or by raising an exception if they are inconsistent.

Return
Number of links that could not be fully evaluated, i.e. incomplete

void initialize()

Initialize the Input .

After the input has all the information it needs, it is initialized by this method. Volatile data structures (e.g. the input buffer) are set up。

bool isInitialized()

Tells whether the Input is initialized.

Return
Whether the Input is initialized

const SplitterMap &getSplitterMap() const

Get splitter map from an initialized input.

Return
The splitter map

template <typename T>
void getInputForNode(size_t nodeIndex, std::vector<T> &input) const

explicitly instantiated for various types

class nupic::Output

Represents a named output to a Region.

Public Functions

Output(Region &region, NTA_BasicType type, bool isRegionLevel)

Constructor.

Parameters
  • region: The region that the output belongs to.
  • type: The type of the output, TODO
  • isRegionLevel: Whether the output is region level, i.e. TODO

~Output()

Destructor.

void setName(const std::string &name)

Set the name for the output.

Output need to know their own name for error messages.

Parameters
  • name: The name of the output

const std::string &getName() const

Get the name of the output.

Return
The name of the output

void initialize(size_t size)

Initialize the Output .

Note
It’s safe to reinitialize an initialized Output with the same parameters.
Parameters
  • size: The count of node output element, i.e. TODO

Add a Link to the Output .

Called by Input.addLink()

Note
The Output does NOT take ownership of link, it’s created and owned by an Input Object.

Parameters
  • link: The Link to add

Removing an existing link from the output.

Note
Called only by Input.removeLink() even if triggered by Network.removeRegion() while removing the region that contains us.
Parameters
  • link: The Link to remove

bool hasOutgoingLinks()

Tells whether the output has outgoing links.

Note
We cannot delete a region if there are any outgoing links This allows us to check in Network.removeRegion() and Network.~Network().
Return
Whether the output has outgoing links

const Array &getData() const

Get the data of the output.

Return
A constant reference to the data of the output as an Array
Note
It’s mportant to return a const array so caller can’t reallocate the buffer.

bool isRegionLevel() const

Tells whether the output is region level.

Return
Whether the output is region level, i.e. TODO

Region &getRegion() const

Get the Region that the output belongs to.

Return
The mutable reference to the Region that the output belongs to

size_t getNodeOutputElementCount() const

Get the count of node output element.

Return
The count of node output element, previously set by initialize().