Note

This documentation is for a development version. Click here for the latest stable release (v1.3.0).

nengo_spa.modules¶

SPA modules with defined inputs and outputs usable in action rules.

SPA modules derive from nengo_spa.Network and thus provide information about inputs and outputs that can be used in action rules and the associated vocabularies. Note that a module might have no inputs and outputs that can be used in action rules (like BasalGanglia and Thalamus), but only inputs and outputs that must be manually connected to. Many SPA modules are networks that might be automatically created by building action rules. Because of this, it is possible to set module parameters with nengo.Config objects to allow to easily change parameters of networks created in this way.

Note that SPA modules can be used as standalone networks without using any other NengoSPA features.

`AssociativeMemory`(selection_net, input_vocab)	General associative memory network.
`BasalGanglia`(action_count[, …])	Winner take all network, typically used for action selection.
`Bind`([vocab, neurons_per_dimension, …])	Network for binding together two inputs.
`Compare`([vocab, neurons_per_dimension])	Computes the dot product of two inputs.
`IAAssocMem`(input_vocab[, output_vocab, …])	Associative memory based on the `IA` network.
`Product`([n_neurons])	Multiplies two scalars.
`Scalar`([n_neurons])	Represents a single scalar.
`State`([vocab, subdimensions, …])	Represents a single vector, with optional memory.
`Thalamus`(action_count[, neurons_action, …])	Inhibits non-selected actions.
`ThresholdingAssocMem`(threshold, input_vocab)	Associative memory based on `Thresholding`.
`Transcode`([function, input_vocab, …])	Transcode from, to, and between Semantic Pointers.
`WTAAssocMem`(threshold, input_vocab[, …])	Associative memory based on the `WTA` network.

class nengo_spa.modules.AssociativeMemory(selection_net, input_vocab, output_vocab=None, mapping=None, n_neurons=50, label=None, seed=None, add_to_container=None, vocabs=None, **selection_net_kwargs)[source]¶

General associative memory network.

This provides a low-level selection network with the necessary interface to include it within the SPA system.

Parameters

selection_netNetwork: The network that is used to select the response. It needs to accept the arguments n_neurons (number of neurons to use to represent each possible choice) and n_ensembles (number of choices). The returned network needs to have an input attribute to which the utilities for each choice are connected and an output attribute from which a connection will be created to read the selected output(s).
input_vocab: Vocabulary or int: The vocabulary to match.
output_vocab: Vocabulary or int, optional: The vocabulary to be produced for each match. If None, the associative memory will act like an auto-associative memory (cleanup memory).
mapping: dict, str, or sequence of str: A dictionary that defines the mapping from Semantic Pointers in the input vocabulary to Semantic Pointers in the output vocabulary. If set to the string 'by-key', the mapping will be done based on the keys of the to vocabularies. If a sequence is provided, an auto-associative (cleanup) memory with the given set of keys will be created.
n_neuronsint: Number of neurons to represent each choice, passed on to the selection_net.
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 this Network will be added to the current container. See nengo.Network for more details.
vocabsVocabularyMap, optional: Maps dimensionalities to the corresponding default vocabularies.
**selection_net_kwargsdict: Additional keyword arguments that will passed to the selection_net.

add_default_output(key, min_activation_value, n_neurons=50)[source]¶

Adds a Semantic Pointer to output when no other pointer is active.

Parameters

keystr: Semantic Pointer to output.
min_activation_valuefloat: Minimum output of another Semantic Pointer to deactivate the default output.
n_neuronsint, optional: Number of neurons used to represent the default Semantic Pointer.

class nengo_spa.modules.IAAssocMem(input_vocab, output_vocab=None, mapping=None, n_neurons=50, label=None, seed=None, add_to_container=None, vocabs=None, **selection_net_kwargs)[source]¶

Associative memory based on the IA network.

See AssociativeMemory and IA for more information.

