 Getting started
 User Guide
 Examples
 API reference
 Developer Guide
Note
This documentation is for a development version. Click here for the latest stable release (v1.3.0).
nengo_spa.algebras¶
The following items are reexported by nengo_spa.algebras
:
Abstract base class for algebras. 

Definition of constants for common properties of vectors in an algebra. 


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

Vector properties supported by the 

Vectorderived Transformation Binding (VTB) algebra. 

Vector properties supported by the 

Transposed Vectorderived Transformation Binding (TVTB) algebra. 

Vector properties supported by the 
Base classes¶
Abstract base class for algebras. 

Abstract base class for implementing signs for an algebra. 

Definition of constants for common properties of vectors in an algebra. 


The side in a binary operation for which a special element’s properties hold. 

A generic sign implementation. 

class
nengo_spa.algebras.base.
ElementSidedness
(value)[source]¶ Bases:
enum.Enum
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.base.
AbstractAlgebra
[source]¶ Bases:
object
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
 dint
Dimensionality
 Returns
 bool
True, if d is a valid vector dimensionality for the use with the algebra.

create_vector
(d, properties, *, rng=None)[source]¶ Create a vector fulfilling given properties in the algebra.
Valid properties and combinations thereof depend on the concrete algebra. It is suggested that the properties is either a set of str (if order does not matter) or a list of str (if order does matter). Use the constants defined in
CommonProperties
where appropriate. Parameters
 dint
Vector dimensionality
 properties
Definition of properties for the vector to fulfill. Type and specification format depend on the concrete algbra, but it is suggested to use either a set or list of str (depending on whether order of properties matters) utilizing the constants defined in
CommonProperties
where applicable. rngnumpy.random.RandomState, optional
The random number generator to use to create the vector.
 Returns
 ndarray
Random vector with desired properties.

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
 ndarray
Unitary vector.

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
 (d,) ndarray
Superposed vector.

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
 (d,) ndarray
Bound vector.

binding_power
(v, exponent)[source]¶ Returns the binding power of v using the exponent.
For a positive exponent, the binding power is defined as binding (exponent1) times bindings of v to itself. For a negative exponent, the binding power is the approximate inverse bound to itself according to the prior definition. Depending on the algebra, fractional exponents might be valid or return a ValueError, if not. Usually, a fractional binding power will require that v has a positive sign.
Note the following special exponents:
an exponent of 1 will return the approximate inverse,
an exponent of 0 will return the identity vector,
and an exponent of 1 will return v itself.
The default implementation supports integer exponents only and will apply the
bind
method multiple times. It requires the algebra to have a left identity. Parameters
 v(d,) ndarray
Vector to bind repeatedly to itself.
 exponentint or float
Exponent of the binding power.
 Returns
 (d,) ndarray
Binding power of v.
See also

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.
 sidednessElementSidedness, optional
Side in the binding operation on which the returned value acts as inverse.
 Returns
 (d,) ndarray
Inverted vector.

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_inputsbool, 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
 (d, d) ndarray
Transformation matrix to perform binding with v.

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
 dint
Vector dimensionality (determines the matrix size).
 sidednessElementSidedness, optional
Side in the binding operation on which a transformed vectors acts as inverse.
 Returns
 (d, d) ndarray
Transformation matrix to invert a vector.

implement_superposition
(n_neurons_per_d, d, n)[source]¶ Implement neural network for superposing vectors.
 Parameters
 n_neurons_per_dint
Neurons to use per dimension.
 dint
Dimensionality of the vectors.
 nint
Number of vectors to superpose in the network.
 Returns
 tuple
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.

implement_binding
(n_neurons_per_d, d, unbind_left, unbind_right)[source]¶ Implement neural network for binding vectors.
 Parameters
 n_neurons_per_dint
Neurons to use per dimension.
 dint
Dimensionality of the vectors.
 unbind_leftbool
Whether the left input should be unbound from the right input.
 unbind_rightbool
Whether the right input should be unbound from the left input.
 Returns
 tuple
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.

sign
(v)[source]¶ Returns the sign of v defined by the algebra.
The exact definition of the sign depends on the concrete algebra, but should be analogous to the sign of a (complex) number in so far that binding two vectors with the same sign produces a “positive” vector. There might, however, be multiple types of negative signs, where binding vectors with different types of negative signs will produce another “negative” vector.
Furthermore, if the algebra supports fractional binding powers, it should do so for all “nonnegative” vectors, but not “negative” vectors.
If an algebra does not have the notion of a sign, it may raise a
NotImplementedError
. Parameters
 v(d,) ndarray
