nengo_spa.networks

Basic networks that are used by NengoSPA.

These networks do not provide any information about inputs, outputs or used vocabularies and are completely independent of SPA specifics.

CircularConvolution(n_neurons, dimensions[, …])

Compute the circular convolution of two vectors.

IdentityEnsembleArray(neurons_per_dimension, …)

An ensemble array optimized for representing the identity circular convolution vector besides random unit vectors.

MatrixMult(n_neurons, shape_left, …)

Computes the matrix product A*B.

VTB(n_neurons, dimensions[, unbind_left, …])

Compute vector-derived transformation binding (VTB).

TVTB(n_neurons, dimensions[, unbind_left, …])

Compute transposed vector-derived transformation binding (TVTB).

Selection networks

selection.IA(n_neurons, n_ensembles[, …])

Independent accumulator (IA) winner-take-all (WTA) network.

selection.Thresholding(n_neurons, …[, …])

Array of thresholding ensembles.

selection.WTA(n_neurons, n_ensembles[, …])

Winner-take-all (WTA) network with lateral inhibition.

class nengo_spa.networks.CircularConvolution(n_neurons, dimensions, invert_a=False, invert_b=False, input_magnitude=1.0, **kwargs)[source]

Compute the circular convolution of two vectors.

The circular convolution \(c\) of vectors \(a\) and \(b\) is given by

\[c[i] = \sum_j a[j] b[i - j]\]

where negative indices on \(b\) wrap around to the end of the vector.

This computation can also be done in the Fourier domain,

\[c = DFT^{-1} ( DFT(a) \odot DFT(b) )\]

where \(DFT\) is the Discrete Fourier Transform operator, and \(DFT^{-1}\) is its inverse. This network uses this method.

Parameters
  • n_neurons (int) – Number of neurons to use in each product computation.

  • dimensions (int) – The number of dimensions of the input and output vectors.

  • invert_a (bool, optional) – Whether to reverse the order of elements in first input.

  • invert_b (bool, optional) – Whether to reverse the order of elements in the second input. Flipping exactly one input will make the network perform circular correlation instead of circular convolution which can be treated as an approximate inverse to circular convolution.

  • input_magnitude (float, optional) – The expected magnitude of the vectors to be convolved. This value is used to determine the radius of the ensembles computing the element-wise product.

  • **kwargs (dict) – Keyword arguments to pass through to the nengo.Network constructor.

input_a

The first vector to be convolved.

Type

nengo.Node

input_b

The second vector to be convolved.

Type

nengo.Node

product

Network created to do the element-wise product of the \(DFT\) components.

Type

nengo.networks.Product

output

The resulting convolved vector.

Type

nengo.Node

Examples

A basic example computing the circular convolution of two 10-dimensional vectors represented by ensemble arrays:

A = EnsembleArray(50, n_ensembles=10)
B = EnsembleArray(50, n_ensembles=10)
C = EnsembleArray(50, n_ensembles=10)
cconv = nengo_spa.networks.CircularConvolution(50, dimensions=10)
nengo.Connection(A.output, cconv.input_a)
nengo.Connection(B.output, cconv.input_b)
nengo.Connection(cconv.output, C.input)

Notes

The network maps the input vectors \(a\) and \(b\) of length \(N\) into the Fourier domain and aligns them for complex multiplication. Letting \(F = DFT(a)\) and \(G = DFT(b)\), this is given by:

[ F[i].real ]     [ G[i].real ]     [ w[i] ]
[ F[i].imag ]  *  [ G[i].imag ]  =  [ x[i] ]
[ F[i].real ]     [ G[i].imag ]     [ y[i] ]
[ F[i].imag ]     [ G[i].real ]     [ z[i] ]

where \(i\) only ranges over the lower half of the spectrum, since the upper half of the spectrum is the flipped complex conjugate of the lower half, and therefore redundant. The input transforms are used to perform the DFT on the inputs and align them correctly for complex multiplication.

