Reusable networks

Networks are an abstraction of a grouping of Nengo objects (i.e., Node, Ensemble, Connection, and Network instances, though usually not Probe instances.) Like most abstractions, this helps with code-reuse and maintainability. You’ll find the documentation for the reusable networks included with Nengo below.

You may also want to build your own reusable networks. Doing so can help encapsulate parts of your model, making your code easier to understand, easier to re-use, and easier to share. The following examples will help you build your own reusable networks:

You may also find the config system documentation useful.

Built-in networks

nengo.networks.EnsembleArray

An array of ensembles.

nengo.networks.BasalGanglia

Winner take all network, typically used for action selection.

nengo.networks.Thalamus

Inhibits non-selected actions.

nengo.networks.AssociativeMemory

Associative memory network.

nengo.networks.CircularConvolution

Compute the circular convolution of two vectors.

nengo.networks.Integrator

An ensemble that accumulates input and maintains state.

nengo.networks.Oscillator

A two-dimensional ensemble with interacting recurrent connections.

nengo.networks.Product

Computes the element-wise product of two equally sized vectors.

nengo.networks.InputGatedMemory

Stores a given vector in memory, with input controlled by a gate.

class nengo.networks.EnsembleArray(n_neurons, n_ensembles, ens_dimensions=1, label=None, seed=None, add_to_container=None, **ens_kwargs)[source]

An array of ensembles.

This acts, in some ways, like a single high-dimensional ensemble, but actually consists of many sub-ensembles, each one representing a separate dimension. This tends to be much faster to create and can be more accurate than having one huge high-dimensional ensemble. However, since the neurons represent different dimensions separately, we cannot compute nonlinear interactions between those dimensions.

Note that in addition to the parameters below, parameters affecting all of the sub-ensembles can be passed to the ensemble array. For example:

ea = nengo.networks.EnsembleArray(20, 2, radius=1.5)

creates an ensemble array with 2 sub-ensembles, each with 20 neurons, and a radius of 1.5.

Parameters
n_neuronsint

The number of neurons in each sub-ensemble.

n_ensemblesint

The number of sub-ensembles to create.

ens_dimensionsint, optional

The dimensionality of each sub-ensemble.

labelstr, optional

A name to assign this EnsembleArray. Used for visualization and debugging.

seedint, optional

Random number seed that will be used in the build step.

add_to_containerbool, optional

Determines if this network will be added to the current container. If None, this network will be added to the network at the top of the Network.context stack unless the stack is empty.

Attributes
dimensions_per_ensembleint

The dimensionality of each sub-ensemble.

ea_ensembleslist

The sub-ensembles in the ensemble array.

inputNode

A node that provides input to all of the ensembles in the array.

n_ensemblesint

The number of sub-ensembles to create.

n_neurons_per_ensembleint

The number of neurons in each sub-ensemble.

neuron_inputNode or None

A node that provides input to all the neurons in the ensemble array. None unless created in add_neuron_input.

neuron_outputNode or None

A node that gathers neural output from all the neurons in the ensemble array. None unless created in add_neuron_output.

outputNode

A node that gathers decoded output from all of the ensembles in the array.

property dimensions

(int) Dimensionality of the ensemble array.

add_neuron_input(self)[source]

Adds a node that provides input to the neurons of all ensembles.

Direct neuron input is useful for inhibiting the activity of all neurons in the ensemble array.

This node is accessible through the ‘neuron_input’ attribute of this ensemble array.

add_neuron_output(self)[source]

Adds a node that collects the neural output of all ensembles.

Direct neuron output is useful for plotting the spike raster of all neurons in the ensemble array.

This node is accessible through the ‘neuron_output’ attribute of this ensemble array.

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

Adds a node that collects the decoded output of all ensembles.

By default, this is called once in __init__ with function=None. However, this can be called multiple times with different functions, similar to the way in which an ensemble can be connected to many downstream ensembles with different functions.

Note that in addition to the parameters below, parameters affecting all of the connections from the sub-ensembles to the new node can be passed to this function. For example:

ea.add_output('output', None, solver=nengo.solvers.Lstsq())

creates a new output with the decoders of each connection solved for with the Lstsq solver.

Parameters
namestr

The name of the output. This will also be the name of the attribute set on the ensemble array.

functioncallable or iterable of callables

The function to compute across the connection from sub-ensembles to the new output node. If function is an iterable, it must be an iterable consisting of one function for each sub-ensemble.