Vector to determine sign of.
 Returns
 AbstractSign
The sign of the input vector.
See also

abs
(v)[source]¶ Returns the absolute vector of v defined by the algebra.
The exact definition of “absolute vector” may depend on the concrete algebra. It should be a “positive” vector (see
sign
) that relates to the input vector.The default implementation requires that the possible signs of the algebra correspond to actual vectors within the algebra. It will bind the inverse of the sign vector (from the left side) to the vector v.
If an algebra does not have the notion of a sign or absolute vector, it may raise a
NotImplementedError
. Parameters
 v(d,) ndarray
Vector to obtain the absolute vector of.
 Returns
 (d,) ndarray
The absolute vector relating to the input vector.

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
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
Side in the binding operation on which the element absorbs.
 Returns
 (d,) ndarray
Standard absorbing element.

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
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
Side in the binding operation on which the element acts as identity.
 Returns
 (d,) ndarray
Identity element.

negative_identity_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Returns the negative identity element of dimensionality d.
The negative identity only changes the sign of the vector it is bound to.
Some algebras might not have a negative identity element (or even the notion of a sign). In that case a :py:class`NotImplementedError` may be raised.
 Parameters
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
Side in the binding operation on which the element acts as negative identity.
 Returns
 (d,) ndarray
Negative identity element.

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
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
Side in the binding operation on which the element acts as zero.
 Returns
 (d,) ndarray
Zero element.


class
nengo_spa.algebras.base.
AbstractSign
[source]¶ Bases:
abc.ABC
Abstract base class for implementing signs for an algebra.

class
nengo_spa.algebras.base.
GenericSign
(sign)[source]¶ Bases:
nengo_spa.algebras.base.AbstractSign
A generic sign implementation.
 Parameters
 sign1, 0, 1, None
The represented sign. None is used for an indefinite sign.

class
nengo_spa.algebras.base.
CommonProperties
[source]¶ Bases:
object
Definition of constants for common properties of vectors in an algebra.
Use these for best interoperability between algebras.

UNITARY
= 'unitary'¶ A unitary vector does not change the length of a vector it is bound to.

POSITIVE
= 'positive'¶ A positive vector does not change the sign of a vector it is bound to.
A positive vector allows for fractional binding powers.

Holographic reduced representations (HRR)¶
Holographic Reduced Representations (HRRs) algebra. 

Vector properties supported by the 


Represents a sign in the 

class
nengo_spa.algebras.hrr_algebra.
HrrAlgebra
[source]¶ Bases:
nengo_spa.algebras.base.AbstractAlgebra
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
 dint
Dimensionality
 Returns
 bool
True, if d is a valid vector dimensionality for the use with the algebra.

create_vector
(d, properties, *, rng=None)[source]¶ Create a vector fulfilling given properties in the algebra.
 Parameters
 dint
Vector dimensionality
 propertiesset of str
Definition of properties for the vector to fulfill. Valid set elements are constants defined in
HrrProperties
. rngnumpy.random.RandomState, optional
The random number generator to use to create the vector.
 Returns
 ndarray
Random vector with desired properties.

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
 ndarray
Unitary vector.

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
 (d,) ndarray
Superposed vector.

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
 (d,) ndarray
Bound vector.

binding_power
(v, exponent)[source]¶ Returns the binding power of v using the exponent.
The binding power is defined as binding (exponent1) times bindings of v to itself. Fractional binding powers are supported.
Note the following special exponents:
an exponent of 1 will return the approximate inverse,
an exponent of 0 will return the identity vector,
and an exponent of w1cne will return v itself.
The following relations hold for integer exponents, and for unitary vectors:
\(v^a \circledast v^b = v^{a+b}\),
\((v^a)^b = v^{ab}\).
If \(a \geq 0\) and \(b \geq 0\), then the first relation holds also for nonunitary vectors with real exponents.
 Parameters
 v(d,) ndarray
Vector to bind repeatedly to itself.
 exponentint or float
Exponent of the binding power.
 Returns
 (d,) ndarray
Binding power of v.
See also

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
. Parameters
 v(d,) ndarray
Vector to invert.
 sidednessElementSidedness, optional
This argument has no effect because the HRR algebra is commutative and the inverse is twosided.
 Returns
 (d,) ndarray
Inverted vector.
Examples
For the vector
[1, 2, 3, 4, 5]
, the inverse is[1, 5, 4, 3, 2]
.

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_inputsbool, 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
 (d, d) ndarray
Transformation matrix to perform binding with v.

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

