Encoders¶
ScalarEncoder¶

class
nupic::algorithms::spatial_pooler::
SpatialPooler
¶ CLA spatial pooler implementation in C++.
Description
The Spatial Pooler is responsible for creating a sparse distributed representation of the input. Given an input it computes a set of sparse active columns and simultaneously updates its permanences, duty cycles, etc.
The primary public interfaces to this function are the “initialize” and “compute” methods.
Example usage:
SpatialPooler sp; sp.initialize(inputDimensions, columnDimensions, <parameters>); while (true) { <get input vector> sp.compute(inputVector, learn, activeColumns) <do something with output> }
Inherits from nupic::Serializable< SpatialPoolerProto >
Public Functions

virtual void
initialize
(vector<UInt> inputDimensions, vector<UInt> columnDimensions, UInt potentialRadius = 16, Real potentialPct = 0.5, bool globalInhibition = true, Real localAreaDensity = 1.0, UInt numActiveColumnsPerInhArea = 10, UInt stimulusThreshold = 0, Real synPermInactiveDec = 0.01, Real synPermActiveInc = 0.1, Real synPermConnected = 0.1, Real minPctOverlapDutyCycles = 0.001, UInt dutyCyclePeriod = 1000, Real boostStrength = 0.0, Int seed = 1, UInt spVerbosity = 0, bool wrapAround = true)¶ Initialize the spatial pooler using the given parameters.
 Parameters