class nengo_spa.modules.ThresholdingAssocMem(threshold, input_vocab, output_vocab=None, mapping=None, n_neurons=50, label=None, seed=None, add_to_container=None, vocabs=None, **selection_net_kwargs)[source]¶

Associative memory based on Thresholding.

See AssociativeMemory and Thresholding for more information.

class nengo_spa.modules.WTAAssocMem(threshold, input_vocab, output_vocab=None, mapping=None, n_neurons=50, label=None, seed=None, add_to_container=None, vocabs=None, **selection_net_kwargs)[source]¶

Associative memory based on the WTA network.

See AssociativeMemory and WTA for more information.

class nengo_spa.modules.BasalGanglia(action_count, n_neurons_per_ensemble=Default, output_weight=Default, input_bias=Default, ampa_synapse=Default, gaba_synapse=Default, **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 nengo.solvers.Solver for the basal ganglia is nengo.solvers.NnlsL2nz, which requires SciPy. If SciPy is not installed, the global default solver will be used instead.

Parameters

action_countint: Number of actions.
n_neuron_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_synapseSynapse, optional: Synapse for connections corresponding to biological connections to AMPA receptors (i.e., connections from STN to to GPi and GPe).
gaba_synapseSynapse, optional: Synapse 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).
**kwargsdict: Keyword arguments passed through the nengo_spa.Network.

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_inputnengo.Node or None: If input_bias is non-zero, this node will be created to bias all of the dimensions of the input signal.
gpenengo.networks.EnsembleArray: Globus pallidus externus ensembles.
gpinengo.networks.EnsembleArray: Globus pallidus internus ensembles.
inputnengo.Node: Accepts the input signal.
outputnengo.Node: Provides the output signal.
stnnengo.networks.EnsembleArray: Subthalamic nucleus ensembles.
strD1nengo.networks.EnsembleArray: Striatal D1 ensembles.
strD2nengo.networks.EnsembleArray: Striatal D2 ensembles.

class nengo_spa.modules.Bind(vocab=Default, neurons_per_dimension=Default, unbind_left=Default, unbind_right=Default, **kwargs)[source]¶

Network for binding together two inputs.

Parameters

vocabVocabulary or int: The vocabulary to use to interpret the vector. If an integer is given, the default vocabulary of that dimensionality will be used.
neurons_per_dimensionint, optional (Default: 200): Number of neurons to use in each dimension.
unbind_leftbool, optional: Whether to unbind the left input.
unbind_rightbool, optional: Whether to unbind the right input.
**kwargsdict: Keyword arguments passed through to nengo_spa.Network.

Attributes

input_leftnengo.Node: Left input vector.
input_rightnengo.Node: Right input vector.
outputnengo.Node: Output.

class nengo_spa.modules.Compare(vocab=Default, neurons_per_dimension=Default, **kwargs)[source]¶

Computes the dot product of two inputs.

Parameters

vocabVocabulary or int: The vocabulary to use to interpret the vector. If an integer is given, the default vocabulary of that dimensionality will be used.
neurons_per_dimensionint, optional (Default: 200): Number of neurons to use in each product computation.
**kwargsdict: Keyword arguments passed through to nengo_spa.Network.

Attributes

input_anengo.Node: First input vector.
input_bnengo.Node: Second input vector.
outputnengo.Node: Output.

class nengo_spa.modules.Product(n_neurons=Default, **kwargs)[source]¶

Multiplies two scalars.

Parameters

n_neuronsint, optional (Default: 200): Number of neurons to use in product computation.
**kwargsdict: Keyword arguments passed through to nengo_spa.Network.

Attributes

input_anengo.Node: First input.
input_bnengo.Node: Second input.
outputnengo.Node: Output.

class nengo_spa.modules.Scalar(n_neurons=Default, **kwargs)[source]¶

Represents a single scalar.

Parameters

n_neuronsint, optional (Default: 50): Number of neurons to represent the scalar.
**kwargsdict: Keyword arguments passed through to nengo_spa.Network.