synapseSynapse, optional

The synapse model with which to filter the connections from sub-ensembles to the new output node. This is kept separate from the other conn_kwargs because this defaults to None rather than the default synapse model. In almost all cases the synapse should stay as None, and synaptic filtering should be performed in the connection from the output node.

class nengo.networks.BasalGanglia(dimensions, n_neurons_per_ensemble=100, output_weight=- 3.0, input_bias=0.0, ampa_config=None, gaba_config=None, **kwargs)[source]

Winner take all network, typically used for action selection.

The basal ganglia network outputs approximately 0 at the dimension with the largest value, and is negative elsewhere.

While the basal ganglia is primarily defined by its winner-take-all function, it is also organized to match the organization of the human basal ganglia. It consists of five ensembles:

  • Striatal D1 dopamine-receptor neurons (strD1)

  • Striatal D2 dopamine-receptor neurons (strD2)

  • Subthalamic nucleus (stn)

  • Globus pallidus internus / substantia nigra reticulata (gpi)

  • Globus pallidus externus (gpe)

Interconnections between these areas are also based on known neuroanatomical connections. See [1] for more details, and [2] for the original non-spiking basal ganglia model by Gurney, Prescott & Redgrave that this model is based on.

Note

The default Solver for the basal ganglia is NnlsL2nz, which requires SciPy. If SciPy is not installed, the global default solver will be used instead.

Parameters
dimensionsint

Number of dimensions (i.e., actions).

n_neurons_per_ensembleint, optional

Number of neurons in each ensemble in the network.

output_weightfloat, optional

A scaling factor on the output of the basal ganglia (specifically on the connection out of the GPi).

input_biasfloat, optional

An amount by which to bias all dimensions of the input node. Biasing the input node is important for ensuring that all input dimensions are positive and easily comparable.

ampa_configconfig, optional

Configuration for connections corresponding to biological connections to AMPA receptors (i.e., connections from STN to to GPi and GPe). If None, a default configuration using a 2 ms lowpass synapse will be used.

gaba_configconfig, optional

Configuration for connections corresponding to biological connections to GABA receptors (i.e., connections from StrD1 to GPi, StrD2 to GPe, and GPe to GPi and STN). If None, a default configuration using an 8 ms lowpass synapse will be used.

**kwargs

Keyword arguments passed through to nengo.Network like ‘label’ and ‘seed’.

References

1

Stewart, T. C., Choo, X., & Eliasmith, C. (2010). Dynamic behaviour of a spiking model of action selection in the basal ganglia. In Proceedings of the 10th international conference on cognitive modeling (pp. 235-40).

2

Gurney, K., Prescott, T., & Redgrave, P. (2001). A computational model of action selection in the basal ganglia. Biological Cybernetics 84, 401-423.

Attributes
bias_inputNode or None

If input_bias is non-zero, this node will be created to bias all of the dimensions of the input signal.

gpeEnsembleArray

Globus pallidus externus ensembles.

gpiEnsembleArray

Globus pallidus internus ensembles.

inputNode

Accepts the input signal.

outputNode

Provides the output signal.

stnEnsembleArray

Subthalamic nucleus ensembles.

strD1EnsembleArray

Striatal D1 ensembles.

strD2EnsembleArray

Striatal D2 ensembles.

class nengo.networks.Thalamus(dimensions, n_neurons_per_ensemble=50, mutual_inhib=1.0, threshold=0.0, **kwargs)[source]

Inhibits non-selected actions.

The thalamus is intended to work in tandem with a basal ganglia network. It converts basal ganglia output into a signal with (approximately) 1 for the selected action and 0 elsewhere.

In order to suppress low responses and strengthen high responses, a constant bias is added to each dimension (i.e., action), and dimensions mutually inhibit each other. Additionally, the ensemble representing each dimension is created with positive encoders and can be assigned positive x-intercepts to threshold low responses.

Parameters
dimensionsint

Number of dimensions (i.e., actions).

n_neurons_per_ensembleint, optional

Number of neurons in each ensemble in the network.

mutual_inhibfloat, optional

Strength of the mutual inhibition between actions.

thresholdfloat, optional

The threshold below which values will not be represented.

**kwargs

Keyword arguments passed through to nengo.Network like ‘label’ and ‘seed’.

Attributes
actionsEnsembleArray

Each ensemble represents one dimension (action).

biasNode

The constant bias injected in each actions ensemble.

inputNode

Input to the actions ensembles.

outputNode

Output from the actions ensembles.

class nengo.networks.AssociativeMemory(input_vectors, output_vectors=None, n_neurons=50, threshold=0.3, input_scales=1.0, inhibitable=False, label=None, seed=None, add_to_container=None)[source]

Associative memory network.

Parameters
input_vectors: array_like

The list of vectors to be compared against.

output_vectors: array_like, optional

The list of vectors to be produced for each match. If None, the associative memory will be autoassociative (cleanup memory).

n_neurons: int, optional

The number of neurons for each of the ensemble (where each ensemble represents each item in the input_vectors list).

threshold: float, optional

The association activation threshold.

input_scales: float or array_like, optional

Scaling factor to apply on each of the input vectors. Note that it is possible to scale each vector independently.

inhibitable: bool, optional

Flag to indicate if the entire associative memory module is inhibitable (entire thing can be shut off). The input gain into the inhibitory connection is 1.5.

labelstr, optional

A name for the ensemble. Used for debugging and visualization.

seedint, optional

The seed used for random number generation.

add_to_containerbool, optional

Determines if the network will be added to the current container. If None, will be true if currently within a Network.

property am_ens_config

(Config) Defaults for associative memory ensemble creation.

property default_ens_config

(Config) Defaults for other ensemble creation.

property thresh_ens_config

(Config) Defaults for threshold ensemble creation.

add_input_mapping(self, name, input_vectors, input_scales=1.0)[source]

Adds a set of input vectors to the associative memory network.

Creates a transform with the given input vectors between the a named input node and associative memory element input to enable the inputs to be mapped onto ensembles of the Associative Memory.

Parameters
name: str

Name to use for the input node. This name will be used as the name of the attribute for the associative memory network.

input_vectors: array_like

The list of vectors to be compared against.

input_scales: float or array_like, optional

Scaling factor to apply on each of the input vectors. Note that it is possible to scale each vector independently.

add_output_mapping(self, name, output_vectors)[source]

Adds another output to the associative memory network.

Creates a transform with the given output vectors between the associative memory element output and a named output node to enable the selection of output vectors by the associative memory.

Parameters
name: str

Name to use for the output node. This name will be used as the name of the attribute for the associative memory network.

output_vectors: array_like

The list of vectors to be produced for each match.

add_default_output_vector(self, output_vector, output_name='output', n_neurons=50, min_activation_value=0.5)[source]

Adds a default output vector to the associative memory network.

The default output vector is chosen if the input matches none of the given input vectors.

Parameters
output_vector: array_like

The vector to be produced if the input value matches none of the vectors in the input vector list.

output_name: str, optional

The name of the input to which the default output vector should be applied.

n_neurons: int, optional

Number of neurons to use for the default output vector ensemble.

min_activation_value: float, optional

Minimum activation value (i.e. threshold) to use to disable the default output vector.

add_wta_network(self, inhibit_scale=1.5, inhibit_synapse=0.005)[source]

Add a winner-take-all (WTA) network to associative memory output.

Parameters
inhibit_scale: float, optional

Mutual inhibition scaling factor.

inhibit_synapse: float, optional

Mutual inhibition synapse time constant.

add_threshold_to_outputs(self, n_neurons=50, inhibit_scale=10)[source]

Adds a thresholded output to the associative memory.

Parameters
n_neurons: int, optional

Number of neurons to use for the default output vector ensemble.

inhibit_scale: float, optional

Mutual inhibition scaling factor.

class nengo.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) DFT(b) )\]

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

Parameters
n_neuronsint

Number of neurons to use in each product computation

dimensionsint

The number of dimensions of the input and output vectors.

invert_a, invert_bbool, optional

Whether to reverse the order of elements in either the first input (invert_a) or the second input (invert_b). Flipping the second input will make the network perform circular correlation instead of circular convolution.

input_magnitudefloat, 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

Keyword arguments passed through to nengo.Network like ‘label’ and ‘seed’.

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.

Examples

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

from nengo.networks import CircularConvolution, EnsembleArray

with nengo.Network():
    A = EnsembleArray(50, n_ensembles=10)
    B = EnsembleArray(50, n_ensembles=10)
    C = EnsembleArray(50, n_ensembles=10)
    cconv = CircularConvolution(50, dimensions=10)
    nengo.Connection(A.output, cconv.input_a)
    nengo.Connection(B.output, cconv.input_b)
    nengo.Connection(cconv.output, C.input)
Attributes
input_aNode

The first vector to be convolved.

input_bNode

The second vector to be convolved.

productNetwork

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

outputNode

The resulting convolved vector.

class nengo.networks.Integrator(recurrent_tau, n_neurons, dimensions, **kwargs)[source]

An ensemble that accumulates input and maintains state.

This is accomplished through scaling the input signal and recurrently connecting an ensemble to itself to maintain state.

Parameters
recurrent_taufloat

Time constant on the recurrent connection.

n_neuronsint

Number of neurons in the recurrently connected ensemble.

dimensionsint

Dimensionality of the input signal and ensemble.

**kwargs

Keyword arguments passed through to nengo.Network like ‘label’ and ‘seed’.

Attributes
ensembleEnsemble

The recurrently connected ensemble.

inputNode

Provides the input signal.

class nengo.networks.Oscillator(recurrent_tau, frequency, n_neurons, **kwargs)[source]

A two-dimensional ensemble with interacting recurrent connections.

The ensemble connects to itself in a manner similar to the integrator; however, here the two dimensions interact with each other to implement a cyclic oscillator.

Parameters
recurrent_taufloat

Time constant on the recurrent connection.

frequencyfloat

Desired frequency, in Hz, of the cyclic oscillation.

n_neuronsint

Number of neurons in the recurrently connected ensemble.

**kwargs

Keyword arguments passed through to nengo.Network like ‘label’ and ‘seed’.

Attributes
ensembleEnsemble

The recurrently connected oscillatory ensemble.

inputNode

Provides the input signal.

class nengo.networks.Product(n_neurons, dimensions, input_magnitude=1.0, **kwargs)[source]

Computes the element-wise product of two equally sized vectors.

The network used to calculate the product is described in Gosmann, 2015. A simpler version of this network can be found in the Multiplication example.

Note that this network is optimized under the assumption that both input values (or both values for each input dimensions of the input vectors) are uniformly and independently distributed. Visualized in a joint 2D space, this would give a square of equal probabilities for pairs of input values. This assumption is violated with non-uniform input value distributions (for example, if the input values follow a Gaussian or cosine similarity distribution). In that case, no square of equal probabilities is obtained, but a probability landscape with circular equi-probability lines. To obtain the optimal network accuracy, scale the input_magnitude by a factor of 1 / sqrt(2).

Parameters
n_neuronsint

Number of neurons per dimension in the vector.

Note

These neurons will be distributed evenly across two ensembles. If an odd number of neurons is specified, the extra neuron will not be used.

dimensionsint

Number of dimensions in each of the vectors to be multiplied.

input_magnitudefloat, optional

The expected magnitude of the vectors to be multiplied. This value is used to determine the radius of the ensembles computing the element-wise product.

**kwargs

Keyword arguments passed through to nengo.Network like ‘label’ and ‘seed’.

Attributes
input_aNode

The first vector to be multiplied.

input_bNode

The second vector to be multiplied.

outputNode

The resulting product.

sq1EnsembleArray

Represents the first squared term. See Gosmann, 2015 for details.

sq2EnsembleArray

Represents the second squared term. See Gosmann, 2015 for details.

class nengo.networks.InputGatedMemory(n_neurons, dimensions, feedback=1.0, difference_gain=1.0, recurrent_synapse=0.1, difference_synapse=None, **kwargs)[source]

Stores a given vector in memory, with input controlled by a gate.

Parameters
n_neuronsint

Number of neurons per dimension in the vector.

dimensionsint

Dimensionality of the vector.

feedbackfloat, optional

Strength of the recurrent connection from the memory to itself.

difference_gainfloat, optional

Strength of the connection from the difference ensembles to the memory ensembles.

recurrent_synapsefloat, optional
difference_synapseSynapse

If None, …

**kwargs

Keyword arguments passed through to nengo.Network like ‘label’ and ‘seed’.

Attributes
diffEnsembleArray

Represents the difference between the desired vector and the current vector represented by mem.

gateNode

With input of 0, the network is not gated, and mem will be updated to minimize diff. With input greater than 0, the network will be increasingly gated such that mem will retain its current value, and diff will be inhibited.

inputNode

The desired vector.

memEnsembleArray

Integrative population that stores the vector.

outputNode

The vector currently represented by mem.

resetNode

With positive input, the mem population will be inhibited, effectively wiping out the vector currently being remembered.