Note
This documentation is for a development version. Click here for the latest stable release (v1.2.0).
nengo_spa.algebras¶
Algebras define the specific superposition and (un)binding operations.
Abstract base class for algebras. 


The side in a binary operation for which a special element’s properties hold. 
Holographic Reduced Representations (HRRs) algebra. 

Vectorderived Transformation Binding (VTB) algebra. 

Transposed Vectorderived Transformation Binding (TVTB) algebra. 

class
nengo_spa.algebras.
AbstractAlgebra
[source]¶ Abstract base class for algebras.
Custom algebras can be defined by implementing the interface of this abstract base class.

is_valid_dimensionality
(d)[source]¶ Checks whether d is a valid vector dimensionality.
 Parameters
d (int) – Dimensionality
 Returns
True, if d is a valid vector dimensionality for the use with the algebra.
 Return type
bool

make_unitary
(v)[source]¶ Returns a unitary vector based on the vector v.
A unitary vector does not change the length of a vector it is bound to.
 Parameters
v ((d,) ndarray) – Vector to base unitary vector on.
 Returns
Unitary vector.
 Return type
ndarray

superpose
(a, b)[source]¶ Returns the superposition of a and b.
This is commonly elementwise addition.
 Parameters
a ((d,) ndarray) – Left operand in superposition.
b ((d,) ndarray) – Right operand in superposition.
 Returns
Superposed vector.
 Return type
(d,) ndarray

bind
(a, b)[source]¶ Returns the binding of a and b.
The resulting vector should in most cases be dissimilar to both inputs.
 Parameters
a ((d,) ndarray) – Left operand in binding.
b ((d,) ndarray) – Right operand in binding.
 Returns
Bound vector.
 Return type
(d,) ndarray

invert
(v, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Invert vector v.
A vector bound to its inverse will result in the identity vector.
Some algebras might not have an inverse only on specific sides. In that case a NotImplementedError may be raised for nonexisting inverses.
 Parameters
v ((d,) ndarray) – Vector to invert.
sidedness (ElementSidedness, optional) – Side in the binding operation on which the returned value acts as inverse.
 Returns
Inverted vector.
 Return type
(d,) ndarray

get_binding_matrix
(v, swap_inputs=False)[source]¶ Returns the transformation matrix for binding with a fixed vector.
 Parameters
v ((d,) ndarray) – Fixed vector to derive binding matrix for.
swap_inputs (bool, optional) – By default the matrix will be such that v becomes the right operand in the binding. By setting swap_inputs, the matrix will be such that v becomes the left operand. For binding operations that are commutative (such as circular convolution), this has no effect.
 Returns
Transformation matrix to perform binding with v.
 Return type
(d, d) ndarray

get_inversion_matrix
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Returns the transformation matrix for inverting a vector.
Some algebras might not have an inverse only on specific sides. In that case a NotImplementedError may be raised for nonexisting inverses.
 Parameters
d (int) – Vector dimensionality (determines the matrix size).
sidedness (ElementSidedness, optional) – Side in the binding operation on which a transformed vectors acts as inverse.
 Returns
Transformation matrix to invert a vector.
 Return type
(d, d) ndarray

implement_superposition
(n_neurons_per_d, d, n)[source]¶ Implement neural network for superposing vectors.
 Parameters
n_neurons_per_d (int) – Neurons to use per dimension.
d (int) – Dimensionality of the vectors.
n (int) – Number of vectors to superpose in the network.
 Returns
Tuple (net, inputs, output) where net is the implemented
nengo.Network
, inputs a sequence of length n of inputs to the network, and output the network output. Return type
tuple

implement_binding
(n_neurons_per_d, d, unbind_left, unbind_right)[source]¶ Implement neural network for binding vectors.
 Parameters
n_neurons_per_d (int) – Neurons to use per dimension.
d (int) – Dimensionality of the vectors.
unbind_left (bool) – Whether the left input should be unbound from the right input.
unbind_right (bool) – Whether the right input should be unbound from the left input.
 Returns
Tuple (net, inputs, output) where net is the implemented
nengo.Network
, inputs a sequence of the left and the right input in that order, and output the network output. Return type
tuple

absorbing_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the standard absorbing element of dimensionality d.
An absorbing element will produce a scaled version of itself when bound to another vector. The standard absorbing element is the absorbing element with norm 1.
Some algebras might not have an absorbing element other than the zero vector. In that case a NotImplementedError may be raised.
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness, optional) – Side in the binding operation on which the element absorbs.
 Returns