Attributes

inputnengo.Node: Input.
outputnengo.Node: Output.

class nengo_spa.modules.State(vocab=Default, subdimensions=Default, neurons_per_dimension=Default, feedback=Default, represent_cc_identity=Default, feedback_synapse=Default, **kwargs)[source]¶

Represents a single vector, with optional memory.

This is a minimal SPA network, useful for passing data along (for example, visual input).

Parameters

vocabVocabulary or int: The vocabulary to use to interpret the vector. If an integer is given, the default vocabulary of that dimensionality will be used.
subdimensionsint, optional (Default: 16): The dimension of the individual ensembles making up the vector. Must divide dimensions evenly. The number of sub-ensembles will be dimensions // subdimensions.
neurons_per_dimensionint, optional (Default: 50): Number of neurons per dimension. Each ensemble will have neurons_per_dimension * subdimensions neurons, for a total of neurons_per_dimension * dimensions neurons.
feedbackfloat, optional (Default: 0.0): Gain of feedback connection. Set to 1.0 for perfect memory, or 0.0 for no memory. Values in between will create a decaying memory.
represent_cc_identitybool, optional: Whether to use optimizations to better represent the circular convolution identity vector. If activated, the IdentityEnsembleArray will be used internally, otherwise a normal nengo.networks.EnsembleArray split up regularly according to subdimensions.
feedback_synapsefloat, optional (Default: 0.1): The synapse on the feedback connection.
**kwargsdict: Keyword arguments passed through to nengo_spa.Network.

Attributes

inputnengo.Node: Input.
outputnengo.Node: Output.

class nengo_spa.modules.Superposition(n_inputs, vocab=Default, neurons_per_dimension=Default, **kwargs)[source]¶

Network for superposing multiple inputs.

Parameters

n_inputsint: Number of inputs.
vocabVocabulary or int: The vocabulary to use to interpret the vector. If an integer is given, the default vocabulary of that dimensionality will be used.
neurons_per_dimensionint, optional (Default: 200): Number of neurons to use in each dimension.
**kwargsdict: Keyword arguments passed through to nengo_spa.Network.

Attributes

inputssequence: Inputs.
outputnengo.Node: Output.

class nengo_spa.modules.Thalamus(action_count, neurons_action=Default, threshold_action=Default, mutual_inhibit=Default, route_inhibit=Default, synapse_inhibit=Default, synapse_bg=Default, neurons_channel_dim=Default, synapse_channel=Default, neurons_gate=Default, threshold_gate=Default, synapse_to_gate=Default, **kwargs)[source]¶

Inhibits non-selected actions.

The thalamus is intended to work in tandem with a BasalGanglia module. 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

neurons_actionint, optional (Default: 50): Number of neurons per action to represent the selection.
threshold_actionfloat, optional (Default: 0.2): Minimum value for action representation.
mutual_inhibitfloat, optional (Default: 1.0): Strength of inhibition between actions.
route_inhibitfloat, optional (Default: 3.0): Strength of inhibition for unchosen actions.
synapse_inhibitfloat, optional (Default: 0.008): Synaptic filter to apply for inhibition between actions.
synapse_bgfloat, optional (Default: 0.008): Synaptic filter for connection between basal ganglia and thalamus.
synapse_directfloat, optional (Default: 0.01): Synaptic filter for direct outputs.
neurons_channel_dimint, optional (Default: 50): Number of neurons per routing channel dimension.
synapse_channelfloat, optional (Default: 0.01): Synaptic filter for channel inputs and outputs.
neurons_gateint, optional (Default: 40): Number of neurons per gate.
threshold_gatefloat, optional (Default: 0.3): Minimum value for gating neurons.
synapse_to-gatefloat, optional (Default: 0.002): Synaptic filter for controlling a gate.
**kwargsdict: Keyword arguments passed through to nengo_spa.Network.

Attributes