inputDimensions
: A list of integers representing the dimensions of the input vector. Format is [height, width, depth, ...], where each value represents the size of the dimension. For a topology of one dimesion with 100 inputs use [100]. For a two dimensional topology of 10x5 use [10,5].columnDimensions
: A list of integers representing the dimensions of the columns in the region. Format is [height, width, depth, ...], where each value represents the size of the dimension. For a topology of one dimesion with 2000 columns use 2000, or [2000]. For a three dimensional topology of 32x64x16 use [32, 64, 16].potentialRadius
: This parameter deteremines the extent of the input that each column can potentially be connected to. This can be thought of as the input bits that are visible to each column, or a ‘receptive field’ of the field of vision. A large enough value will result in global coverage, meaning that each column can potentially be connected to every input bit. This parameter defines a square (or hyper square) area: a column will have a max square potential pool with sides of length (2 * potentialRadius + 1).potentialPct
: The percent of the inputs, within a column’s potential radius, that a column can be connected to. If set to 1, the column will be connected to every input within its potential radius. This parameter is used to give each column a unique potential pool when a large potentialRadius causes overlap between the columns. At initialization time we choose ((2*potentialRadius + 1)^(# inputDimensions) * potentialPct) input bits to comprise the column’s potential pool.globalInhibition
: If true, then during inhibition phase the winning columns are selected as the most active columns from the region as a whole. Otherwise, the winning columns are selected with resepct to their local neighborhoods. Global inhibition boosts performance significantly but there is no topology at the output.localAreaDensity
: The desired density of active columns within a local inhibition area (the size of which is set by the internally calculated inhibitionRadius, which is in turn determined from the average size of the connected potential pools of all columns). The inhibition logic will insure that at most N columns remain ON within a local inhibition area, where N = localAreaDensity * (total number of columns in inhibition area). If localAreaDensity is set to a negative value output sparsity will be determined by the numActivePerInhArea.numActiveColumnsPerInhArea
: An alternate way to control the sparsity of active columns. If numActivePerInhArea is specified then localAreaDensity must be less than 0, and vice versa. When numActivePerInhArea > 0, the inhibition logic will insure that at most ‘numActivePerInhArea’ columns remain ON within a local inhibition area (the size of which is set by the internally calculated inhibitionRadius). When using this method, as columns learn and grow their effective receptive fields, the inhibitionRadius will grow, and hence the net density of the active columns will decrease. This is in contrast to the localAreaDensity method, which keeps the density of active columns the same regardless of the size of their receptive fields.stimulusThreshold
: This is a number specifying the minimum number of synapses that must be active in order for a column to turn ON. The purpose of this is to prevent noisy input from activating columns.synPermInactiveDec
: The amount by which the permanence of an inactive synapse is decremented in each learning step.synPermActiveInc
: The amount by which the permanence of an active synapse is incremented in each round.synPermConnected
: The default connected threshold. Any synapse whose permanence value is above the connected threshold is a “connected synapse”, meaning it can contribute to the cell’s firing.minPctOverlapDutyCycles
: A number between 0 and 1.0, used to set a floor on how often a column should have at least stimulusThreshold active inputs. Periodically, each column looks at the overlap duty cycle of all other column within its inhibition radius and sets its own internal minimal acceptable duty cycle to: minPctDutyCycleBeforeInh * max(other columns’ duty cycles). On each iteration, any column whose overlap duty cycle falls below this computed value will get all of its permanence values boosted up by synPermActiveInc. Raising all permanences in response to a subpar duty cycle before inhibition allows a cell to search for new inputs when either its previously learned inputs are no longer ever active, or when the vast majority of them have been “hijacked” by other columns.dutyCyclePeriod
: The period used to calculate duty cycles. Higher values make it take longer to respond to changes in boost. Shorter values make it potentially more unstable and likely to oscillate.boostStrength
: A number greater or equal than 0, used to control boosting strength. No boosting is applied if it is set to 0. The strength of boosting increases as a function of boostStrength. Boosting encourages columns to have similar activeDutyCycles as their neighbors, which will lead to more efficient use of columns. However, too much boosting may also lead to instability of SP outputs.seed
: Seed for our random number generator. If seed is < 0 a randomly generated seed is used. The behavior of the spatial pooler is deterministic once the seed is set.spVerbosity
: spVerbosity level: 0, 1, 2, or 3wrapAround
: boolean value that determines whether or not inputs at the beginning and end of an input dimension are considered neighbors for the purpose of mapping inputs to columns.

virtual void
compute
(UInt inputVector[], bool learn, UInt activeVector[])¶ This is the main workshorse method of the SpatialPooler class.
This method takes an input vector and computes the set of output active columns. If ‘learn’ is set to True, this method also performs learning.
 Parameters
inputVector
: An array of integer 0’s and 1’s that comprises the input to the spatial pooler. The length of the array must match the total number of input bits implied by the constructor (also returned by the method getNumInputs). In cases where the input is multidimensional, inputVector is a flattened array of inputs.learn
: A boolean value indicating whether learning should be performed. Learning entails updating the permanence values of the synapses, duty cycles, etc. Learning is typically on but setting learning to ‘off’ is useful for analyzing the current state of the SP. For example, you might want to feed in various inputs and examine the resulting SDR’s. Note that if learning is off, boosting is turned off and columns that have never won will be removed from activeVector. TODO: we may want to keep boosting on even when learning is off.activeVector
: An array representing the winning columns after inhibition. The size of the array is equal to the number of columns (also returned by the method getNumColumns). This array will be populated with 1’s at the indices of the active columns, and 0’s everywhere else. In the case where the output is multidimensional, activeVector represents a flattened array of outputs.

void
stripUnlearnedColumns
(UInt activeArray[]) const¶ Removes the set of columns who have never been active from the set of active columns selected in the inhibition round.
Such columns cannot represent learned pattern and are therefore meaningless if only inference is required.
 Parameters
activeArray
: An array of 1’s and 0’s representing winning columns calculated by the ‘compute’ method after disabling any columns that are not learned.

virtual UInt
version
() const¶ Get the version number of this spatial pooler.
 Return
 Integer version number.

virtual void
save
(ostream &outStream) const¶ Save (serialize) the current state of the spatial pooler to the specified file.
 Parameters
fd
: A valid file descriptor.

virtual void
load
(istream &inStream)¶ Load (deserialize) and initialize the spatial pooler from the specified input stream.
 Parameters
inStream
: A valid istream.

virtual UInt
persistentSize
() const¶ Returns the number of bytes that a save operation would result in.
Note: this method is currently somewhat inefficient as it just does a full save into an ostream and counts the resulting size.
 Return
 Integer number of bytes

vector<UInt>
getColumnDimensions
() const¶ Returns the dimensions of the columns in the region.
 Return
 Integer number of column dimension.

vector<UInt>
getInputDimensions
() const¶ Returns the dimensions of the input vector.
 Return
 Integer vector of input dimension.

UInt
getNumColumns
() const¶ Returns the total number of columns.
 Return
 Integer number of column numbers.

UInt
getNumInputs
() const¶ Returns the total number of inputs.
 Return
 Integer number of inputs.

UInt
getPotentialRadius
() const¶ Returns the potential radius.
 Return
 Integer number of potential radius.

void
setPotentialRadius
(UInt potentialRadius)¶ Sets the potential radius.
 Parameters
potentialRadius
: integer number of potential raduis.

Real
getPotentialPct
() const¶ Returns the potential percent.
 Return
 real number of the potential percent.

void
setPotentialPct
(Real potentialPct)¶ Sets the potential percent.
 Parameters
potentialPct
: real number of potential percent.

bool
getGlobalInhibition
() const¶  Return
 boolen value of whether global inhibition is enabled.

void
setGlobalInhibition
(bool globalInhibition)¶ Sets global inhibition.
 Parameters
globalInhibition
: boolen varable of whether global inhibition is enabled.

Int
getNumActiveColumnsPerInhArea
() const¶ Returns the number of active columns per inhibition area.
 Return
 integer number of active columns per inhbition area, Returns a value less than 0 if parameter is unuse.

void
setNumActiveColumnsPerInhArea
(UInt numActiveColumnsPerInhArea)¶ Sets the number of active columns per inhibition area.
Invalidates the ‘localAreaDensity’ parameter.
 Parameters
numActiveColumnsPerInhArea
: integer number of active columns per inhibition area.

Real
getLocalAreaDensity
() const¶ Returns the local area density.
Returns a value less than 0 if parameter is unused”.
 Return
 real number of local area density.

void
setLocalAreaDensity
(Real localAreaDensity)¶ Sets the local area density.
Invalidates the ‘numActivePerInhArea’ parameter”.
 Parameters
localAreaDensity
: real number of local area density.

UInt
getStimulusThreshold
() const¶ Returns the stimulus threshold.
 Return
 integer number of stimulus threshold.

void
setStimulusThreshold
(UInt stimulusThreshold)¶ Sets the stimulus threshold.
 Parameters
stimulusThreshold
: (positive) integer number of stimulus threshold

UInt
getInhibitionRadius
() const¶ Returns the inhibition radius.
 Return
 (positive) integer of inhibition radius/

void
setInhibitionRadius
(UInt inhibitionRadius)¶ Sets the inhibition radius.
 Parameters
inhibitionRadius
: integer of inhibition radius.

UInt
getDutyCyclePeriod
() const¶ Returns the duty cycle period.
 Return
 integer of duty cycle period.

void
setDutyCyclePeriod
(UInt dutyCyclePeriod)¶ Sets the duty cycle period.
 Parameters
dutyCyclePeriod
: integer number of duty cycle period.

Real
getBoostStrength
() const¶ Returns the maximum boost value.
 Return
 real number of the maximum boost value.

void
setBoostStrength
(Real boostStrength)¶ Sets the strength of boost.
 Parameters
boostStrength
: real number of boosting strength, must be larger than 0.0

UInt
getIterationNum
() const¶ Returns the iteration number.
 Return
 integer number of iteration number.

void
setIterationNum
(UInt iterationNum)¶ Sets the iteration number.
 Parameters
iterationNum
: integer number of iteration number.

UInt
getIterationLearnNum
() const¶ Returns the learning iteration number.
 Return
 integer of the learning iteration number.

void
setIterationLearnNum
(UInt iterationLearnNum)¶ Sets the learning iteration number.
 Parameters
iterationLearnNum
: integer of learning iteration number.

UInt
getSpVerbosity
() const¶ Returns the verbosity level.
 Return
 integer of the verbosity level.

void
setSpVerbosity
(UInt spVerbosity)¶ Sets the verbosity level.
 Parameters
spVerbosity
: integer of verbosity level.

bool
getWrapAround
() const¶ Returns boolean value of wrapAround which indicates if receptive fields should wrap around from the beginning the input dimensions to the end.
 Return
 the boolean value of wrapAround.

void
setWrapAround
(bool wrapAround)¶ Sets wrapAround.
 Parameters
wrapAround
: boolean value

UInt
getUpdatePeriod
() const¶ Returns the update period.
 Return
 integer of update period.

void
setUpdatePeriod
(UInt updatePeriod)¶ Sets the update period.
 Parameters
updatePeriod
: integer of update period.

Real
getSynPermTrimThreshold
() const¶ Returns the permanence trim threshold.
 Return
 real number of the permanence trim threshold.

void
setSynPermTrimThreshold
(Real synPermTrimThreshold)¶ Sets the permanence trim threshold.
 Parameters
synPermTrimThreshold
: real number of the permanence trim threshold.

Real
getSynPermActiveInc
() const¶ Returns the permanence increment amount for active synapses inputs.
 Return
 real number of the permanence increment amount for active synapses inputs.

void
setSynPermActiveInc
(Real synPermActiveInc)¶ Sets the permanence increment amount for active synapses inputs.
 Parameters
synPermActiveInc
: real number of the permanence increment amount for active synapses inputs, must be >0.

Real
getSynPermInactiveDec
() const¶ Returns the permanence decrement amount for inactive synapses.
 Return
 real number of the permanence decrement amount for inactive synapses.

void
setSynPermInactiveDec
(Real synPermInactiveDec)¶ Returns the permanence decrement amount for inactive synapses.
 Parameters
synPermInactiveDec
: real number of the permanence decrement amount for inactive synapses.

Real
getSynPermBelowStimulusInc
() const¶ Returns the permanence increment amount for columns that have not been recently active.
 Return
 positive real number of the permanence increment amount for columns that have not been recently active.

void
setSynPermBelowStimulusInc
(Real synPermBelowStimulusInc)¶ Sets the permanence increment amount for columns that have not been recently active.
 Parameters
synPermBelowStimulusInc
: real number of the permanence increment amount for columns that have not been recently active, must be larger than 0.

Real
getSynPermConnected
() const¶ Returns the permanence amount that qualifies a synapse as being connected.
 Return
 real number of the permanence amount that qualifies a synapse as being connected.

void
setSynPermConnected
(Real synPermConnected)¶ Sets the permanence amount that qualifies a synapse as being connected.
 Parameters
synPermConnected
: real number of the permanence amount that qualifies a synapse as being connected.

Real
getSynPermMax
() const¶ Returns the maximum permanence amount a synapse can achieve.
 Return
 real number of the max permanence amount.

void
setSynPermMax
(Real synPermMax)¶ Sets the maximum permanence amount a synapse can achieve.
 Parameters
synPermCMax
: real number of the maximum permanence amount that a synapse can achieve.

Real
getMinPctOverlapDutyCycles
() const¶ Returns the minimum tolerated overlaps, given as percent of neighbors overlap score.
 Return
 real number of the minimum tolerated overlaps.

void
setMinPctOverlapDutyCycles
(Real minPctOverlapDutyCycles)¶ Sets the minimum tolerated overlaps, given as percent of neighbors overlap score.
 Parameters
minPctOverlapDutyCycles
: real number of the minimum tolerated overlaps.

void
getBoostFactors
(Real boostFactors[]) const¶ Returns the boost factors for all columns.
‘boostFactors’ size must match the number of columns.
 Parameters
boostFactors
: real array to store boost factors of all columns.

void
setBoostFactors
(Real boostFactors[])¶ Sets the boost factors for all columns.
‘boostFactors’ size must match the number of columns.
 Parameters
boostFactors
: real array of boost factors of all columns.

void
getOverlapDutyCycles
(Real overlapDutyCycles[]) const¶ Returns the overlap duty cycles for all columns.
‘overlapDutyCycles’ size must match the number of columns.
 Parameters
overlapDutyCycles
: real array to store overlap duty cycles for all columns.

void
setOverlapDutyCycles
(Real overlapDutyCycles[])¶ Sets the overlap duty cycles for all columns.
‘overlapDutyCycles’ size must match the number of columns.
 Parameters
overlapDutyCycles
: real array of the overlap duty cycles for all columns.

void
getActiveDutyCycles
(Real activeDutyCycles[]) const¶ Returns the activity duty cycles for all columns.
‘activeDutyCycles’ size must match the number of columns.
 Parameters
activeDutyCycles
: real array to store activity duty cycles for all columns.

void
setActiveDutyCycles
(Real activeDutyCycles[])¶ Sets the activity duty cycles for all columns.
‘activeDutyCycles’ size must match the number of columns.
 Parameters
activeDutyCycles
: real array of the activity duty cycles for all columns.

void
getMinOverlapDutyCycles
(Real minOverlapDutyCycles[]) const¶ Returns the minimum overlap duty cycles for all columns.
 Parameters
minOverlapDutyCycles
: real arry to store mininum overlap duty cycles for all columns. ‘minOverlapDutyCycles’ size must match the number of columns.

void
setMinOverlapDutyCycles
(Real minOverlapDutyCycles[])¶ Sets the minimum overlap duty cycles for all columns.
‘_minOverlapDutyCycles’ size must match the number of columns.
 Parameters
minOverlapDutyCycles
: real array of the minimum overlap duty cycles for all columns.

void
getPotential
(UInt column, UInt potential[]) const¶ Returns the potential mapping for a given column.
‘potential’ size must match the number of inputs.
 Parameters
column
: integer of column index.potential
: integer array of potential mapping for the selected column.

void
setPotential
(UInt column, UInt potential[])¶ Sets the potential mapping for a given column.
‘potential’ size must match the number of inputs.
 Parameters
column
: integer of column index.potential
: integer array of potential mapping for the selected column.

void
getPermanence
(UInt column, Real permanence[]) const¶ Returns the permanence values for a given column.
‘permanence’ size must match the number of inputs.
 Parameters
column
: integer of column index.permanence
: real array to store permanence values for the selected column.

void
setPermanence
(UInt column, Real permanence[])¶ Sets the permanence values for a given column.
‘permanence’ size must match the number of inputs.
 Parameters
column
: integer of column index.permanence
: real array of permanence values for the selected column.

void
getConnectedSynapses
(UInt column, UInt connectedSynapses[]) const¶ Returns the connected synapses for a given column.
‘connectedSynapses’ size must match the number of inputs.
 Parameters
column
: integer of column index.connectedSynapses
: integer array to store the connected synapses for a given column.

void
getConnectedCounts
(UInt connectedCounts[]) const¶ Returns the number of connected synapses for all columns.
‘connectedCounts’ size must match the number of columns.
 Parameters
connectedCounts
: integer array to store the connected synapses for all columns.

void
printParameters
() const¶ Print the main SP creation parameters to stdout.

const vector<UInt> &
getOverlaps
() const¶ Returns the overlap score for each column.

const vector<Real> &
getBoostedOverlaps
() const¶ Returns the boosted overlap score for each column.

UInt
mapColumn_
(UInt column)¶ Maps a column to its respective input index, keeping to the topology of the region.
It takes the index of the column as an argument and determines what is the index of the flattened input vector that is to be the center of the column’s potential pool. It distributes the columns over the inputs uniformly. The return value is an integer representing the index of the input bit. Examples of the expected output of this method: If the topology is one dimensional, and the column index is 0, this method will return the input index 0. If the column index is 1, and there are 3 columns over 7 inputs, this method will return the input index 3. If the topology is two dimensional, with column dimensions [3, 5] and input dimensions [7, 11], and the column index is 3, the method returns input index 8.
 Parameters
index
: The index identifying a column in the permanence, potential and connectivity matrices.wrapAround
: A boolean value indicating that boundaries should be ignored.

vector<UInt>
mapPotential_
(UInt column, bool wrapAround)¶ Maps a column to its input bits.
This method encapsultes the topology of the region. It takes the index of the column as an argument and determines what are the indices of the input vector that are located within the column’s potential pool. The return value is a list containing the indices of the input bits. The current implementation of the base class only supports a 1 dimensional topology of columns with a 1 dimensional topology of inputs. To extend this class to support 2D topology you will need to override this method. Examples of the expected output of this method: If the potentialRadius is greater than or equal to the entire input space, (global visibility), then this method returns an array filled with all the indices If the topology is one dimensional, and the potentialRadius is 5, this method will return an array containing 5 consecutive values centered on the index of the column (wrapping around if necessary). If the topology is two dimensional (not implemented), and the potentialRadius is 5, the method should return an array containing 25 ‘1’s, where the exact indices are to be determined by the mapping from 1D index to 2D position.
 Parameters
column
: An int index identifying a column in the permanence, potential and connectivity matrices.wrapAround
: A boolean value indicating that boundaries should be ignored.

Real
initPermConnected_
()¶ Returns a randomly generated permanence value for a synapses that is initialized in a connected state.
The basic idea here is to initialize permanence values very close to synPermConnected so that a small number of learning steps could make it disconnected or connected.
Note: experimentation was done a long time ago on the best way to initialize permanence values, but the history for this particular scheme has been lost.
 Return
 real number of a randomly generated permanence value for a synapses that is initialized in a connected state.

Real
initPermNonConnected_
()¶ Returns a randomly generated permanence value for a synapses that is to be initialized in a nonconnected state.
 Return
 real number of a randomly generated permanence value for a synapses that is to be initialized in a nonconnected state.

vector<Real>
initPermanence_
(vector<UInt> &potential, Real connectedPct)¶ Initializes the permanences of a column.
The method returns a 1D array the size of the input, where each entry in the array represents the initial permanence value between the input bit at the particular index in the array, and the column represented by the ‘index’ parameter.
corresponding to indices for which the mask value is 1.
 Parameters
potential
: A int vector specifying the potential pool of the column. Permanence values will only be generated for input bits
 Parameters
connectedPct
: A real value between 0 or 1 specifying the percent of the input bits that will start off in a connected state.

void
updatePermanencesForColumn_
(vector<Real> &perm, UInt column, bool raisePerm = true)¶ This method updates the permanence matrix with a column’s new permanence values.
The column is identified by its index, which reflects the row in the matrix, and the permanence is given in ‘dense’ form, i.e. a full array containing all the zeros as well as the nonzero values. It is in charge of implementing ‘clipping’  ensuring that the permanence values are always between 0 and 1  and ‘trimming’  enforcing sparsity by zeroing out all permanence values below ‘_synPermTrimThreshold’. It also maintains the consistency between ‘self._permanences’ (the matrix storing the permanence values), ‘self._connectedSynapses’, (the matrix storing the bits each column is connected to), and ‘self._connectedCounts’ (an array storing the number of input bits each column is connected to). Every method wishing to modify the permanence matrix should do so through this method.
 Parameters
perm
: An int vector of permanence values for a column. The array is “dense”, i.e. it contains an entry for each input bit, even if the permanence value is 0.column
: An int number identifying a column in the permanence, potential and connectivity matrices.raisePerm
: a boolean value indicating whether the permanence values should be raised until a minimum number are synapses are in a connected state. Should be set to ‘false’ when a direct assignment is required.

void
calculateOverlap_
(UInt inputVector[], vector<UInt> &overlap)¶ This function determines each column’s overlap with the current input vector.
The overlap of a column is the number of synapses for that column that are connected (permanence value is greater than ‘_synPermConnected’) to input bits which are turned on. The implementation takes advantage of the SparseBinaryMatrix class to perform this calculation efficiently.
 Parameters
inputVector
: a int array of 0’s and 1’s that comprises the input to the spatial pooler.overlap
: an int vector containing the overlap score for each column. The overlap score for a column is defined as the number of synapses in a “connected state” (connected synapses) that are connected to input bits which are turned on.

void
inhibitColumns_
(const vector<Real> &overlaps, vector<UInt> &activeColumns)¶ Performs inhibition.
This method calculates the necessary values needed to actually perform inhibition and then delegates the task of picking the active columns to helper functions.
 Parameters
overlaps
: an array containing the overlap score for each column. The overlap score for a column is defined as the number of synapses in a “connected state” (connected synapses) that are connected to input bits which are turned on.activeColumns
: an int array containing the indices of the active columns.

void
inhibitColumnsGlobal_
(const vector<Real> &overlaps, Real density, vector<UInt> &activeColumns)¶ Perform global inhibition.
Performing global inhibition entails picking the top ‘numActive’ columns with the highest overlap score in the entire region. At most half of the columns in a local neighborhood are allowed to be active. Columns with an overlap score below the ‘stimulusThreshold’ are always inhibited.
 Parameters
overlaps
: a real array containing the overlap score for each column. The overlap score for a column is defined as the number of synapses in a “connected state” (connected synapses) that are connected to input bits which are turned on.density
: a real number of the fraction of columns to survive inhibition.activeColumns
: an int array containing the indices of the active columns.

void
inhibitColumnsLocal_
(const vector<Real> &overlaps, Real density, vector<UInt> &activeColumns)¶ Performs local inhibition.
Local inhibition is performed on a column by column basis. Each column observes the overlaps of its neighbors and is selected if its overlap score is within the top ‘numActive’ in its local neighborhood. At most half of the columns in a local neighborhood are allowed to be active. Columns with an overlap score below the ‘stimulusThreshold’ are always inhibited.
 Parameters
overlaps
: an array containing the overlap score for each column. The overlap score for a column is defined as the number of synapses in a “connected state” (connected synapses) that are connected to input bits which are turned on.density
: The fraction of columns to survive inhibition. This value is only an intended target. Since the surviving columns are picked in a local fashion, the exact fraction of surviving columns is likely to vary.activeColumns
: an int array containing the indices of the active columns.

void
adaptSynapses_
(UInt inputVector[], vector<UInt> &activeColumns)¶ The primary method in charge of learning.
Adapts the permanence values of the synapses based on the input vector, and the chosen columns after inhibition round. Permanence values are increased for synapses connected to input bits that are turned on, and decreased for synapses connected to inputs bits that are turned off.
 Parameters
inputVector
: an int array of 0’s and 1’s that comprises the input to the spatial pooler. There exists an entry in the array for every input bit.activeColumns
: an int vector containing the indices of the columns that survived inhibition.

void
bumpUpWeakColumns_
()¶ This method increases the permanence values of synapses of columns whose activity level has been too low.
Such columns are identified by having an overlap duty cycle that drops too much below those of their peers. The permanence values for such columns are increased.

void
updateInhibitionRadius_
()¶ Update the inhibition radius.
The inhibition radius is a meausre of the square (or hypersquare) of columns that each a column is “connected to” on average. Since columns are not connected to each other directly, we determine this quantity by first figuring out how many inputs a column is connected to, and then multiplying it by the total number of columns that exist for each input. For multiple dimension the aforementioned calculations are averaged over all dimensions of inputs and columns. This value is meaningless if global inhibition is enabled.

Real
avgColumnsPerInput_
()¶ REturns the average number of columns per input, taking into account the topology of the inputs and columns.
This value is used to calculate the inhibition radius. This function supports an arbitrary number of dimensions. If the number of column dimensions does not match the number of input dimensions, we treat the missing, or phantom dimensions as ‘ones’.
 Return
 real number of the average number of columns per input.

Real
avgConnectedSpanForColumn1D_
(UInt column)¶ The range of connected synapses for column.
This is used to calculate the inhibition radius. This variation of the function only supports a 1 dimensional column topology.
 Parameters
column
: An int number identifying a column in the permanence, potential and connectivity matrices.

Real
avgConnectedSpanForColumn2D_
(UInt column)¶ The range of connectedSynapses per column, averaged for each dimension.
This vaule is used to calculate the inhibition radius. This variation of the function only supports a 2 dimensional column topology.
 Parameters
column
: An int number identifying a column in the permanence, potential and connectivity matrices.

Real
avgConnectedSpanForColumnND_
(UInt column)¶ The range of connectedSynapses per column, averaged for each dimension.
This vaule is used to calculate the inhibition radius. This variation of the function supports arbitrary column dimensions.
 Parameters
column
: An int number identifying a column in the permanence, potential and connectivity matrices.

void
updateMinDutyCycles_
()¶ Updates the minimum duty cycles defining normal activity for a column.
A column with activity duty cycle below this minimum threshold is boosted.

void
updateMinDutyCyclesGlobal_
()¶ Updates the minimum duty cycles in a global fashion.
Sets the minimum duty cycles for the overlap and activation of all columns to be a percent of the maximum in the region, specified by minPctOverlapDutyCycle and minPctActiveDutyCycle respectively. Functionally it is equivalent to _updateMinDutyCyclesLocal, but this function exploits the globalilty of the computation to perform it in a straightforward, and more efficient manner.

void
updateMinDutyCyclesLocal_
()¶ Updates the minimum duty cycles.
The minimum duty cycles are determined locally. Each column’s minimum duty cycles are set to be a percent of the maximum duty cycles in the column’s neighborhood. Unlike _updateMinDutyCycles

void
updateDutyCycles_
(vector<UInt> &overlaps, UInt activeArray[])¶ Updates the duty cycles for each column.
The OVERLAP duty cycle is a moving average of the number of inputs which overlapped with the each column. The ACTIVITY duty cycles is a moving average of the frequency of activation for each column.
 Parameters
overlaps
: an int vector containing the overlap score for each column. The overlap score for a column is defined as the number of synapses in a “connected state” (connected synapses) that are connected to input bits which are turned on.activeArray
: An int array containing the indices of the active columns, the sprase set of columns which survived inhibition

void
updateBoostFactors_
()¶ Update the boost factors for all columns.
The boost factors are used to increase the overlap of inactive columns to improve their chances of becoming active, and hence encourage participation of more columns in the learning process. The boosting function is a curve defined as: boostFactors = exp[  boostStrength * (dutyCycle  targetDensity)] Intuitively this means that columns that have been active at the target activation level have a boost factor of 1, meaning their overlap is not boosted. Columns whose active duty cycle drops too much below that of their neighbors are boosted depending on how infrequently they have been active. Columns that has been active more than the target activation level have a boost factor below 1, meaning their overlap is suppressed
The boostFactor depends on the activeDutyCycle via an exponential function:
boostFactor ^  \  \ 1 _  \  _  _ _  _ _ _ _ +> activeDutyCycle  targetDensity

void
updateBoostFactorsLocal_
()¶ Update boost factors when local inhibition is enabled.
In this case, the target activation level for each column is estimated as the average activation level for columns in its neighborhood.

void
updateBoostFactorsGlobal_
()¶ Update boost factors when global inhibition is enabled.
All columns share the same target activation level in this case, which is the sparsity of spatial pooler.

void
updateBookeepingVars_
(bool learn)¶ Updates counter instance variables each round.
 Parameters
learn
: a boolean value indicating whether learning should be performed. Learning entails updating the permanence values of the synapses, and hence modifying the ‘state’ of the model. setting learning to ‘off’ might be useful for indicating separate training vs. testing sets.

bool
isUpdateRound_
()¶  Return
 boolean value indicating whether enough rounds have passed to warrant updates of duty cycles

void
seed_
(UInt64 seed)¶ Initialize the random seed.
 Parameters
seed
: 64bit int of random seed

void
printState
(vector<UInt> &state)¶ Print the given UInt array in a nice format.

void
printState
(vector<Real> &state)¶ Print the given Real array in a nice format.
Public Static Functions

static void
updateDutyCyclesHelper_
(vector<Real> &dutyCycles, vector<UInt> &newValues, UInt period)¶ Updates a duty cycle estimate with a new value.
This is a helper function that is used to update several duty cycle variables in the Column class, such as: overlapDutyCucle, activeDutyCycle, minPctDutyCycleBeforeInh, minPctDutyCycleAfterInh, etc. returns the updated duty cycle. Duty cycles are updated according to the following formula:
(period  1)*dutyCycle + newValue dutyCycle :=  period
 Parameters
dutyCycles
: A real array containing one or more duty cycle values that need to be updated.newValues
: A int vector used to update the duty cycle.period
: A int number indicating the period of the duty cycle

virtual void
ScalarSensor¶

class
nupic::algorithms::connections::
Connections
¶ Connections implementation in C++.
Description The Connections class is a data structure that represents the connections of a collection of cells. It is used in the HTM learning algorithms to store and access data related to the connectivity of cells.
Its main utility is to provide a common, optimized data structure that all HTM learning algorithms can use. It is flexible enough to support any learning algorithm that operates on a collection of cells.
Each type of connection (proximal, distal basal, apical) should be represented by a different instantiation of this class. This class will help compute the activity along those connections due to active input cells. The responsibility for what effect that activity has on the cells and connections lies in the user of this class.
This class is optimized to store connections between cells, and compute the activity of cells due to input over the connections.
This class assigns each segment a unique “flatIdx” so that it’s possible to use a simple vector to associate segments with values. Create a vector of length
connections.segmentFlatListLength()
, iterate over segments and update the vector at indexsegment
.Inherits from nupic::Serializable< ConnectionsProto >
Public Functions

Connections
()¶ Connections empty constructor.
(Does not call
initialize
.)

Connections
(CellIdx numCells)¶ Connections constructor.
 Parameters
numCells
: Number of cells.

void
initialize
(CellIdx numCells)¶ Initialize connections.
 Parameters
numCells
: Number of cells.

Segment
createSegment
(CellIdx cell)¶ Creates a segment on the specified cell.
 Parameters
cell
: Cell to create segment on.
 Return Value
Created
: segment.

Synapse
createSynapse
(Segment segment, CellIdx presynapticCell, Permanence permanence)¶ Creates a synapse on the specified segment.
Created synapse.
 Parameters
segment
: Segment to create synapse on.presynapticCell
: Cell to synapse on.permanence
: Initial permanence of new synapse.

void
destroySegment
(Segment segment)¶ Destroys segment.
 Parameters
segment
: Segment to destroy.

void
destroySynapse
(Synapse synapse)¶ Destroys synapse.
 Parameters
synapse
: Synapse to destroy.

void
updateSynapsePermanence
(Synapse synapse, Permanence permanence)¶ Updates a synapse’s permanence.
 Parameters
synapse
: Synapse to update.permanence
: New permanence.

const std::vector<Segment> &
segmentsForCell
(CellIdx cell) const¶ Gets the segments for a cell.
 Parameters
cell
: Cell to get segments for.
 Return Value
Segments
: on cell.

const std::vector<Synapse> &
synapsesForSegment
(Segment segment) const¶ Gets the synapses for a segment.
 Parameters
segment
: Segment to get synapses for.
 Return Value
Synapses
: on segment.

CellIdx
cellForSegment
(Segment segment) const¶ Gets the cell that this segment is on.
 Parameters
segment
: Segment to get the cell for.
 Return Value
Cell
: that this segment is on.

SegmentIdx
idxOnCellForSegment
(Segment segment) const¶ Gets the index of this segment on its respective cell.
 Parameters
segment
: Segment to get the idx for.
 Return Value
Index
: of the segment.

void
mapSegmentsToCells
(const Segment *segments_begin, const Segment *segments_end, CellIdx *cells_begin) const¶ Get the cell for each provided segment.
 Parameters
segments
: The segments to querycells
: Output array with the same length as ‘segments’

Segment
segmentForSynapse
(Synapse synapse) const¶ Gets the segment that this synapse is on.
 Parameters
synapse
: Synapse to get Segment for.
 Return Value
Segment
: that this synapse is on.

const SegmentData &
dataForSegment
(Segment segment) const¶ Gets the data for a segment.
 Parameters
segment
: Segment to get data for.
 Return Value
Segment
: data.

const SynapseData &
dataForSynapse
(Synapse synapse) const¶ Gets the data for a synapse.
 Parameters
synapse
: Synapse to get data for.
 Return Value
Synapse
: data.

Segment
getSegment
(CellIdx cell, SegmentIdx idx) const¶ Get the segment at the specified cell and offset.
 Parameters
cell
: The cell that the segment is on.idx
: The index of the segment on the cell.
 Return Value
Segment
:

UInt32
segmentFlatListLength
() const¶ Get the vector length needed to use segments as indices.
 Return Value
A
: vector length

bool
compareSegments
(Segment a, Segment b) const¶ Compare two segments.
Returns true if a < b.
Segments are ordered first by cell, then by their order on the cell.
 Parameters
a
: Left segment to compareb
: Right segment to compare
 Return Value
true
: if a < b, false otherwise.

std::vector<Synapse>
synapsesForPresynapticCell
(CellIdx presynapticCell) const¶ Returns the synapses for the source cell that they synapse on.
 Return
 Synapse indices
 Parameters
presynapticCell(int)
: Source cell index

void
computeActivity
(std::vector<UInt32> &numActiveConnectedSynapsesForSegment, std::vector<UInt32> &numActivePotentialSynapsesForSegment, const std::vector<CellIdx> &activePresynapticCells, Permanence connectedPermanence) const¶ Compute the segment excitations for a vector of active presynaptic cells.
The output vectors aren’t grown or cleared. They must be preinitialized with the length returned by getSegmentFlatVectorLength().
 Parameters
numActiveConnectedSynapsesForSegment
: An output vector for active connected synapse counts per segment.numActivePotentialSynapsesForSegment
: An output vector for active potential synapse counts per segment.activePresynapticCells
: Active cells in the input.connectedPermanence
: Minimum permanence for a synapse to be “connected”.

void
computeActivity
(std::vector<UInt32> &numActiveConnectedSynapsesForSegment, std::vector<UInt32> &numActivePotentialSynapsesForSegment, CellIdx activePresynapticCell, Permanence connectedPermanence) const¶ Compute the segment excitations for a single active presynaptic cell.
The output vectors aren’t grown or cleared. They must be preinitialized with the length returned by getSegmentFlatVectorLength().
 Parameters
numActiveConnectedSynapsesForSegment
: An output vector for active connected synapse counts per segment.numActivePotentialSynapsesForSegment
: An output vector for active potential synapse counts per segment.activePresynapticCells
: Active cells in the input.connectedPermanence
: Minimum permanence for a synapse to be “connected”.

virtual void
save
(std::ostream &outStream) const¶ Saves serialized data to output stream.

virtual void
write
(ConnectionsProto::Builder &proto) const¶ Writes serialized data to proto object.

virtual void
load
(std::istream &inStream)¶ Loads serialized data from input stream.

virtual void
read
(ConnectionsProto::Reader &proto)¶ Reads serialized data from proto object.

CellIdx
numCells
() const¶ Gets the number of cells.
 Return Value
Number
: of cells.

UInt
numSegments
() const¶ Gets the number of segments.
 Return Value
Number
: of segments.

UInt
numSegments
(CellIdx cell) const¶ Gets the number of segments on a cell.
 Return Value
Number
: of segments.

UInt
numSynapses
() const¶ Gets the number of synapses.
 Return Value
Number
: of synapses.

UInt
numSynapses
(Segment segment) const¶ Gets the number of synapses on a segment.
 Return Value
Number
: of synapses.

bool
operator==
(const Connections &other) const¶ Comparison operator.

UInt32
subscribe
(ConnectionsEventHandler *handler)¶ Add a connections events handler.
The Connections instance takes ownership of the eventHandlers object. Don’t delete it. When calling from Python, call eventHandlers.__disown__() to avoid garbagecollecting the object while this instance is still using it. It will be deleted on
unsubscribe
. Parameters
handler
: An object implementing the ConnectionsEventHandler interface
 Return Value
Unsubscribe
: token

void
unsubscribe
(UInt32 token)¶ Remove an event handler.
 Parameters
token
: The return value ofsubscribe
.