implement_superposition
(n_neurons_per_d, d, n)[source]¶ Implement neural network for superposing vectors.
 Parameters
 n_neurons_per_dint
Neurons to use per dimension.
 dint
Dimensionality of the vectors.
 nint
Number of vectors to superpose in the network.
 Returns
 tuple
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.

implement_binding
(n_neurons_per_d, d, unbind_left, unbind_right)[source]¶ Implement neural network for binding vectors.
 Parameters
 n_neurons_per_dint
Neurons to use per dimension.
 dint
Dimensionality of the vectors.
 unbind_leftbool
Whether the left input should be unbound from the right input.
 unbind_rightbool
Whether the right input should be unbound from the left input.
 Returns
 tuple
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.

sign
(v)[source]¶ Returns the HRR sign of v.
See
AbstractAlgebra.sign
for general information on the notion of a sign for algbras, andHrrSign
for details specific to HRRs. Parameters
 v(d,) ndarray
Vector to determine sign of.
 Returns
 HrrSign
The sign of the input vector.

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
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
This argument has no effect because the HRR algebra is commutative and the standard absorbing element is twosided.
 Returns
 (d,) ndarray
Standard absorbing element.

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
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
This argument has no effect because the HRR algebra is commutative and the identity is twosided.
 Returns
 (d,) ndarray
Identity element.

negative_identity_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the negative identity element of dimensionality d.
The negative identity element for circular convolution is the vector \((1, 0, \dots, 0)^{\top}\).
 Parameters
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
This argument has no effect because the HRR algebra is commutative and the identity is twosided.
 Returns
 (d,) ndarray
Negative identity element.

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
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
This argument has no effect because the HRR algebra is commutative and the zero element is twosided.
 Returns
 (d,) ndarray
Zero element.

class
nengo_spa.algebras.hrr_algebra.
HrrSign
(dc_sign, nyquist_sign)[source]¶ Bases:
nengo_spa.algebras.base.AbstractSign
Represents a sign in the
HrrAlgebra
.For odd dimensionalities, the sign is equal to the sign of the DC component of the Fourier representation of the vector. For even dimensionalities the sign is constituted out of the signs of the DC component and Nyquist frequency. Thus, for even dimensionalities, there is a total of four subsigns excluding zero. The overall sign is considered positive if the DC component is positive and the Nyquist component is nonnegative; the sign is considered negative if either component is negative; and the sign is considered zero if both are zero. Binding two Semantic Pointers with the same subsign will yield a positive Semantic Pointer. See the table below for details.
¶ Sign (DC, Nyquist)
+ (+1, +1)
− (+1, 1)
− (1, +1)
− (−1, 1)
(0, 0)
+ (+1, +1)
+ (+1, +1)
− (+1, 1)
− (−1, +1)
− (−1, 1)
(0, 0)
− (+1, 1)
+ (1, +1)
− (−1, 1)
− (−1, +1)
(0, 0)
− (−1, +1)
+ (1, +1)
− (+1, 1)
(0, 0)
− (−1, 1)
+ (1, +1)
(0, 0)
(0, 0)
(0, 0)
 Parameters
 dc_signint
Sign of the DC component.
 nyquist_signint
Sign of the Nyquist frequency component. Will be set to the dc_sign if zero.

dc_sign
¶

nyquist_sign
¶

to_vector
(d)[source]¶ Return the vector in the algebra corresponding to the sign.
DC sign
Nyquist sign
Vector
1
1
[ 1, 0, 0, …] (identity)
1
1
[ 0, 1, 0, 0, …]
1
1
[ 0, 1, 0, …]
1
1
[1, 0, 0, 0, …] (negative identity)
0
0
[ 0, 0, 0, …] (zero)
 Parameters
 dint
Vector dimensionality.
 Returns
 (d,) ndarray
Vector corresponding to the sign.

class
nengo_spa.algebras.hrr_algebra.
HrrProperties
[source]¶ Bases:
object
Vector properties supported by the
HrrAlgebra
.
UNITARY
= 'unitary'¶ A unitary vector does not change the length of a vector it is bound to.

POSITIVE
= 'positive'¶ A positive vector does not change the sign of a vector it is bound to.
A positive vector allows for fractional binding powers.

Vectorderived transformation binding (VTB)¶
Vectorderived Transformation Binding (VTB) algebra. 

Vector properties supported by the 


Represents a sign in the 