actionsnengo.networks.EnsembleArray: Each ensemble represents one dimension (action).
biasnengo.Node: The constant bias injected in each actions ensemble.
inputnengo.Node: Input to the actions ensembles.
outputnengo.Node: Output from the actions ensembles.

construct_gate(index, bias, label=None)[source]¶

Construct a gate ensemble.

The gate neurons have no activity when the action is selected, but are active when the action is not selected. This makes the gate useful for inhibiting ensembles that should only be active when this action is active.

Parameters

indexint: Index to identify the gate.
biasnengo.Network: Node providing a bias input of 1.
labelstr, optional: Label for the gate.

Returns

nengo.Ensemble: The constructed gate.

construct_channel(sink, type_, label=None)[source]¶

Construct a channel.

Channels are an additional neural population in-between a source population and a target population. This allows inhibiting the channel without affecting the source and thus is useful in routing information.

Parameters

sinknengo.base.NengoObject: Sink/target that the channel feeds into.
type_nengo_spa.types.Type: Type of the data transmitted through the channel.
labelstr, optional: Label for the channel.

Returns

nengo.networks.EnsembleArray: The constructed channel.

connect_bg(bg)[source]¶: Connect a basal ganglia network to this thalamus.

connect_gate(index, channel)[source]¶

Connect a gate to a channel for information routing.

Parameters

indexint: Index of the gate to connect.
channelnengo.networks.EnsembleArray: Channel to inhibit with the gate.

connect_fixed(index, target, transform)[source]¶

Create connection to route fixed value.

Parameters

indexint: Index of the action to connect.
targetnengo.base.NengoObject: Target of the connection.
transformarray-like: Transform to apply to apply to the connection.

connect(source, target, transform)[source]¶

Create connection.

The connection will use the thalamus’s synapse_channel.

Parameters

sourcenengo.base.NengoObject: Source object.
targetnengo.base.NengoObject: Target object.
transformarray-like: Transform to apply to the connection.

class nengo_spa.modules.Transcode(function=Default, input_vocab=Default, output_vocab=Default, size_in=Default, size_out=Default, **kwargs)[source]¶

Transcode from, to, and between Semantic Pointers.

This can thought of the equivalent of a nengo.Node for Semantic Pointers.

Either the input_vocab or the output_vocab argument must not be None. (If you want both arguments to be None, use a normal nengo.Node.) Which one of the parameters in the pairs input_vocab/size_in and output_vocab/size_out is not set to None, determines whether a Semantic Pointer input/output or a normal vector input/output is expected.

Parameters

functionfunc, optional (Default: None)

Function that transforms the input Semantic Pointer to an output Semantic Pointer. The function signature depends on input_vocab:

If input_vocab is None, the allowed signatures are the same as for a nengo.Node. Either function(t) or function(t, x) where t (float) is the current simulation time and x (NumPy array) is the current input to transcode with size size_in.
If input_vocab is not None, the signature has to be function(t, sp) where t (float) is the current simulation time and sp (SemanticPointer) is the current Semantic Pointer input. The associated vocabulary can be obtained via sp.vocab.

The allowed function return value depends on output_vocab:

If output_vocab is None, the return value must be a NumPy array (or equivalent) of size size_out or None (i.e. no return value) if size_out is None.
If output_vocab is not None, the return value can be either of: NumPy array, SemanticPointer instance, or an SemanticPointer expression or symbolic expression as string that gets parsed with the output_vocab.

input_vocabVocabulary, optional (Default: None)

Input vocabulary. Mutually exclusive with size_in.

output_vocabVocabulary, optional (Default: None)

Output vocabulary. Mutually exclusive with size_out.

size_inint, optional (Default: None)

Input size. Mutually exclusive with input_vocab.

size_outint, optional (Default: None)

Output size. Mutually exclusive with output_vocab.

**kwargsdict

Additional keyword arguments passed to nengo_spa.Network.

Attributes

inputnengo.Node: Input.
outputnengo.Node: Output.