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.
|
General associative memory network. |
|
Winner take all network, typically used for action selection. |
|
Network for binding together two inputs. |
|
Computes the dot product of two inputs. |
|
Associative memory based on the |
|
Multiplies two scalars. |
|
Represents a single scalar. |
|
Represents a single vector, with optional memory. |
|
Inhibits non-selected actions. |
|
Associative memory based on |
|
Transcode from, to, and between Semantic Pointers. |
|
Associative memory based on the |
-
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_net (Network) – 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_neurons (int) – Number of neurons to represent each choice, passed on to the selection_net.
label (str, optional) – A name for the ensemble. Used for debugging and visualization.
seed (int, optional) – The seed used for random number generation.
add_to_container (bool, optional) – Determines if this Network will be added to the current container. See
nengo.Network
for more details.vocabs (VocabularyMap, optional) – Maps dimensionalities to the corresponding default vocabularies.
**selection_net_kwargs (dict) – 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
key (str) – Semantic Pointer to output.
min_activation_value (float) – Minimum output of another Semantic Pointer to deactivate the default output.
n_neurons (int, 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
andIA
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
andThresholding
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
andWTA
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 isnengo.solvers.NnlsL2nz
, which requires SciPy. If SciPy is not installed, the global default solver will be used instead.- Parameters
action_count (int) – Number of actions.
n_neuron_per_ensemble (int, optional) – Number of neurons in each ensemble in the network.
output_weight (float, optional) – A scaling factor on the output of the basal ganglia (specifically on the connection out of the GPi).
input_bias (float, 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_synapse (Synapse, optional) – Synapse for connections corresponding to biological connections to AMPA receptors (i.e., connections from STN to to GPi and GPe).
gaba_synapse (Synapse, 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).
**kwargs (dict) – Keyword arguments passed through the
nengo_spa.Network
.
-
bias_input
¶ If input_bias is non-zero, this node will be created to bias all of the dimensions of the input signal.
- Type
nengo.Node or None
-
gpe
¶ Globus pallidus externus ensembles.
-
gpi
¶ Globus pallidus internus ensembles.
-
input
¶ Accepts the input signal.
- Type
-
output
¶ Provides the output signal.
- Type
-
stn
¶ Subthalamic nucleus ensembles.
-
strD1
¶ Striatal D1 ensembles.
-
strD2
¶ Striatal D2 ensembles.
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.
-
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
vocab (Vocabulary 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_dimension (int, optional (Default: 200)) – Number of neurons to use in each dimension.
unbind_left (bool, optional) – Whether to unbind the left input.
unbind_right (bool, optional) – Whether to unbind the right input.
**kwargs (dict) – Keyword arguments passed through to
nengo_spa.Network
.
-
input_left
¶ Left input vector.
- Type
-
input_right
¶ Right input vector.
- Type
-
output
¶ Output.
- Type
-
class
nengo_spa.modules.
Compare
(vocab=Default, neurons_per_dimension=Default, **kwargs)[source]¶ Computes the dot product of two inputs.
- Parameters
vocab (Vocabulary 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_dimension (int, optional (Default: 200)) – Number of neurons to use in each product computation.
**kwargs (dict) – Keyword arguments passed through to
nengo_spa.Network
.
-
input_a
¶ First input vector.
- Type
-
input_b
¶ Second input vector.
- Type
-
output
¶ Output.
- Type
-
class
nengo_spa.modules.
Product
(n_neurons=Default, **kwargs)[source]¶ Multiplies two scalars.
- Parameters
n_neurons (int, optional (Default: 200)) – Number of neurons to use in product computation.
**kwargs (dict) – Keyword arguments passed through to
nengo_spa.Network
.
-
input_a
¶ First input.
- Type
-
input_b
¶ Second input.
- Type
-
output
¶ Output.
- Type
-
class
nengo_spa.modules.
Scalar
(n_neurons=Default, **kwargs)[source]¶ Represents a single scalar.
- Parameters
n_neurons (int, optional (Default: 50)) – Number of neurons to represent the scalar.
**kwargs (dict) – Keyword arguments passed through to
nengo_spa.Network
.
-
input
¶ Input.
- Type
-
output
¶ Output.
- Type
-
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
vocab (Vocabulary or int) – The vocabulary to use to interpret the vector. If an integer is given, the default vocabulary of that dimensionality will be used.
subdimensions (int, 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_dimension (int, optional (Default: 50)) – Number of neurons per dimension. Each ensemble will have
neurons_per_dimension * subdimensions
neurons, for a total ofneurons_per_dimension * dimensions
neurons.feedback (float, 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_identity (bool, optional) – Whether to use optimizations to better represent the circular convolution identity vector. If activated, the
IdentityEnsembleArray
will be used internally, otherwise a normalnengo.networks.EnsembleArray
split up regularly according to subdimensions.feedback_synapse (float, optional (Default: 0.1)) – The synapse on the feedback connection.
**kwargs (dict) – Keyword arguments passed through to
nengo_spa.Network
.
-
input
¶ Input.
- Type
-
output
¶ Output.
- Type
-
class
nengo_spa.modules.
Superposition
(n_inputs, vocab=Default, neurons_per_dimension=Default, **kwargs)[source]¶ Network for superposing multiple inputs.
- Parameters
n_inputs (int) – Number of inputs.
vocab (Vocabulary 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_dimension (int, optional (Default: 200)) – Number of neurons to use in each dimension.
**kwargs (dict) – Keyword arguments passed through to
nengo_spa.Network
.
-
inputs
¶ Inputs.
- Type
sequence
-
output
¶ Output.
- Type
-
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_action (int, optional (Default: 50)) – Number of neurons per action to represent the selection.
threshold_action (float, optional (Default: 0.2)) – Minimum value for action representation.
mutual_inhibit (float, optional (Default: 1.0)) – Strength of inhibition between actions.
route_inhibit (float, optional (Default: 3.0)) – Strength of inhibition for unchosen actions.
synapse_inhibit (float, optional (Default: 0.008)) – Synaptic filter to apply for inhibition between actions.
synapse_bg (float, optional (Default: 0.008)) – Synaptic filter for connection between basal ganglia and thalamus.
synapse_direct (float, optional (Default: 0.01)) – Synaptic filter for direct outputs.
neurons_channel_dim (int, optional (Default: 50)) – Number of neurons per routing channel dimension.
synapse_channel (float, optional (Default: 0.01)) – Synaptic filter for channel inputs and outputs.
neurons_gate (int, optional (Default: 40)) – Number of neurons per gate.
threshold_gate (float, optional (Default: 0.3)) – Minimum value for gating neurons.
synapse_to-gate (float, optional (Default: 0.002)) – Synaptic filter for controlling a gate.
**kwargs (dict) – Keyword arguments passed through to
nengo_spa.Network
.
-
actions
¶ Each ensemble represents one dimension (action).
-
bias
¶ The constant bias injected in each actions ensemble.
- Type
-
input
¶ Input to the actions ensembles.
- Type
-
output
¶ Output from the actions ensembles.
- Type
-
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
index (int) – Index to identify the gate.
bias (
nengo.Network
) – Node providing a bias input of 1.label (str, optional) – Label for the gate.
- Returns
The constructed gate.
- Return type
-
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
sink (nengo.base.NengoObject) – Sink/target that the channel feeds into.
type (nengo_spa.types.Type) – Type of the data transmitted through the channel.
label (str, optional) – Label for the channel.
- Returns
The constructed channel.
- Return type
-
connect_gate
(index, channel)[source]¶ Connect a gate to a channel for information routing.
- Parameters
index (int) – Index of the gate to connect.
channel (nengo.networks.EnsembleArray) – Channel to inhibit with the gate.
-
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
function (func, 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
. Eitherfunction(t)
orfunction(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 viasp.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_vocab (Vocabulary, optional (Default: None)) – Input vocabulary. Mutually exclusive with size_in.
output_vocab (Vocabulary, optional (Default: None)) – Output vocabulary. Mutually exclusive with size_out.
size_in (int, optional (Default: None)) – Input size. Mutually exclusive with input_vocab.
size_out (int, optional (Default: None)) – Output size. Mutually exclusive with output_vocab.
**kwargs (dict) – Additional keyword arguments passed to
nengo_spa.Network
.
-
input
¶ Input.
- Type
-
output
¶ Output.
- Type