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.

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

name: Name of the Region

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.

construct with link type, params, names of regions and inputs/outputs
wire in to network (setting src and dest Output/Input pointers)
set source and destination dimensions
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

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

dims: The Dimensions for the source Output

void setDestDimensions(Dimensions &dims)¶

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

Parameters

dims: The Dimensions for the destination Input

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

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

std::ostream &operator<<(std::ostream &f, const Link &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

void removeLink(Link *&link)¶

Removing an existing link from the input.

It’s called in four cases:

Network.removeLink()
Network.removeRegion() when given srcRegion
Network.removeRegion() when given destRegion
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.

Tries to make sure that dimensions at both ends of a link are specified by calling setSourceDimensions() if possible, and then calling getDestDimensions()
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

void addLink(Link *link)¶

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

void removeLink(Link *link)¶

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().