Standard absorbing element.
 Return type
(d,) ndarray

identity_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the identity element of dimensionality d.
The identity does not change the vector it is bound to.
Some algebras might not have an identity element. In that case a NotImplementedError may be raised.
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness, optional) – Side in the binding operation on which the element acts as identity.
 Returns
Identity element.
 Return type
(d,) ndarray

zero_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the zero element of dimensionality d.
The zero element produces itself when bound to a different vector. Usually this will be the zero vector.
Some algebras might not have a zero element. In that case a NotImplementedError may be raised.
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness, optional) – Side in the binding operation on which the element acts as zero.
 Returns
Zero element.
 Return type
(d,) ndarray


class
nengo_spa.algebras.
ElementSidedness
(value)[source]¶ The side in a binary operation for which a special element’s properties hold.

LEFT
= 'left'¶

RIGHT
= 'right'¶

TWO_SIDED
= 'twosided'¶


class
nengo_spa.algebras.
HrrAlgebra
[source]¶ Holographic Reduced Representations (HRRs) algebra.
Uses elementwise addition for superposition, circular convolution for binding with an approximate inverse.
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.
Circular convolution as a binding operation is associative, commutative, distributive.
More information on circular convolution as a binding operation can be found in [plate2003].
 plate2003
Plate, Tony A. Holographic Reduced Representation: Distributed Representation for Cognitive Structures. Stanford, CA: CSLI Publications, 2003.

is_valid_dimensionality
(d)[source]¶ Checks whether d is a valid vector dimensionality.
For circular convolution all positive numbers are valid dimensionalities.
 Parameters
d (int) – Dimensionality
 Returns
True, if d is a valid vector dimensionality for the use with the algebra.
 Return type
bool

make_unitary
(v)[source]¶ Returns a unitary vector based on the vector v.
A unitary vector does not change the length of a vector it is bound to.
 Parameters
v ((d,) ndarray) – Vector to base unitary vector on.
 Returns
Unitary vector.
 Return type
ndarray

superpose
(a, b)[source]¶ Returns the superposition of a and b.
This is commonly elementwise addition.
 Parameters
a ((d,) ndarray) – Left operand in superposition.
b ((d,) ndarray) – Right operand in superposition.
 Returns
Superposed vector.
 Return type
(d,) ndarray

bind
(a, b)[source]¶ Returns the binding of a and b.
The resulting vector should in most cases be dissimilar to both inputs.
 Parameters
a ((d,) ndarray) – Left operand in binding.
b ((d,) ndarray) – Right operand in binding.
 Returns
Bound vector.
 Return type
(d,) ndarray

invert
(v, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Invert vector v.
This turns circular convolution into circular correlation, meaning that
A*B*~B
is approximatelyA
.Examples
For the vector
[1, 2, 3, 4, 5]
, the inverse is[1, 5, 4, 3, 2]
. Parameters
v ((d,) ndarray) – Vector to invert.
sidedness (ElementSidedness, optional) – This argument has no effect because the HRR algebra is commutative and the inverse is twosided.
 Returns
Inverted vector.
 Return type
(d,) ndarray

get_binding_matrix
(v, swap_inputs=False)[source]¶ Returns the transformation matrix for binding with a fixed vector.
 Parameters
v ((d,) ndarray) – Fixed vector to derive binding matrix for.
swap_inputs (bool, optional) – By default the matrix will be such that v becomes the right operand in the binding. By setting swap_inputs, the matrix will be such that v becomes the left operand. For binding operations that are commutative (such as circular convolution), this has no effect.
 Returns
Transformation matrix to perform binding with v.
 Return type
(d, d) ndarray

get_inversion_matrix
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Returns the transformation matrix for inverting a vector.
 Parameters
d (int) – Vector dimensionality (determines the matrix size).
sidedness (ElementSidedness, optional) – This argument has no effect because the HRR algebra is commutative and the inverse is twosided.
 Returns
Transformation matrix to invert a vector.
 Return type
(d, d) ndarray

implement_superposition
(n_neurons_per_d, d, n)[source]¶ Implement neural network for superposing vectors.
 Parameters
n_neurons_per_d (int) – Neurons to use per dimension.
d (int) – Dimensionality of the vectors.
n (int) – Number of vectors to superpose in the network.
 Returns
Tuple (net, inputs, output) where net is the implemented
nengo.Network
, inputs a sequence of length n of inputs to the network, and output the network output. Return type
tuple

implement_binding
(n_neurons_per_d, d, unbind_left, unbind_right)[source]¶ Implement neural network for binding vectors.
 Parameters
n_neurons_per_d (int) – Neurons to use per dimension.
d (int) – Dimensionality of the vectors.
unbind_left (bool) – Whether the left input should be unbound from the right input.
unbind_right (bool) – Whether the right input should be unbound from the left input.
 Returns
Tuple (net, inputs, output) where net is the implemented
nengo.Network
, inputs a sequence of the left and the right input in that order, and output the network output. Return type
tuple

absorbing_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the standard absorbing element of dimensionality d.
An absorbing element will produce a scaled version of itself when bound to another vector. The standard absorbing element is the absorbing element with norm 1.
The absorbing element for circular convolution is the vector \((1, 1, \dots, 1)^{\top} / \sqrt{d}\).
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness, optional) – This argument has no effect because the HRR algebra is commutative and the standard absorbing element is twosided.
 Returns
Standard absorbing element.
 Return type
(d,) ndarray

identity_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the identity element of dimensionality d.
The identity does not change the vector it is bound to.
The identity element for circular convolution is the vector \((1, 0, \dots, 0)^{\top}\).
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness, optional) – This argument has no effect because the HRR algebra is commutative and the identity is twosided.
 Returns
Identity element.
 Return type
(d,) ndarray

zero_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the zero element of dimensionality d.
The zero element produces itself when bound to a different vector. For circular convolution this is the zero vector.
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness, optional) – This argument has no effect because the HRR algebra is commutative and the zero element is twosided.
 Returns
Zero element.
 Return type
(d,) ndarray

class
nengo_spa.algebras.
TvtbAlgebra
[source]¶ Transposed Vectorderived Transformation Binding (TVTB) algebra.
TVTB 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 twosided identities and inverses. Other properties are equivalent to VTB.
See also

is_valid_dimensionality
(d)[source]¶ Checks whether d is a valid vector dimensionality.
For TVTB all square numbers are valid dimensionalities.
 Parameters
d (int) – Dimensionality
 Returns
True, if d is a valid vector dimensionality for the use with the algebra.
 Return type
bool

make_unitary
(v)[source]¶ Returns a unitary vector based on the vector v.
A unitary vector does not change the length of a vector it is bound to.
 Parameters
v ((d,) ndarray) – Vector to base unitary vector on.
 Returns
Unitary vector.
 Return type
ndarray

superpose
(a, b)[source]¶ Returns the superposition of a and b.
This is commonly elementwise addition.
 Parameters
a ((d,) ndarray) – Left operand in superposition.
b ((d,) ndarray) – Right operand in superposition.
 Returns
Superposed vector.
 Return type
(d,) ndarray

bind
(a, b)[source]¶ Returns the binding of a and b.
The resulting vector should in most cases be dissimilar to both inputs.
 Parameters
a ((d,) ndarray) – Left operand in binding.
b ((d,) ndarray) – Right operand in binding.
 Returns
Bound vector.
 Return type
(d,) ndarray

invert
(v, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Invert vector v.
A vector bound to its inverse will result in the identity vector.
 Parameters
v ((d,) ndarray) – Vector to invert.
sidedness (ElementSidedness) – This argument has no effect because the inverse of the TVTB algebra is twosided.
 Returns
Inverse of vector.
 Return type
(d,) ndarray

get_binding_matrix
(v, swap_inputs=False)[source]¶ Returns the transformation matrix for binding with a fixed vector.
 Parameters
v ((d,) ndarray) – Fixed vector to derive binding matrix for.
swap_inputs (bool, optional) – By default the matrix will be such that v becomes the right operand in the binding. By setting swap_inputs, the matrix will be such that v becomes the left operand. For binding operations that are commutative (such as circular convolution), this has no effect.
 Returns
Transformation matrix to perform binding with v.
 Return type
(d, d) ndarray

get_inversion_matrix
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Returns the transformation matrix for inverting a vector.
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness) – This argument has no effect because the inverse of the TVTB algebra is twosided.
 Returns
Transformation matrix to invert a vector.
 Return type
(d, d) ndarray

implement_superposition
(n_neurons_per_d, d, n)[source]¶ Implement neural network for superposing vectors.
 Parameters
n_neurons_per_d (int) – Neurons to use per dimension.
d (int) – Dimensionality of the vectors.
n (int) – Number of vectors to superpose in the network.
 Returns
Tuple (net, inputs, output) where net is the implemented
nengo.Network
, inputs a sequence of length n of inputs to the network, and output the network output. Return type
tuple

implement_binding
(n_neurons_per_d, d, unbind_left, unbind_right)[source]¶ Implement neural network for binding vectors.
 Parameters
n_neurons_per_d (int) – Neurons to use per dimension.
d (int) – Dimensionality of the vectors.
unbind_left (bool) – Whether the left input should be unbound from the right input.
unbind_right (bool) – Whether the right input should be unbound from the left input.
 Returns
Tuple (net, inputs, output) where net is the implemented
nengo.Network
, inputs a sequence of the left and the right input in that order, and output the network output. Return type
tuple

absorbing_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ TVTB has no absorbing element except the zero vector.
Always raises a
NotImplementedError
.

identity_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the identity element of dimensionality d.
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness) – This argument has no effect because the identity of the TVTB algebra is twosided.
 Returns
Identity element.
 Return type
(d,) ndarray

zero_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the zero element of dimensionality d.
The zero element produces itself when bound to a different vector. For VTB this is the zero vector.
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness, optional) – This argument has no effect because the zero element of the VTB algebra is twosided.
 Returns
Zero element.
 Return type
(d,) ndarray


class
nengo_spa.algebras.
VtbAlgebra
[source]¶ Vectorderived Transformation Binding (VTB) algebra.
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 twosided identities and inverses.Additional information about VTB can be found in
See also

is_valid_dimensionality
(d)[source]¶ Checks whether d is a valid vector dimensionality.
For VTB all square numbers are valid dimensionalities.
 Parameters
d (int) – Dimensionality
 Returns
True, if d is a valid vector dimensionality for the use with the algebra.
 Return type
bool

make_unitary
(v)[source]¶ Returns a unitary vector based on the vector v.
A unitary vector does not change the length of a vector it is bound to.
 Parameters
v ((d,) ndarray) – Vector to base unitary vector on.
 Returns
Unitary vector.
 Return type
ndarray

superpose
(a, b)[source]¶ Returns the superposition of a and b.
This is commonly elementwise addition.
 Parameters
a ((d,) ndarray) – Left operand in superposition.
b ((d,) ndarray) – Right operand in superposition.
 Returns
Superposed vector.
 Return type
(d,) ndarray

