# nengo_spa.algebras¶

Algebras define the specific superposition and (un)binding operations.

 AbstractAlgebra Abstract base class for algebras. HrrAlgebra Holographic Reduced Representations (HRRs) algebra. VtbAlgebra Vector-derived Transformation Binding (VTB) 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 True, if d is a valid vector dimensionality for the use with the algebra. 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. Unitary vector. ndarray
superpose(a, b)[source]

Returns the superposition of a and b.

Parameters: a ((d,) ndarray) – Left operand in superposition. b ((d,) ndarray) – Right operand in superposition. Superposed vector. (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. Bound vector. (d,) ndarray
invert(v)[source]

Invert vector v.

A vector bound to its inverse will result in the identity vector.

Parameters: v ((d,) ndarray) – Vector to invert. Inverted vector. (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. Transformation matrix to perform binding with v. (d, d) ndarray
get_inversion_matrix(d)[source]

Returns the transformation matrix for inverting a vector.

Parameters: d (int) – Vector dimensionality (determines the matrix size). Transformation matrix to invert a vector. (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. 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. 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. 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. tuple
absorbing_element(d)[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. Standard absorbing element. (d,) ndarray
identity_element(d)[source]

Return the identity element of dimensionality d.

The identity does not change the vector it is bound to.

Parameters: d (int) – Vector dimensionality. Identity element. (d,) ndarray
zero_element(d)[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.

Parameters: d (int) – Vector dimensionality. Zero element. (d,) ndarray
class nengo_spa.algebras.HrrAlgebra[source]

Holographic Reduced Representations (HRRs) algebra.

Uses element-wise 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 True, if d is a valid vector dimensionality for the use with the algebra. 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. Unitary vector. ndarray
superpose(a, b)[source]

Returns the superposition of a and b.

Parameters: a ((d,) ndarray) – Left operand in superposition. b ((d,) ndarray) – Right operand in superposition. Superposed vector. (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. Bound vector. (d,) ndarray
invert(v)[source]

Invert vector v.

A vector bound to its inverse will result in the identity vector.

Parameters: v ((d,) ndarray) – Vector to invert. Inverted vector. (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. Transformation matrix to perform binding with v. (d, d) ndarray
get_inversion_matrix(d)[source]

Returns the transformation matrix for inverting a vector.

Parameters: d (int) – Vector dimensionality (determines the matrix size). Transformation matrix to invert a vector. (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. 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. 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. 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. tuple
absorbing_element(d)[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. Standard absorbing element. (d,) ndarray
identity_element(d)[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. Identity element. (d,) ndarray
zero_element(d)[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. Zero element. (d,) ndarray
class nengo_spa.algebras.VtbAlgebra[source]

Vector-derived 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$$.

Note that VTB requires the vector dimensionality to be square.

The VTB binding operation is neither associative nor commutative.

Publications with further information are forthcoming.

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 True, if d is a valid vector dimensionality for the use with the algebra. 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. Unitary vector. ndarray
superpose(a, b)[source]

Returns the superposition of a and b.

Parameters: a ((d,) ndarray) – Left operand in superposition. b ((d,) ndarray) – Right operand in superposition. Superposed vector. (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. Bound vector. (d,) ndarray
invert(v)[source]

Invert vector v.

A vector bound to its inverse will result in the identity vector.

Parameters: v ((d,) ndarray) – Vector to invert. Inverted vector. (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. Transformation matrix to perform binding with v. (d, d) ndarray
get_swapping_matrix(d)[source]

Get matrix to swap operands in bound state.

Parameters: d (int) – Dimensionality of vector. Matrix to multiply with a vector to switch left and right operand in bound state. (d, d) ndarry
get_inversion_matrix(d)[source]

Returns the transformation matrix for inverting a vector.

Parameters: d (int) – Vector dimensionality (determines the matrix size). Transformation matrix to invert a vector. (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. 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. 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. 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. tuple
absorbing_element(d)[source]

VTB has no absorbing element except the zero vector.

identity_element(d)[source]

Return the identity element of dimensionality d.

The identity does not change the vector it is bound to.

Parameters: d (int) – Vector dimensionality. Identity element. (d,) ndarray
zero_element(d)[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. Zero element. (d,) ndarray