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 sub-par 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 3
  • wrapAround: 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 multi-dimensional, 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 multi-dimensional, 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 2-D 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 1-D index to 2-D 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 non-connected state.

Return
real number of a randomly generated permanence value for a synapses that is to be initialized in a non-connected state.

vector<Real> initPermanence_(vector<UInt> &potential, Real connectedPct)

Initializes the permanences of a column.

The method returns a 1-D 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 non-zero 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

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 index segment.flatIdx, and then recover the segments using connections.segmentForFlatIdx(i).

Inherits from nupic::Serializable< ConnectionsProto >

Public Functions

Connections()

Connections empty constructor.

(Does not call initialize.)

Connections(CellIdx numCells, SegmentIdx maxSegmentsPerCell = 255, SynapseIdx maxSynapsesPerSegment = 255)

Connections constructor.

Parameters
  • numCells: Number of cells.
  • maxSegmentsPerCell: Maximum number of segments per cell.
  • maxSynapsesPerSegment: Maximum number of synapses per segment.

void initialize(CellIdx numCells, SegmentIdx maxSegmentsPerCell, SynapseIdx maxSynapsesPerSegment)

Initialize connections.

Parameters
  • numCells: Number of cells.
  • maxSegmentsPerCell: Maximum number of segments per cell.
  • maxSynapsesPerSegment: Maximum number of synapses per segment.

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.

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:

Segment segmentForFlatIdx(UInt32 flatIdx) const

Do a reverse-lookup of a segment from its flatIdx.

Parameters
  • flatIdx: the flatIdx of the segment
Return Value
  • Segment:

UInt32 segmentFlatListLength() const

Get the vector length needed to use the segments’ flatIdx for indexing.

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 compare
  • b: 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”.

void recordSegmentActivity(Segment segment)

Record the fact that a segment had some activity.

This information is used during segment cleanup.

Parameters
  • segment: The segment that had some activity.

void startNewIteration()

Mark the passage of time.

This information is used during segment cleanup.

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 garbage-collecting 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 of subscribe.