NuPIC Core
Core algorithms for NuPIC(the Numenta Platform for Intelligent Computing), implemented in C++
 All Classes Namespaces Files Functions Typedefs Enumerations Enumerator Friends Pages
List of all members
nta::Link Class Reference

Represents a link between regions in a Network. More...

#include <Link.hpp>

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

Todo:
Should LinkPolicyFactory be documented?
 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="")
 Initialization Phase 1: setting parameters of the link. More...
 
void connectToNetwork (Output *src, Input *dest)
 Initialization Phase 2: connecting inputs/outputs to the Network. More...
 
 Link (const std::string &linkType, const std::string &linkParams, Output *srcOutput, Input *destInput)
 
void setSrcDimensions (Dimensions &dims)
 Initialization Phase 3: set the Dimensions for the source Output, and induce the Dimensions for the destination Input . More...
 
void setDestDimensions (Dimensions &dims)
 Initialization Phase 3: Set the Dimensions for the destination Input, and induce the Dimensions for the source Output . More...
 
void initialize (size_t destinationOffset)
 Initialization Phase 4: sets the offset in the destination Input . More...
 
 ~Link ()
 Destructor.
 

Parameter getters of the link

const DimensionsgetSrcDimensions () const
 Get the Dimensions for the source Output . More...
 
const DimensionsgetDestDimensions () const
 Get the Dimensions for the destination Input . More...
 
const std::string & getLinkType () const
 Get the type of the link. More...
 
const std::string & getLinkParams () const
 Get the parameters of the link. More...
 
const std::string & getSrcRegionName () const
 Get the name of the source Region. More...
 
const std::string & getSrcOutputName () const
 Get the name of the source Output. More...
 
const std::string & getDestRegionName () const
 Get the name of the destination Region. More...
 
const std::string & getDestInputName () const
 Get the name of the destination Input. More...
 

Misc

OutputgetSrc () const
 Get the source Output of the link. More...
 
InputgetDest () const
 Get the destination Input of the link. More...
 
void compute ()
 Copy data from source to destination. More...
 
void buildSplitterMap (Input::SplitterMap &splitter)
 Build a splitter map from the link. More...
 
const std::string toString () const
 Convert the Link to a human-readable string. More...
 
std::ostream & operator<< (std::ostream &f, const Link &link)
 Serialize the link. More...
 

Not implemented

size_t getNodeInputSize (size_t nodeIndex)
 Get the size of the input contributed by this link for a single node. More...
 
bool isInputContiguous ()
 Tells whether the Input is contiguous. More...
 
size_t getInputOffset (size_t nodeIndex)
 Locate the contiguous input for a node. More...
 

Detailed Description

Represents a link between regions in a Network.

Definition at line 49 of file Link.hpp.

Constructor & Destructor Documentation

nta::Link::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 = "" 
)

Initialization Phase 1: setting parameters of the link.

Parameters
linkTypeThe type of the link
linkParamsThe parameters of the link
srcRegionNameThe name of the source Region
destRegionNameThe name of the destination Region
srcOutputNameThe name of the source Output
destInputNameThe name of the destination Input

Member Function Documentation

void nta::Link::buildSplitterMap ( Input::SplitterMap splitter)

Build a splitter map from the link.

Parameters
[out]splitterThe built SplitterMap

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

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.

void nta::Link::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 nta::Link::connectToNetwork ( Output src,
Input dest 
)

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

Parameters
srcThe source Output of the link
destThe destination Input of the link
Input& nta::Link::getDest ( ) const

Get the destination Input of the link.

Returns
The destination Input of the link
const Dimensions& nta::Link::getDestDimensions ( ) const

Get the Dimensions for the destination Input .

Returns
The Dimensions for the destination Input
const std::string& nta::Link::getDestInputName ( ) const

Get the name of the destination Input.

Returns
The name of the destination Input
const std::string& nta::Link::getDestRegionName ( ) const

Get the name of the destination Region.

Returns
The name of the destination Region
size_t nta::Link::getInputOffset ( size_t  nodeIndex)

Locate the contiguous input for a node.

This method is used only if the input is contiguous

Parameters
nodeIndexThe index of the node
Returns
The Input offset of the node
Todo:
not implemented; necessary?
const std::string& nta::Link::getLinkParams ( ) const

Get the parameters of the link.

Returns
The parameters of the link
const std::string& nta::Link::getLinkType ( ) const

Get the type of the link.

Returns
The type of the link
size_t nta::Link::getNodeInputSize ( size_t  nodeIndex)

Get the size of the input contributed by this link for a single node.

Parameters
nodeIndexThe index of the node
Returns
The size of the input contributed by this link for a single node.
Todo:
index=-1 for region-level input?
Todo:
not implemented; necessary?
Output& nta::Link::getSrc ( ) const

Get the source Output of the link.

Returns
The source Output of the link
const Dimensions& nta::Link::getSrcDimensions ( ) const

Get the Dimensions for the source Output .

Returns
The Dimensions for the source Output
const std::string& nta::Link::getSrcOutputName ( ) const

Get the name of the source Output.

Returns
The name of the source Output
const std::string& nta::Link::getSrcRegionName ( ) const

Get the name of the source Region.

Returns
The name of the source Region
void nta::Link::initialize ( size_t  destinationOffset)

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

Parameters
destinationOffsetThe offset in the destination Input, i.e. TODO
bool nta::Link::isInputContiguous ( )

Tells whether the Input is contiguous.

Returns
Whether the Input is contiguous, i.e. TODO

If the input for a particular node is a contiguous subset of the src output, then the splitter map is overkill, and all we need to know is the offset/size (per node) Returns true if and only if the input for each node is a contiguous chunk of the input buffer.

Todo:
not implemented; necessary?
void nta::Link::setDestDimensions ( Dimensions dims)

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

Parameters
dimsThe Dimensions for the destination Input
void nta::Link::setSrcDimensions ( Dimensions dims)

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

Parameters
dimsThe Dimensions for the source Output
const std::string nta::Link::toString ( ) const

Convert the Link to a human-readable string.

Returns
The human-readable string describing the Link

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  f,
const Link link 
)
friend

Serialize the link.

Parameters
fThe output stream being serialized to
linkThe Link being serialized

The documentation for this class was generated from the following file: