Note
This documentation is for a development version. Click here for the latest stable release (v3.1.0).
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 codereuse 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 reuse, and easier to share. The following examples will help you build your own reusable networks:
You may also find the config system documentation useful.
Builtin networks¶
An array of ensembles. 

Winner take all network, typically used for action selection. 

Inhibits nonselected actions. 

Associative memory network. 

Compute the circular convolution of two vectors. 

An ensemble that accumulates input and maintains state. 

A twodimensional ensemble with interacting recurrent connections. 

Computes the elementwise product of two equally sized vectors. 

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 highdimensional ensemble, but actually consists of many subensembles, each one representing a separate dimension. This tends to be much faster to create and can be more accurate than having one huge highdimensional 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 subensembles can be passed to the ensemble array. For example:
ea = nengo.networks.EnsembleArray(20, 2, radius=1.5)
creates an ensemble array with 2 subensembles, each with 20 neurons, and a radius of 1.5.
 Parameters
 n_neuronsint
The number of neurons in each subensemble.
 n_ensemblesint
The number of subensembles to create.
 ens_dimensionsint, optional
The dimensionality of each subensemble.
 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 subensemble.
 ea_ensembleslist
The subensembles in the ensemble array.
 inputNode
A node that provides input to all of the ensembles in the array.
 n_ensemblesint
The number of subensembles to create.
 n_neurons_per_ensembleint
The number of neurons in each subensemble.
 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
()[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
()[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
(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__
withfunction=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 subensembles to the new node can be passed to this function. For example:
ea.add_output("lstsq_output", None, solver=nengo.solvers.Lstsq())
creates a new output at
ea.lstsq_output
with the decoders of each connection solved for with theLstsq
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 subensembles to the new output node. If function is an iterable, it must be an iterable consisting of one function for each subensemble.
 synapseSynapse, optional
The synapse model with which to filter the connections from subensembles 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 winnertakeall function, it is also organized to match the organization of the human basal ganglia. It consists of five ensembles:
Striatal D1 dopaminereceptor neurons (
strD1
)Striatal D2 dopaminereceptor 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 nonspiking basal ganglia model by Gurney, Prescott & Redgrave that this model is based on.
Note
The default
Solver
for the basal ganglia isNnlsL2nz
, 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. 23540).
 2
Gurney, K., Prescott, T., & Redgrave, P. (2001). A computational model of action selection in the basal ganglia. Biological Cybernetics 84, 401423.
 Attributes
 bias_inputNode or None
If
input_bias
is nonzero, 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 nonselected 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 xintercepts 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
(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
(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
(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.

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 elementwise 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 10dimensional 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 elementwise 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 twodimensional 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 radians per second, 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 elementwise 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 nonuniform 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 equiprobability 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 elementwise 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 minimizediff
. With input greater than 0, the network will be increasingly gated such thatmem
will retain its current value, anddiff
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.