The complex product \(H = F * G\) is then

\[H[i] = (w[i] - x[i]) + (y[i] + z[i]) I\]

where \(I = \sqrt{-1}\). We can perform this addition along with the inverse DFT \(c = DFT^{-1}(H)\) in a single output transform, finding only the real part of \(c\) since the imaginary part is analytically zero.

class nengo_spa.networks.IdentityEnsembleArray(neurons_per_dimension, dimensions, subdimensions, **kwargs)[source]

An ensemble array optimized for representing the identity circular convolution vector besides random unit vectors.

The ensemble array will use ensembles with subdimensions dimensions, except for the first subdimensions dimensions. These will be split into a one-dimensional ensemble for the first dimension and a subdimensions-1 dimensional ensemble.

Parameters
  • neurons_per_dimension (int) – Neurons per dimension.

  • dimensions (int) – Total number of dimensions. Must be a multiple of subdimensions.

  • subdimensions (int) – Maximum number of dimensions per ensemble.

  • **kwargs (dict) – Keyword arguments to pass through to the nengo.Network constructor.

input

Input node.

Type

nengo.Node

output

Output node.

Type

nengo.Node

add_neuron_input()[source]

Adds a node providing input to the neurons of all ensembles.

This node will be accessible through the neuron_input attribute.

Returns

The added node.

Return type

nengo.Node

add_neuron_output()[source]

Adds a node providing neuron (non-decoded) output of all ensembles.

This node will be accessible through the neuron_output attribute.

Returns

The added node.

Return type

nengo.Node

add_output(name, function, synapse=None, **conn_kwargs)[source]

Adds a new decoded output.

This will add the attribute named name to the object.

Parameters
  • name (str) – Name of output. Must be a valid Python attribute name.

  • function (func) – Function to decode.

  • synapse (float or nengo.Lowpass) – Synapse to apply to the decoded connection to the returned output node.

  • conn_kwargs (dict) – Additional keywword arguments to apply to the decoded connection.

Returns

Node providing the decoded output.

Return type

nengo.Node

class nengo_spa.networks.MatrixMult(n_neurons, shape_left, shape_right, **kwargs)[source]

Computes the matrix product A*B.

Both matrices need to be two dimensional.

See the Nengo Matrix Multiplication example for a description of the network internals.

Parameters
  • n_neurons (int) –

    Number of neurons used per product of two scalars.

    Note

    If an odd number of neurons is given, one less neuron will be used per product to obtain an even number. This is due to the implementation the Product network.

  • shape_left (tuple) – Shape of the A input matrix.

  • shape_right (tuple) – Shape of the B input matrix.

  • **kwargs (dict) – Keyword arguments to pass through to the nengo.Network constructor.

input_left

The left matrix (A) to multiply.

Type

nengo.Node

input_right

The left matrix (A) to multiply.

Type

nengo.Node

C

The product network doing the matrix multiplication.

Type

nengo.networks.Product

output

The resulting matrix result.

Type

nengo.node

class nengo_spa.networks.TVTB(n_neurons, dimensions, unbind_left=False, unbind_right=False, **kwargs)[source]

Compute transposed vector-derived transformation binding (TVTB).

VTB uses elementwise addition for superposition. The binding operation \(\mathcal{B}(x, y)\) is defined as