bind
(a, b)[source]¶ Returns the binding of a and b.
The resulting vector should in most cases be dissimilar to both inputs.
 Parameters
a ((d,) ndarray) – Left operand in binding.
b ((d,) ndarray) – Right operand in binding.
 Returns
Bound vector.
 Return type
(d,) ndarray

invert
(v, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Invert vector v.
A vector bound to its inverse will result in the identity vector.
VTB has a right inverse only.
Deprecated since version 1.2.0: Calling this method with the default
sidedness=ElementSidedness.TWO_SIDED
returns the right inverse for backwards compatibility, but has been deprecated and will be removed in the next major release. Parameters
v ((d,) ndarray) – Vector to invert.
sidedness (ElementSidedness) – Must be set to
ElementSidedness.RIGHT
.
 Returns
Right inverse of vector.
 Return type
(d,) ndarray

get_binding_matrix
(v, swap_inputs=False)[source]¶ Returns the transformation matrix for binding with a fixed vector.
 Parameters
v ((d,) ndarray) – Fixed vector to derive binding matrix for.
swap_inputs (bool, optional) – By default the matrix will be such that v becomes the right operand in the binding. By setting swap_inputs, the matrix will be such that v becomes the left operand. For binding operations that are commutative (such as circular convolution), this has no effect.
 Returns
Transformation matrix to perform binding with v.
 Return type
(d, d) ndarray

get_swapping_matrix
(d)[source]¶ Get matrix to swap operands in bound state.
 Parameters
d (int) – Dimensionality of vector.
 Returns
Matrix to multiply with a vector to switch left and right operand in bound state.
 Return type
(d, d) ndarry

get_inversion_matrix
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Returns the transformation matrix for inverting a vector.
VTB has a right inverse only.
Deprecated since version 1.2.0: Calling this method with the default
sidedness=ElementSidedness.TWO_SIDED
returns the right transformation matrix for the right inverse for backwards compatibility, but has been deprecated and will be removed in the next major release. Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness) – Must be set to
ElementSidedness.RIGHT
.
 Returns
Transformation matrix to invert a vector.
 Return type
(d, d) ndarray

implement_superposition
(n_neurons_per_d, d, n)[source]¶ Implement neural network for superposing vectors.
 Parameters
n_neurons_per_d (int) – Neurons to use per dimension.
d (int) – Dimensionality of the vectors.
n (int) – Number of vectors to superpose in the network.
 Returns
Tuple (net, inputs, output) where net is the implemented
nengo.Network
, inputs a sequence of length n of inputs to the network, and output the network output. Return type
tuple

implement_binding
(n_neurons_per_d, d, unbind_left, unbind_right)[source]¶ Implement neural network for binding vectors.
 Parameters
n_neurons_per_d (int) – Neurons to use per dimension.
d (int) – Dimensionality of the vectors.
unbind_left (bool) – Whether the left input should be unbound from the right input.
unbind_right (bool) – Whether the right input should be unbound from the left input.
 Returns
Tuple (net, inputs, output) where net is the implemented
nengo.Network
, inputs a sequence of the left and the right input in that order, and output the network output. Return type
tuple

absorbing_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ VTB has no absorbing element except the zero vector.
Always raises a
NotImplementedError
.

identity_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the identity element of dimensionality d.
VTB has a right identity only.
Deprecated since version 1.2.0: Calling this method with the default
sidedness=ElementSidedness.TWO_SIDED
returns the right identity for backwards compatibility, but has been deprecated and will be removed in the next major release. Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness) – Must be set to
ElementSidedness.RIGHT
.
 Returns
Right identity element.
 Return type
(d,) ndarray

zero_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the zero element of dimensionality d.
The zero element produces itself when bound to a different vector. For VTB this is the zero vector.
 Parameters
d (int) – Vector dimensionality.
sidedness (ElementSidedness, optional) – This argument has no effect because the zero element of the VTB algebra is twosided.
 Returns
Zero element.
 Return type
(d,) ndarray