class
nengo_spa.algebras.vtb_algebra.
VtbAlgebra
[source]¶ Bases:
nengo_spa.algebras.base.AbstractAlgebra
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 & \ddots \end{array}\right] x\end{split}\]with \(d'\) blocks
where
\[\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
 dint
Dimensionality
 Returns
 bool
True, if d is a valid vector dimensionality for the use with the algebra.

create_vector
(d, properties, *, rng=None)[source]¶ Create a vector fulfilling given properties in the algebra.
Creating positive vectors requires SciPy.
 Parameters
 dint
Vector dimensionality
 propertiesset of str
Definition of properties for the vector to fulfill. Valid set elements are constants defined in
VtbProperties
. rngnumpy.random.RandomState, optional
The random number generator to use to create the vector.
 Returns
 ndarray
Random vector with desired properties.

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
 ndarray
Unitary vector.

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
 (d,) ndarray
Superposed vector.

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
 (d,) ndarray
Bound vector.

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.
 sidednessElementSidedness
Must be set to
ElementSidedness.RIGHT
.
 Returns
 (d,) ndarray
Right inverse of vector.

binding_power
(v, exponent)[source]¶ Returns the binding power of v using the exponent.
The binding power is defined as binding (exponent1) times bindings of v to itself.
Fractional binding powers are supported for “positive” vectors if SciPy is available.
Note the following special exponents:
an exponent of 1 will return the inverse,
an exponent of 0 will return the identity vector,
and an exponent of 1 will return v itself.
Be aware that the binding power for the VTB algebra does not satisfy the usual properties of exponentiation:
\(\mathcal{B}(v^a, v^b) = v^{a+b}\) does not hold,
\((v^a)^b = v^{ab}\) does not hold.
 Parameters
 v(d,) ndarray
Vector to bind repeatedly to itself.
 exponentint or float
Exponent of the binding power.
 Returns
 (d,) ndarray
Binding power of v.
See also

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_inputsbool, 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
 (d, d) ndarray
Transformation matrix to perform binding with v.

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

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
 dint
Vector dimensionality.
 sidednessElementSidedness
Must be set to
ElementSidedness.RIGHT
.
 Returns
 (d, d) ndarray
Transformation matrix to invert a vector.

implement_superposition
(n_neurons_per_d, d, n)[source]¶ Implement neural network for superposing vectors.
 Parameters
 n_neurons_per_dint
Neurons to use per dimension.
 dint
Dimensionality of the vectors.
 nint
Number of vectors to superpose in the network.
 Returns
 tuple
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.

implement_binding
(n_neurons_per_d, d, unbind_left, unbind_right)[source]¶ Implement neural network for binding vectors.
 Parameters
 n_neurons_per_dint
Neurons to use per dimension.
 dint
Dimensionality of the vectors.
 unbind_leftbool
Whether the left input should be unbound from the right input.
 unbind_rightbool
Whether the right input should be unbound from the left input.
 Returns
 tuple
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.

sign
(v)[source]¶ See
AbstractAlgebra.sign
.

abs
(v)[source]¶ See
AbstractAlgebra.abs
.

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
 dint
Vector dimensionality.
 sidednessElementSidedness
Must be set to
ElementSidedness.RIGHT
.
 Returns
 (d,) ndarray
Right identity element.

negative_identity_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the negative identity element of dimensionality d.
VTB has a right negative identity only.
 Parameters
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
Must be set to
ElementSidedness.RIGHT
.
 Returns
 (d,) ndarray
Negative identity element.

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
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
This argument has no effect because the zero element of the VTB algebra is twosided.
 Returns
 (d,) ndarray
Zero element.


class
nengo_spa.algebras.vtb_algebra.
VtbSign
(sign)[source]¶ Bases:
nengo_spa.algebras.base.GenericSign
Represents a sign in the
VtbAlgebra
.The sign depends on the symmetry and positive/negative definiteness of the binding matrix derived from the vector. For all nonsymmetric matrices, the sign is indefinite. It is also indefinite, if the matrices’ eigenvalues have different signs. A symmetric, positive (negative) definite binding matrix corresponds to a positive (negative) sign (equivalent to all eigenvalues being greater than 0, respectively lower than 0). If all eigenvalues are equal to 0, the sign is also 0.

class
nengo_spa.algebras.vtb_algebra.
VtbProperties
[source]¶ Bases:
object
Vector properties supported by the
VtbAlgebra
.
UNITARY
= 'unitary'¶ A unitary vector does not change the length of a vector it is bound to.

POSITIVE
= 'positive'¶ A positive vector does not change the sign of a vector it is bound to.
A positive vector allows for fractional binding powers.

Transposed vectorderived transformation binding (TVTB)¶
Transposed Vectorderived Transformation Binding (TVTB) algebra. 

Vector properties supported by the 


Represents a sign in the 

class
nengo_spa.algebras.tvtb_algebra.
TvtbAlgebra
[source]¶ Bases:
nengo_spa.algebras.base.AbstractAlgebra
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 & \ddots \end{array}\right] x\end{split}\]with \(d'\) blocks
where
\[\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
 dint
Dimensionality
 Returns
 bool
True, if d is a valid vector dimensionality for the use with the algebra.

create_vector
(d, properties, *, rng=None)[source]¶ Create a vector fulfilling given properties in the algebra.
Creating positive vectors requires SciPy.
 Parameters
 dint
Vector dimensionality
 propertiesset of str
Definition of properties for the vector to fulfill. Valid set elements are constants defined in
TvtbProperties
. rngnumpy.random.RandomState, optional
The random number generator to use to create the vector.
 Returns
 ndarray
Random vector with desired properties.

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
 ndarray
Unitary vector.

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
 (d,) ndarray
Superposed vector.

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
 (d,) ndarray
Bound vector.

binding_power
(v, exponent)[source]¶ Returns the binding power of v using the exponent.
The binding power is defined as binding (exponent1) times bindings of v to itself.
Fractional binding powers are supported for “positive” vectors if SciPy is available.
Note the following special exponents:
an exponent of 1 will return the inverse,
an exponent of 0 will return the identity vector,
and an exponent of 1 will return v itself.
The following relations hold for integer exponents:
\(\mathcal{B}(v^a, v^b) = v^{a+b}\),
\((v^a)^b = v^{ab}\).
(Technically, these relations also hold for positive unitary vectors, but the only such vector is the identity vector.)
 Parameters
 v(d,) ndarray
Vector to bind repeatedly to itself.
 exponentint or float
Exponent of the binding power.
 Returns
 (d,) ndarray
Binding power of v.
See also

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.
 sidednessElementSidedness
This argument has no effect because the inverse of the TVTB algebra is twosided.
 Returns
 (d,) ndarray
Inverse of vector.

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_inputsbool, 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
 (d, d) ndarray
Transformation matrix to perform binding with v.

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

implement_superposition
(n_neurons_per_d, d, n)[source]¶ Implement neural network for superposing vectors.
 Parameters
 n_neurons_per_dint
Neurons to use per dimension.
 dint
Dimensionality of the vectors.
 nint
Number of vectors to superpose in the network.
 Returns
 tuple
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.

implement_binding
(n_neurons_per_d, d, unbind_left, unbind_right)[source]¶ Implement neural network for binding vectors.
 Parameters
 n_neurons_per_dint
Neurons to use per dimension.
 dint
Dimensionality of the vectors.
 unbind_leftbool
Whether the left input should be unbound from the right input.
 unbind_rightbool
Whether the right input should be unbound from the left input.
 Returns
 tuple
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.

sign
(v)[source]¶ See
AbstractAlgebra.sign
.

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
 dint
Vector dimensionality.
 sidednessElementSidedness
This argument has no effect because the identity of the TVTB algebra is twosided.
 Returns
 (d,) ndarray
Identity element.

negative_identity_element
(d, sidedness=<ElementSidedness.TWO_SIDED: 'twosided'>)[source]¶ Return the negative identity element of dimensionality d.
 Parameters
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
This argument has no effect because the negative identity of the TVTB algebra is twosided.
 Returns
 (d,) ndarray
Negative identity element.

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
 dint
Vector dimensionality.
 sidednessElementSidedness, optional
This argument has no effect because the zero element of the VTB algebra is twosided.
 Returns
 (d,) ndarray
Zero element.


class
nengo_spa.algebras.tvtb_algebra.
TvtbSign
(sign)[source]¶ Bases:
nengo_spa.algebras.base.GenericSign
Represents a sign in the
TvtbAlgebra
.The sign depends on the symmetry and positive/negative definiteness of the binding matrix derived from the vector. For all nonsymmetric matrices, the sign is indefinite. It is also indefinite, if the matrices’ eigenvalues have different signs. A symmetric, positive (negative) definite binding matrix corresponds to a positive (negative) sign (equivalent to all eigenvalues being greater than 0, respectively lower than 0). If all eigenvalues are equal to 0, the sign is also 0.

class
nengo_spa.algebras.tvtb_algebra.
TvtbProperties
[source]¶ Bases:
object
Vector properties supported by the
TvtbAlgebra
.
UNITARY
= 'unitary'¶ A unitary vector does not change the length of a vector it is bound to.

POSITIVE
= 'positive'¶ A positive vector does not change the sign of a vector it is bound to.
A positive vector allows for fractional binding powers.