\[\begin{split}\mathcal{B}(x, y) := V_y^T x = \left[\begin{array}{ccc} V_y'^T & 0 & 0 \\ 0 & V_y'^T & 0 \\ 0 & 0 & V_y'^T \end{array}\right] x\end{split}\]

with

\[\begin{split}V_y' = d^{\frac{1}{4}} \left[\begin{array}{cccc} y_1 & y_2 & \dots & y_{d'} \\ y_{d' + 1} & y_{d' + 2} & \dots & y_{2d'} \\ \vdots & \vdots & \ddots & \vdots \\ y_{d - d' + 1} & y_{d - d' + 2} & \dots & y_d \end{array}\right]\end{split}\]

and

\[d'^2 = d.\]

The approximate inverse \(y^+\) for \(y\) is permuting the elements such that \(V_{y^+} = V_y^T\).

Note that TVTB requires the vector dimensionality to be square.

The TVTB binding operation is neither associative nor commutative. In contrast to VTB, however, TVTB has two-sided identities and inverses. Other properties are equivalent to VTB.

See also

VtbAlgebra, VTB

Parameters
  • n_neurons (int) – Number of neurons to use in each product computation.

  • dimensions (int) – The number of dimensions of the input and output vectors. Needs to be a square number.

  • unbind_left (bool) – Whether to unbind the left input vector from the right input vector.

  • unbind_right (bool) – Whether to unbind the right input vector from the left input vector.

  • **kwargs (dict) – Keyword arguments to pass through to the nengo.Network constructor.

input_left

The left operand vector to be bound.

Type

nengo.Node

input_right

The right operand vector to be bound.

Type

nengo.Node

mat

Representation of the matrix \(V_y'\).

Type

nengo.Node

vec

Representation of the vector \(y\).

Type

nengo.Node

matmuls

Matrix multiplication networks.

Type

list

output

The resulting bound vector.

Type

nengo.Node

class nengo_spa.networks.VTB(n_neurons, dimensions, unbind_left=False, unbind_right=False, **kwargs)[source]

Compute vector-derived transformation binding (VTB).

VTB uses elementwise addition for superposition. The binding operation \(\mathcal{B}(x, y)\) is defined as

\[\begin{split}\mathcal{B}(x, y) := V_y x = \left[\begin{array}{ccc} V_y' & 0 & 0 \\ 0 & V_y' & 0 \\ 0 & 0 & V_y' \end{array}\right] x\end{split}\]

with

\[\begin{split}V_y' = d^{\frac{1}{4}} \left[\begin{array}{cccc} y_1 & y_2 & \dots & y_{d'} \\ y_{d' + 1} & y_{d' + 2} & \dots & y_{2d'} \\ \vdots & \vdots & \ddots & \vdots \\ y_{d - d' + 1} & y_{d - d' + 2} & \dots & y_d \end{array}\right]\end{split}\]

and

\[d'^2 = d.\]

The approximate inverse \(y^+\) for \(y\) is permuting the elements such that \(V_{y^+} = V_y^T\).

Note that VTB requires the vector dimensionality to be square.

The VTB binding operation is neither associative nor commutative. Furthermore, there are right inverses and identities only. By transposing the \(V_y\) matrix, the closely related TvtbAlgebra (Transposed VTB) algebra is obtained which does have two-sided identities and inverses.

Additional information about VTB can be found in

See also

TvtbAlgebra, TVTB

Parameters
  • n_neurons (int) – Number of neurons to use in each product computation.

  • dimensions (int) – The number of dimensions of the input and output vectors. Needs to be a square number.

  • unbind_left (bool) – Whether to unbind the left input vector from the right input vector.

  • unbind_right (bool) – Whether to unbind the right input vector from the left input vector.

  • **kwargs (dict) – Keyword arguments to pass through to the nengo.Network constructor.

input_left

The left operand vector to be bound.

Type

nengo.Node

input_right

The right operand vector to be bound.

Type

nengo.Node

mat

Representation of the matrix \(V_y'\).

Type

nengo.Node

vec

Representation of the vector \(y\).

Type

nengo.Node

matmuls

Matrix multiplication networks.

Type

list

output

The resulting bound vector.

Type

nengo.Node

nengo_spa.networks.selection

Selection networks that pick one or more options among multiple choices.

class nengo_spa.networks.selection.IA(n_neurons, n_ensembles, accum_threshold=0.8, accum_neuron_ratio=0.7, accum_timescale=0.2, feedback_timescale=0.005, accum_synapse=0.1, ff_synapse=0.005, intercept_width=0.15, radius=1.0, **kwargs)[source]

Independent accumulator (IA) winner-take-all (WTA) network.

This is a two-layered network. The first layer consists of independent accumulators (integrators), whereas the second layer does a thresholding. Once the threshold is exceeded a feedback connection will stabilize the current choice and inhibit all other choices. To switch the selection, it is necessary to provide a transient input to input_reset to reset the accumulator states.

This network is suited especially for accumulating evidence under noisy conditions and keep a stable choice selection until the processing of the choice has been finished.

Further details are to be found in [gosmann2017].

Parameters
  • n_neurons (int) – Number of neurons for each choice.

  • n_ensembles (int) – Number of choices.

  • accum_threshold (float, optional) – Accumulation threshold that needs to be reached to produce an output.

  • accum_neuron_ratio (float, optional) – Portion of n_neurons that will be used for a layer 1 accumulator ensemble. The remaining neurons will be used for a layer 2 thresholding ensemble.

  • accum_timescale (float, optional) – Evidence accumulation timescale.

  • feedback_timescale (float, optional) – Timescale for the feedback connection from the thresholding layer to the accumulation layer.

  • accum_synapse (Synapse or float, optional) – The synapse for connections to the accumulator ensembles.

  • ff_synapse (Synapse or float, optional) – Synapse for feed-forward connections.

  • intercept_width (float, optional) – The nengo.presets.ThresholdingEnsembles intercept_width parameter.

  • radius (float, optional) – The representational radius of the ensembles.

  • **kwargs (dict) – Keyword arguments passed on to nengo.Network.

input

The inputs to the network.

Type

nengo.Node

input_reset

Input to reset the accumulators.

Type

nengo.Node

output

The outputs of the network.

Type

nengo.Node

accumulators

The layer 1 accumulators.

Type

nengo.Thresholding

thresholding

The layer 2 thresholding ensembles.

Type

nengo.Thresholding

References

gosmann2017

Jan Gosmann, Aaron R. Voelker, and Chris Eliasmith. “A spiking independent accumulator model for winner-take-all computation.” In Proceedings of the 39th Annual Conference of the Cognitive Science Society. London, UK, 2017. Cognitive Science Society.

class nengo_spa.networks.selection.Thresholding(n_neurons, n_ensembles, threshold, intercept_width=0.15, function=None, radius=1.0, **kwargs)[source]

Array of thresholding ensembles.

All inputs below the threshold will produce an output of 0, whereas inputs above the threshold produce an output of equal value.

Parameters
  • n_neurons (int) – Number of neurons for each ensemble.

  • n_ensembles (int) – Number of ensembles.

  • threshold (float) – The thresholding value.

  • intercept_width (float, optional) – The nengo.presets.ThresholdingEnsembles intercept_width parameter.

  • function (function, optional) – Function to apply to the thresholded values.

  • radius (float, optional) – The representational radius of the ensembles.

  • **kwargs (dict) – Keyword arguments passed on to nengo.Network.

input

The inputs to the network.

Type

nengo.Node

output

The outputs of the network.

Type

nengo.Node

thresholded

The raw thresholded value (before applying function or correcting for the shift produced by the thresholding).

Type

nengo.Node

class nengo_spa.networks.selection.WTA(n_neurons, n_ensembles, inhibit_scale=1.0, inhibit_synapse=0.005, **kwargs)[source]

Winner-take-all (WTA) network with lateral inhibition.

Parameters
  • n_neurons (int) – Number of neurons for each ensemble.

  • n_ensembles (int) – Number of ensembles.

  • inhibit_scale (float, optional) – Scaling of the lateral inhibition.

  • inhibit_synapse (Synapse or float, optional) – Synapse on the recurrent connection for lateral inhibition.

  • **kwargs (dict) – Keyword arguments passed on to Thresholding.

input

The inputs to the network.

Type

nengo.Node

output

The outputs of the network.

Type

nengo.Node

thresholded

The raw thresholded value (before applying function or correcting for the shift produced by the thresholding).

Type

nengo.Node